Google Nest 集成可让你在 Home Assistant 中接入部分受支持的 Google Nest 设备。此集成使用 Smart Device Management API 和 Google Cloud Pub/Sub，高效监听设备状态变化和其他事件。有关 SDM API 支持的全部设备，请参阅支持的设备。

Home Assistant 目前支持以下设备类型：

• 气候
• 传感器
• 相机
• 活动

摄像头和门铃使用自动化和设备触发器处理事件，并使用媒体源在支持的设备上获取媒体图像。SDM API 目前不支持其他设备类型，例如烟雾与一氧化碳报警器或安防系统。

您可以控制向 Home Assistant 公开的信息和功能。您可以为任何特定设备授权单个设备、多个设备或不同级别的功能，例如运动事件、实时流。该集成足够灵活，可以根据您的允许进行调整。

#前提条件

• 自 2025 年 1 月 23 日起，Nest 设备访问控制台 Pub/Sub 设置流程已更改。 请确保您使用的是最新版本的 Home Assistant。

• Nest 智能设备管理 (SDM) API 需要 5 美元费用。购买前，请确保您的设备受支持。

• SDM API 还与某些 Google 帐号类型或安全设置不兼容，包括 Google Workspace 和高级保护计划。请参阅下面的已知限制。

#配置

要将 Nest 集成添加到 Home Assistant，请使用下面这个 My Home Assistant 按钮：

集成设置步骤将引导您完成配置 Google Cloud 项目、设备访问项目的过程，最后将您的帐户链接到 Home Assistant。确保您运行的是最新版本的 Home Assistant。

#气候

所有 Google Nest Thermostat 模型都公开为使用 SDM API 中的 Thermostat Traits 的“气候”实体。恒温器的状态变化通过 Cloud Pubsub 订阅者报告给 Home Assistant。

给定一个名为“Upstairs”的恒温器，然后使用“climate.upstairs”等名称创建气候实体

:::note 此功能通过以下权限启用：

• 允许家庭助理访问和控制您的恒温器

#传感器

所有 Google Nest Thermostat 模型都具有从 SDM API 公开的特征。传感器的初始值在启动时获取，然后使用 Cloud Pubsub 订阅者定期更新。传感器支持以下特征：

• 温度
• 湿度

给定一个名为“Upstairs”的恒温器，然后使用“sensor.upstairs_Temperature”或“sensor.upstairs_humidity”等名称创建传感器。

#相机

Home Assistant 支持所有 SDM API 功能。但是，每个摄像头或门铃设备都有一组不同的内置功能。摄像头设备具有以下实时流类型之一：

• RTSP：这些设备具有由 Home Assistant Core 提供服务的 HLS 流。这些相机支持服务器端“相机”操作，例如流录制或图像预览。请参阅低延迟 HLS，这是一个减少流延迟的绝佳选项。
• WebRTC：这些设备支持浏览器到相机的直接通信和超低延迟流。 图片概览卡 可以在网格中显示实时流，并将摄像头视图设置为“实时”（不建议用于电池供电的摄像头）。 不支持诸如流录制之类的“相机”操作。

给定一个名为“Front Yard”的相机，然后使用“camera.front_yard”等名称创建相机。

{
    "event_type": "nest_event",
    "data": {
        "device_id": "EXAMPLE_DEVICE_ID",
        "type": "doorbell_chime",
        "timestamp": "2022-01-26T04:56:54.031000+00:00",
        "nest_event_id": "EXAMPLE_EVENT_ID",
        "attachment": {
          "image": "/api/nest/event_media/DEVICE_ID/EVENT_ID/thumbnail",
          "video": "/api/nest/event_media/DEVICE_ID/EVENT_ID",
        }
        "zones": ["Zone 1"],
    },
}

#Google Home 应用通知设置

Google Home 应用通知设置不仅控制将哪些通知发送到您的手机， 还包括发布到 Pub/Sub feed 的内容。

例如，如果您启用仅限外出通知，Home Assistant 将仅在您的手机离开家时接收事件。

另一件可能不直观的事情是，在设备历史记录中看到该事件并不意味着它已发布到源中。 但是，如果您收到推送通知，则这些设置可能有效。

注意：它们对源的确切设置和效果可能会因相机型号或应用程序版本而异。

如果您仍然没有收到通知，您可以阅读此[来自 Google 的问题排查指南] (https://support.google.com/googlenest/answer/9230439#zippy=%2Cyour-camera-detected-something-but-you-didnt-get-a-camera-alert)

#媒体源

Nest 媒体源 平台允许您浏览最近摄像机事件的剪辑。 Home Assistant 并非旨在成为网络录像机 (NVR) 平台，但支持捕获最近事件的基本支持。

上表描述了哪些设备支持图像快照或 10 帧 mp4 视频剪辑。

#媒体附件

媒体源 API 可以在配套应用程序附件 中用于通知，作为上述设备触发器的操作，例如 按下门铃。您需要熟悉相机支持的媒体源以及配套应用程序的媒体功能。

• /api/nest/event_media/DEVICE_ID/EVENT_ID：事件媒体，根据相机类型支持图像快照 (jpg) 或剪辑预览 (mp4)。

• /api/nest/event_media/DEVICE_ID/EVENT_ID/thumbnail：媒体的缩略图预览，根据相机类型支持图像快照（jpg）或剪辑预览（gif）。

您可以在 automation 中使用 Nest 设备触发器负载字段 attachment.image 或 attachment.video 从 actions 发送通知，如下面的示例所示。

action: notify.mobile_app_iphone
data:
  message: Doorbell Pressed
  title: Someone pressed the doorbell
  data:
    image: "{{ trigger.event.data.attachment.image }}"
    video: "{{ trigger.event.data.attachment.video }}"

action: notify.mobile_app_android
data:
  message: Doorbell Pressed
  title: Someone pressed the doorbell
  data:
    image: "{{ trigger.event.data.attachment.image }}"

action: notify.mobile_app
data:
  message: Doorbell Pressed
  title: Someone pressed the doorbell
  data:
    image: "{{ trigger.event.data.attachment.image }}"

#已知限制

#Google 帐号类型

Google 帐户使用 SDM API 存在一些限制。有关详细信息，请参阅设备访问注册 文档。

主要限制如下：

• 不支持 Google Workspace 帐户。只能使用消费者帐户（例如 gmail.com）。
• Google 帐户一旦与您的设备访问项目关联，就无法更改。在继续之前，请确保您已登录正确的 Google 帐户。

请记住，5 美元的注册费不可退还。

#Google 高级保护计划

Google 高级保护计划 用户会自动屏蔽设备控制所需的“受限”API 范围。

:::important 变通方法：如果你启用了 AP，请创建并使用一个次要的标准 Google 帐号（非 AP）来托管这些设备：

1. 创建一个不带高级保护的新 Google 帐户（如果您还没有）。

2. 使用此新帐户在 Google Home 应用中创建新的 Home。

3. 从主帐户中删除您的 Nest 设备，然后将它们重新添加到这个新的主页。请注意，这可能会删除某些设备保存的视频历史记录或设置。

4. 邀请您的主帐户（有 AP 的帐户）作为 家庭成员 到新的 主页。这使您可以保留对手机上 Google Home 应用的控制权。

5. 使用新的标准帐号凭据连接 Home Assistant。

::: *[AP]：高级保护计划

#Google Home 应用迁移和相机

将相机迁移到 Google Home 应用会将相机从 RTSP 转换为 WebRTC，这会导致快照功能丢失。此外，还有一个已知问题，即目前尚未发布这些活动的媒体；这已报告给 Nest SDM 团队，这是他们迁移的意外副作用。

#部分支持温度传感器

SDM API 不支持其他 Nest 温度传感器。 API 报告的温度将从当前配置为主动传感器的任何设备中获取，可以通过手动选择或 Nest 应用中提供的时间表进行调整。如果有多个传感器可用，则仅显示活动传感器的温度。

#故障排查

#无法关联 Google 帐号

#症状：无法链接到[项目名称]：如果问题仍然存在，请联系[项目名称]

#Description

错误 无法链接到 [项目名称] 通常意味着使用的 OAuth 客户端 ID 是 家庭助理 应用程序凭据 中不匹配。

#Resolution

最简单的方法是从 Home Assistant 中删除应用程序凭据，然后进行验证 使用的 OAuth 客户端 ID 必须在这三个地方保持一致：

• Google Cloud Console - 请参阅上面的说明以创建新的 Web Auth OAuth 凭据（如果需要）。
• 设备访问项目 - 设备访问项目的 OAuth 客户端 ID 必须引用 Google Cloud Console 中的 Web Auth OAuth 客户端 ID。
• 确保您在设备访问控制台和 Google Cloud Console 中使用相同的 Google 帐户。例如，仔细检查屏幕右上角的照片和帐户名称。
• 应用程序凭据 - Home Assistant 需要配置相同的凭据。如果现有条目不匹配，请删除它们，然后手动输入或在设置过程中重新输入。

#症状：无法访问合作伙伴信息或无法检索信息

#Description

显示错误“无法访问合作伙伴信息”或“无法检索信息” 在帐户链接过程中意味着所使用的 Google 帐户无法访问 Google Home。

#Resolution

• 您可以在 Google Home 应用中整理您的家庭和设备，并跨帐户共享家庭和设备。确保所使用的帐户有权访问主页。
• 如果您以前有 Nest 帐户，请确保其已成功迁移到 Google 帐户。如果您的 Google Home 有多个成员，请注意，最初设置家庭的个人必须完成将其 Nest 帐户迁移到 Google 帐户，然后您才能与 Home Assistant 建立连接。

#症状：错误 400：redirect_uri_mismatch

#Description

此错误 错误 400：redirect_uri_mismatch 表示您的 OAuth 客户端 ID 未配置为与 My Home Assistant 回调 URL 匹配。自您最初设置以来，Home Assistant 的重定向 URL 行为可能已发生变化！

#Resolution

对于具有默认配置的用户：

• 这应该在错误消息中显示重定向 URI https://my.home-assistant.io/redirect/oauth。如果错误消息有不同的 URL，那么您正在运行旧版本的 Home Assistant，需要升级或手动禁用 My Home Assistant（见下文）。

• 返回 API 控制台 并选择您的 OAuth 2.0 客户端 ID。
• 将 URL https://my.home-assistant.io/redirect/oauth 添加到授权重定向 URI 列表中，然后单击 保存 并重新开始流程。

对于手动禁用 My Home Assistant 的用户：

• Google 应用严格的重定向 URI 验证规则 以确保您的登录凭据安全。实际上，这意味着您必须通过 SSL 和公共顶级域 访问 Home Assistant。请参阅有关 Securing 的文档，并注意您实际上不需要启用远程访问。

• 如果您的安装上没有我的家庭助理， 您可以使用 <HOME_ASSISTANT_URL>/auth/external/callback 作为重定向 URI 相反。

• <HOME_ASSISTANT_URL> 必须与配置期间使用的相同/ 认证过程。

#症状：出现问题：如果问题仍然存在，请联系此应用程序的开发人员

#Description

这通常意味着您使用了错误类型的凭据或拥有凭据 帐户之间混淆。

#Resolution

按照上述说明，确保 Google Cloud Console 中的凭据是 Web 应用程序 凭据。如果您有多个 Google 帐户登录到当前浏览器会话，则在页面之间切换时 Google 可能会默认使用第一个登录的帐户。为了避免这种情况，请注销其他帐户或使用私人/隐身浏览器窗口，仅登录所需的 Google 帐户。

#症状：出现问题，请几分钟后重试

#Description

根据 Google 的合作伙伴连接管理器错误参考，此错误涵盖了合作伙伴连接中的所有其他未记录的内部错误。导致此错误的问题之一是 Nest 和 Google Home 应用程序之间的同步问题。

#Resolution

确认您的 Nest 设备在 Google Home 应用和同一 Home 下的 Nest 应用中可见。如果 Google Home 中缺少它，请在 Nest 应用上创建一个新的虚拟主页，这会触发同步过程。 （这是 Google 支持团队推荐的解决方法）。一旦 Nest 设备在 Google Home 应用中可见，就可以删除虚拟条目。

#症状：错误 403：access_denied 或访问被阻止：home-assistant.io 尚未完成 Google 的验证过程

#Description

错误 Error 403: access_denied 意味着 OAuth Consent 屏幕可能配置错误， 要么是因为它不允许访问您的 Google 帐户，要么是因为您已输入 触发 Google 验证过程的额外信息。谷歌将要求 当您向品牌页面添加额外信息时进行验证。

#Resolution

访问 OAuth 验证中心 并 确认验证状态为不需要验证。如果验证 需要：

1. 导航至品牌页面。
2. 删除不需要的其他字段并保存。请参阅上面的设置说明并 确保不要输入额外的字段。
3. 返回验证中心，确认状态正确。

此外，您需要按照以下步骤确保受众配置正确：

1. 访问 OAuth 受众 页面。
2. 确保帐户设置为在生产中。

您现在可以重复集成设置和帐户链接步骤。

#症状：错误：invalid_client 无应用程序名称

#Description

错误 Error: invalid_client no application name 表示 OAuth 同意屏幕尚未 已针对项目进行了完全配置，并且需要其他信息。

#Resolution

访问 OAuth 同意屏幕 并 输入必填字段（应用程序名称、支持电子邮件、开发人员电子邮件），并将其他所有内容保留为默认值。

#找不到设备

#症状：设备未出现在 Home Assistant 中

#Description

这通常意味着 Home Assistant 无权访问该设备，因为该设备未归还 来自 SDM API。

#Resolution

您可以在 Nest 合作伙伴连接管理器 中管理与 Home Assistant 共享的设备和权限。 Home Assistant 会自动更新以反映您所做的任何更改。有关更多详细信息，请参阅 SDM API 故障排除 文档。

#症状：恒温器未出现在 Home Assistant 中或不可用

有报告称，由于 SDM API 中的错误，恒温器可能不会出现或不可用。让 API 重新工作的常见修复方法是尝试以下步骤：

• 重新启动恒温器设备。有关更多详细信息，请参阅如何重新启动或重置 Nest 恒温器。
• 在官方 Nest 应用程序或 https://home.nest.com 上：将恒温器移至其他房间或假房间/临时房间。
• Home Assistant 会自动更新以反映您所做的任何更改，并将发现 API 中出现的新设备。

#症状：禁用 API 时不显示设备

#Description

当 SDM API 被禁用时，SDM API 可能不会返回授权帐户的设备。

#Resolution

仔细检查 GCP 是否配置正确并启用 API，并在 OAuth 设置流程中至少授权一台设备。如果您在这里遇到问题，那么您可能需要浏览 Google 说明并直接针对 API 发出命令，直到成功取回设备。

#认证问题

#症状：经常需要重新身份验证

#Description

您可能会被要求比预期更频繁地重新进行身份验证，例如每 7 天一次。这意味着 OAuth 同意屏幕配置错误，或者您的身份验证令牌因其他原因被 Google 撤销。

#Resolution

• 最可能的原因是 OAuth 同意屏幕 默认设置为 测试，令牌将在 7 天后过期。
• 按照上述步骤将其设置为生产以解决此问题，并再次重新授权您的集成以获得新令牌。
• 您可能还会看到错误消息invalid_grant：令牌已过期或撤销。
• 请参阅 Google Identity：刷新令牌过期，了解有关令牌可能过期的更多原因。

#集成设置失败

#症状：配置错误：无法创建订阅者“订阅/名称”未找到

#Description

集成无法启动，因为它尝试创建具有订阅的订阅者 在您的 Google 帐户中找不到的名称。默认情况下，Google 发布/订阅订阅将在 31 天不活动后被删除（参考）。如果发生这种情况，集成将失败，您将在 Home Assistant 日志中看到前面的日志行。

#Resolution.

要修复该订阅：

1. 转到 设备访问控制台 并重新启用 Pub/Sub 主题。
2. 可能需要重新创建 Nest 集成才能获取新的 Pub/Sub 主题。
3. （可选）为防止将来过期，请转到 Google Cloud Console Pub/Sub 订阅页面 并将 Nest 创建的 Pub/Sub 订阅编辑为默认不会过期。

#Nest 集成数据问题

#症状：未接收到相机运动和人物事件

Nest 集成订阅 Google Pub/sub 订阅以侦听相机运动 或人物事件。 Google Home 应用中的设置还可以控制哪些事件 已发布，因此如果设置不正确，您可能不会收到事件。

#Resolution

• 确认您已允许 Home Assistant 访问摄像头流，并且在 合作伙伴连接管理器 中正确设置了权限。
• 如果您仍然看不到事件，则可能需要调整 Google Home 应用设置。有关详细信息，请参阅 Google Home 应用通知设置。

#症状：设备未接收更新信息

#Description

您可能会看到 Google Home 中的更改出乎意料地没有反映在 Home Assistant 中。 Nest 集成订阅来自 Google Pub/sub 订阅的更新以及陈旧信息的问题 通常表明订阅者配置有问题。

传感器或恒温器温度设置点等内容的更改应立即发布到主题，并在一切配置正确后由家庭助理订阅者接收。

#Resolution

• 要详细了解 Google Pub/Sub 的工作原理，请参阅拉取订阅工作流程文档。以下部分中的步骤将：

1. 验证 Nest 设备访问控制台是否配置了用于发布消息的 Pub/Sub 主题
2. （可选）验证主题消息发布。这些步骤适用于某些主题配置。
3. 验证Pub/Sub订阅消息路由
4. 验证 Home Assistant 是否正在接收 Pub/Sub 订阅上的消息

• 验证 Nest 设备访问控制台配置

1.访问设备访问控制台 2.点击Home Assistant设备接入项目 3. 验证发布/订阅主题是否已启用。如果没有，请按照集成配置说明进行操作。 4. 如果 Pub/Sub 主题以 projects/<您的云项目>/topics/home-assistant- 开头，则您正在使用由 Home Assistant 创建的主题。您可以按照下一节中的步骤来验证该主题。 5. 如果 Pub/Sub 主题以 projects/sdm-prod/topics 开头，则您正在使用由设备访问控制台创建的主题。这是老方法，但效果完全没问题。您应该跳过下一节。

• （可选）验证主题消息发布。 如果使用以 projects/sdm-prod/topics 开头的主题名称，请跳过此部分

1. 访问 Pub/Sub 主题 Cloud Console
2. 单击与设备访问控制台配置匹配的 Home Assistant 主题 ID。
3. 查看订阅选项卡并确认有订阅 ID。这将在下一节中得到验证。
4. 单击指标选项卡并将缩放设置为6 小时或1 天。
5. 查看已发布消息计数。这对设备向主题发布的消息进行计数。如果消息数量不符合您的预期，则表明：
   • 设备连接到 Google 时出现问题：验证设备在 Google Home 应用中是否正常工作。
   • SDM API 的问题：这需要设备访问支持 来诊断或解决。

• 验证 Pub/Sub 订阅消息路由

1. 访问 Pub/Sub 订阅 Cloud Console
2. 单击 Home Assistant 订阅 ID
3. 确认主题名称与上面的 Nest 设备访问控制台中的相同。
4. 查看底部面板中的Metrics 选项卡，其中包括：

• 传送指标：发布消息计数显示在路由到订阅的主题上发布的消息。您可能需要向下滚动才能看到这一点。
  • 最早的未确认消息年龄显示 Home Assistant Nest 集成未完全接收消息。请参阅下一节进行诊断。

5. 单击“消息”选项卡
6. 单击“拉取”以查看收到的有关该主题的消息的示例。这些对应于上一节中可选地通过已发布消息计数验证的消息。如果没有发布消息，则表明：

• 订阅配置错误：确认主题 ID 与设备访问控制台匹配。如果它们不匹配，请按照集成配置说明来解决此问题。
  • 设备连接到 Google 时出现问题：验证设备在 Google Home 应用中是否正常工作。
  • SDM API 的问题：这需要设备访问支持 来诊断或解决。

7. 单击已接收消息的箭头可查看所有行内容，以便更轻松地查看已接收消息的完整内容。您可以确认该消息包含您期望看到的信息，并且与下一部分中 Home Assistant 收到的消息相对应。

• 验证家庭助理正在接收消息

1. 启用 Nest 集成的调试日志。有关说明，请参阅调试日志和诊断。 2.查看原始日志
2. 成功接收的事件消息将出现在调试日志中，类似于以下内容：

2025-11-08 09:15:57.620 DEBUG (MainThread) [google_nest_sdm.streaming_manager] Received 1 messages
2025-11-08 09:15:57.621 DEBUG (MainThread) [google_nest_sdm.event] EventMessage raw_data={'eventId': 'xxxxxx-yyyy-zzzz-aaaa', 'timestamp': '2025-11-08T17:15:56.470930Z', 'resourceUpdate': {'name': 'enterprises/...'}}
2025-11-08 09:15:57.621 DEBUG (MainThread) [google_nest_sdm.device] Processing update xxxxxx-yyyy-zzzz-aaaa @ 2025-11-08 17:15:56.470930+00:00
2025-11-08 09:15:57.621 DEBUG (MainThread) [google_nest_sdm.device] Trait update {'sdm.devices.traits.ThermostatMode': {'mode': 'COOL', 'availableModes': ['HEAT', 'COOL', 'HEATCOOL', 'OFF']}, 'sdm.devices.traits.ThermostatEco': {'availableModes': ['OFF', 'MANUAL_ECO'], 'mode': 'OFF', 'heatCelsius': 4.4444427, 'coolCelsius': 24.444443}, 'sdm.devices.traits.ThermostatTemperatureSetpoint': {'coolCelsius': 25.997345}, 'name': 'enterprises/<project id>/devices/<device_id>'}
2025-11-08 09:17:14.406 DEBUG (MainThread) [google_nest_sdm.subscriber_client] Sending streaming pull request (acking 1 messages)

4. 订阅拉取请求长时间运行，并且每隔几分钟重新连接。这是正常现象，您将看到诸如“流拉取中的 API 错误”和“已建立事件流连接”之类的调试消息。 拉取订阅工作流程文档 更详细地描述了其工作原理。以下调试日志表明订阅连接工作正常。

2025-11-08 09:19:50.827 DEBUG (MainThread) [google_nest_sdm.subscriber_client] API error in streaming pull: 503 The service was unable to fulfill your request. Please try again. [code=8a75]
2025-11-08 09:19:50.828 DEBUG (MainThread) [google_nest_sdm.streaming_manager] Disconnected from event stream: API error when streaming iterator: 503 The service was unable to fulfill your request. Please try again. [code=8a75]
2025-11-08 09:19:50.830 DEBUG (MainThread) [google_nest_sdm.streaming_manager] Reconnecting stream in 10.0 seconds
...
2025-11-08 09:20:00.837 DEBUG (MainThread) [google_nest_sdm.subscriber_client] Sending streaming pull request for projects/<your cloud project>/subscriptions/home-assistant-prod
...
2025-11-08 09:20:01.004 DEBUG (MainThread) [google_nest_sdm.streaming_manager] Event stream connection established
2025-11-08 09:20:01.004 DEBUG (MainThread) [google_nest_sdm.subscriber_client] Starting streaming iterator

5. 确认调试日志中“发送流式拉取请求”消息中的订阅 ID 与上面在云控制台中验证的订阅 ID 匹配。如果它们不匹配，请按照集成配置说明来解决此问题。

• 报告 Nest 集成问题时，请提供设备发布的消息等详细信息以及调试日志中的详细信息。

#移除集成

此集成遵循标准移除流程，不需要额外步骤。

#从 Home Assistant 中移除集成实例

1. 前往 设置 > 设备与服务 并选择该集成卡片。
2. 在设备列表中，选择你想移除的集成实例。
3. 在对应条目旁，选择三点菜单 ，然后选择 删除。

删除集成后，你可能还想清理设置过程中添加到 Google 帐号中的未使用信息。可查看本集成的配置说明，了解如何找到已配置的 OAuth 凭据和设备访问项目位置。