企业官网建设流程全解析

Home Assistant 17TRACK Get Packages 动作完全指南：用seventeentrack.get_packages查询包裹数据

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本指南聚焦 Home Assistant 官方文档中的17TRACK: Get packages动作（seventeentrack.get_packages），讲解如何通过 UI 与 YAML 两种方式调用它查询 17Track 账户中的包裹最新数据，如何按状态过滤结果、读取返回的响应数据结构，以及如何把它接入自动化与仪表盘实现「今日送达提醒」「在途包裹概览」等实战场景。读完你将掌握该动作的全部配置参数、返回值字段与源码层面的实现依据，能够直接编写可运行的自动化与脚本。

动作概览：它能做什么

seventeentrack.get_packages是 17TRACK 集成（seventeentrackdomain）提供的一个动作（action），其作用是查询 17Track API 并返回你账户中已跟踪包裹的最新数据。根据动作文档的描述，你可以把结果限制在特定状态的包裹（例如在途、待取件），这在自动化或脚本中非常实用——典型场景是发送一条通知，列出今天所有「正在派送（out for delivery）」的包裹。

从仓库结构看，该动作与 seventeentrack.add_package（按单号添加包裹）、seventeentrack.archive_package（归档包裹）共同构成 17TRACK 集成的动作体系：添加 → 查询 → 归档，三者配合即可在 Home Assistant 内完成包裹跟踪的完整闭环。

动作文档（source/_actions/seventeentrack.get_packages.markdown）将description明确为 "Queries the 17Track API for the latest package data"，并在related_actions中声明了与 add/archive 两个动作的关联关系。

前置条件：17TRACK 集成

使用该动作前，需要先通过配置流（config flow）完成 17TRACK 集成接入。集成文档（source/_integrations/seventeentrack.markdown）说明了以下关键信息：

• 集成允许用户获取与 17track.net 账户绑定的包裹数据；
• 集成会创建汇总传感器（显示处于某状态如 "In Transit" 的包裹数量），以及账户内每个包裹的独立传感器；
• ha_iot_class: Cloud Polling，即采用云端轮询方式获取数据；
• 集成类型为service，通过ha_config_flow: true启用配置流。

⚠️重要提示（源自官方集成文档）：虽然 17track.net 网站声明账户密码不能超过 16 个字符，但用户技术上可以设置更长的密码，然而这些超长密码无法与集成使用的 API 配合工作。因此请确保你的 17track.net 密码不超过 16 个字符。

获取 config_entry_id

无论走 UI 还是 YAML 路径，调用动作时都需要指定 17Track 服务（即config_entry_id）。官方集成文档提供了获取方法：进入Settings > Devices & services，选择 17Track 集成，点击右上角三个点的菜单，选择Copy entry ID（复制条目 ID）。

方式一：从用户界面（UI）使用

如果你更习惯可视化方式构建自动化，动作文档对应的 UI 操作路径如下（actions/ui_header.md也确认了该动作支持 UI 引导式配置）：

1. 进入Settings > Automations & scenes；
2. 打开一个已有的自动化或脚本，或选择Create automation > Create new automation；
3. 如果是新建自动化，在When区域添加一个触发器；脚本则不需要触发器（脚本由其他事物调用时才会运行）；
4. 在Then do区域选择Add action；
5. 在搜索框中搜索并选择17TRACK: Get packages；
6. 选择要查询的17Track service，并可选择要返回的Package states（包裹状态）；
7. 在Response variable（响应变量）字段中输入一个名称来存储数据，例如result；
8. 选择Save（保存）。

动作不支持 targets

该动作不支持目标（targets）。在 UI 中，你通过17Track service字段选择 17Track 服务，而不是通过选择区域、设备、实体或标签来指定目标。这意味着它只能针对已配置的 17TRACK 集成条目执行，不能按实体定向。

UI 选项一览

方式二：在 YAML 中使用

如果你直接在 YAML 中工作，或想确切了解 Home Assistant 在底层做了什么，动作文档给出了完整的 YAML 技术参考（actions/yaml_header.md对此进行了说明：该部分列出 YAML 中使用的字段名、类型以及哪些是必填的）。

基本示例

action: seventeentrack.get_packages data: config_entry_id: 2b4be47a1fa7c3764f14cf756dc98991 package_state: - delivered - in_transit response_variable: result

执行后，匹配的包裹会存储在result响应变量中，位于result.packages下。

YAML 选项详解

package_state 可选值

动作文档明确列出了package_state支持的一个或多个值：

• not_found（未找到）
• in_transit（在途）
• expired（已过期）
• ready_to_be_picked_up（待取件）
• undelivered（未送达）
• delivered（已送达）
• alert（异常提醒）

值得注意的是，集成文档在「Package statuses」章节列出的状态为：Not found、In transit、Expired、Ready to be picked up、Undelivered、Delivered、Returned（已退回）。集成会为每个状态创建一个传感器，传感器显示的值即为处于该状态的包裹数量。因此在实际使用中，package_state的状态维度与集成传感器状态体系一致，你可以按需组合过滤，例如只查询delivered和in_transit。

响应数据结构（Response data）

动作返回一个packages列表，每个条目描述一个包裹，包含以下字段（源自动作文档）：

在模板（template）中可通过result.packages访问该列表，例如{{ result.packages | count }}统计包裹数量、{% for package in result.packages %}遍历每个包裹。

实战：自动化与仪表盘集成示例

示例一：仪表盘汇总卡片（官方集成文档示例）

集成文档提供了一个完整的实战场景：先创建一个基于触发器的模板传感器，每小时调用一次seventeentrack.get_packages统计在途包裹，再在仪表盘用 Markdown 卡片展示。

第一步：创建触发器型模板传感器：

template: - trigger: - trigger: time_pattern hours: /1 - trigger: homeassistant event: start action: - action: seventeentrack.get_packages data: config_entry_id: YOUR_CONFIG_ENTRY_ID package_state: - in_transit response_variable: result sensor: - name: "Packages in transit" unique_id: packages_in_transit state: "{{ result.packages | count }}" attributes: packages: "{{ result.packages }}"

这里使用了两个触发器：每小时（time_pattern）触发一次，以及 Home Assistant 启动（homeassistantevent: start）时触发，保证重启后立即刷新数据。包裹列表存入传感器属性packages中。

第二步：使用模板 Markdown 卡片列出所有在途包裹及其状态：

type: markdown title: Packages in transit content: > {% for package in state_attr('sensor.packages_in_transit', 'packages') %} - **{{ package.friendly_name }} ({{ package.tracking_number }}):** {{ package.info_text }} {% endfor %}

示例二：与添加/归档动作联动，构成完整跟踪闭环

• 用seventeentrack.add_package从订单确认邮件中解析出单号并自动添加跟踪（参考 add_package 动作文档 中的自动化示例）；
• 用seventeentrack.get_packages定期查询状态变化；
• 用seventeentrack.archive_package在包裹标记为已送达后自动归档（参考 archive_package 动作文档）。

快速测试：Try it yourself

动作文档附带的actions/try_it.md建议你亲自验证：打开Settings > Tools > Actions，搜索该动作，填写字段，然后选择Perform action（执行动作）。无需编写一行 YAML，即可在真实实体上看到效果。

常见问题排查方向

动作文档末尾的stuck.md提示了遇到问题时的通用排查思路。结合本动作特性，常见检查点包括：

• config_entry_id 是否正确：必须指向 17TRACK 集成条目的真实 ID，可通过 Settings > Devices & services 中集成菜单的 Copy entry ID 获取；
• 密码长度限制：若 API 鉴权失败，先确认 17track.net 账户密码不超过 16 个字符；
• 状态值拼写：package_state需使用文档列出的枚举值（如in_transit、ready_to_be_picked_up）；
• 响应变量命名冲突：response_variable名称在同一自动化/脚本中应保持唯一，避免被其他动作覆盖。

小结

seventeentrack.get_packages是 17TRACK 集成数据查询的核心入口：通过config_entry_id指定服务、用package_state按状态过滤、以response_variable承接返回的packages列表，配合模板传感器与 Markdown 卡片即可构建实时的包裹看板。结合 add/archive 两个兄弟动作，你可以在 Home Assistant 内完成从添加单号、状态监控到自动归档的完整包裹跟踪自动化闭环。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io