API Catalog

用途

API Catalog 是一个参考技能（reference skill），用于把外部 API 和服务连接到 Home Assistant。它面向需要从第三方服务拉取数据并在 Home Assistant 中使用的场景，提供认证方式、端点和可运行代码示例。

主要能力

该技能覆盖三种接入方法：

Node-RED：HTTP 请求节点流程，是启动最快的方式。
HA YAML：rest sensor 和 rest_command，适合简单的轮询场景。
自定义集成：完整的、可发布到 HACS 的 Python 组件（需配合 ha-integration 技能）。

技能按类别整理了参考文件：

能源与电力：references/energy-apis.md，覆盖 Tibber、Nordpool、Energi Data Service。
天气：references/weather-apis.md，覆盖 SMHI、OpenWeatherMap、yr.no、Tomorrow.io。
交通：references/transport-apis.md，覆盖 SL、Trafikverket、Resrobot、Entur（挪威）。
智能家居云：references/smarthome-apis.md，覆盖 Shelly Cloud、Tuya IoT、Philips Hue、IKEA Dirigera。
全球/其他：references/global-apis.md，覆盖 OpenAI、Spotify、Google Calendar、Telegram、GitHub。

认证模式一览：

API key 放在请求头：Authorization: Bearer {key} 或 X-API-Key: {key}，例如 Tibber、OpenAI。
API key 放在 URL：?appid={key} 追加到 URL，例如 OpenWeatherMap。
OAuth2：先获取 access token，再定期刷新，例如 Spotify、Google。
本地 token：在设备上一次性按键认证，例如 Philips Hue。
无认证：公开 API，无需凭据，例如 SMHI、yr.no、Nordpool。
Basic auth：用户名加密码的 Base64 编码，部分本地设备使用。

使用方式

技能给出的使用流程是：

用户按名称提到某个 API 或服务。
阅读对应的参考文件，了解认证设置和端点。
按用户选择的方法（Node-RED / YAML / 集成）生成可运行代码。
附带凭据设置说明。

输出方法：针对每个 API，按用户需要的方法生成代码——Node-RED 使用 http request 节点加 function 节点解析，再用 api-call-service 推送到 HA；HA YAML 在 configuration.yaml 下使用 rest sensor 平台或 rest_command；完整集成则使用 ha-integration 技能配合轮询集成模板。

文档给出的常见模式示例包括：

Node-RED 请求头携带 API key：

{ "type": "http request", "method": "GET", "url": "https://api.example.com/data", "headers": {"Authorization": "Bearer {{env.API_KEY}}"}, "ret": "obj" }

Node-RED 的 GraphQL（Tibber 风格）：

{ "type": "http request", "method": "POST", "url": "https://api.tibber.com/v1-beta/gql", "headers": { "Authorization": "Bearer {{env.TIBBER_TOKEN}}", "Content-Type": "application/json" }, "payload": "{"query": "{ viewer { homes { currentSubscription { priceInfo { current { total } } } } } }"}", "ret": "obj" }

HA YAML 的 REST sensor：

rest:

scan_interval: 300 resource: https://api.example.com/current headers: Authorization: !secret example_api_key sensor:
- name: "Example Value" value_template: "{{ value_json.data.value }}" unit_of_measurement: "°C"

适用场景

适用于需要把外部服务数据接入 Home Assistant 的用户，例如读取电价、天气、交通、智能家居云设备状态，或接入 OpenAI、Spotify、Google Calendar、Telegram、GitHub 等服务。用户可按自身技术偏好选择 Node-RED、YAML 或自定义集成。

限制与注意事项

文档强调一条“铁律”：凭据必须放在 secrets 中，绝不硬编码在流程或 YAML 里。API key 应放在 Node-RED credentials、ESPHome secrets.yaml 或 HA secrets.yaml 中，不要把真实 token 粘贴到聊天、会被导出的流程或提交到 git 的 YAML 中。

输出前检查清单包括：凭据使用 !secret（YAML）、Node-RED credentials 或环境变量，绝不硬编码；遵守速率限制（相应设置 scan_interval 或流程定时器）；包含错误处理（Node-RED catch 节点或 YAML timeout）；对 OAuth2 说明刷新 token 流程；注明使用的 API 端点及其返回的数据。

该技能可与 node-red 技能（用于流程 JSON 实现）、ha-yaml 技能（用于使用所取数据的 YAML 传感器和自动化）、ha-integration 技能（用于构建完整的可发布到 HACS 的 Python 集成）配合使用。

关于具体 API 的收费、价格、平台支持范围等信息，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项