此页面由 Cloud Translation API 翻译。

活动

事件是异步的，并由 Google Cloud Pub/Sub 进行管理，每个 Project对应一个主题。事件可为所有设备和结构提供更新，只要用户未撤消访问令牌且事件消息未过期，即可确保收到事件。

允许显示活动

事件是 SDM API 的一项可选功能。请参阅启用事件了解如何为 Project启用事件。

Google Cloud Pub/Sub

如需详细了解 Pub/Sub 的运作方式，请参阅 Google Cloud Pub/Sub 文档。具体而言：

通过方法指南了解 Pub/Sub 的基础知识。
了解身份验证的运作方式。
选择提供的客户端库或编写您自己的客户端库并使用 REST/HTTP 或 gRPC API 途径。

事件订阅

为您的 Project启用事件后，您将获得一个专门针对该 Project ID 的主题，格式如下：

projects/sdm-prod/topics/enterprise-project-id

如需接收事件，请根据您的用例创建对该主题的拉取或推送订阅。支持多个订阅 SDM 主题。如需了解详情，请参阅管理订阅。

发起事件

如需在创建 Pub/Sub 订阅后首次发起事件，请将 devices.list API 调用作为一次性触发器。所有结构和设备的事件都将在此调用后发布。

如需查看示例，请参阅快速入门指南中的授权页面。

事件顺序

Pub/Sub 不保证有序地传送事件，而且事件的接收顺序可能与事件实际发生的顺序不一致。使用 timestamp 字段有助于对事件顺序进行协调。事件也可能会单独到达，或合并到单个事件消息中。

如需了解详情，请参阅对消息进行排序。

用户 ID

如果您的实现基于用户（而非结构或设备），请使用事件载荷中的 userID 字段来关联资源和事件。此字段是表示特定用户的经过混淆处理的 ID。

也可以在每个 API 调用的 HTTP 响应标头中找到 userID。

关系事件

关系事件代表资源的关系更新。例如，当设备添加到结构中或从结构中删除时。

关系事件分为三种类型：

CREATED
已删除
已更新

关系事件的载荷如下所示：

载荷

{
  "eventId" : "049ce833-c330-476f-952f-b3dda83ae0f6",
  "timestamp" : "2019-01-01T00:00:01Z",
  "relationUpdate" : {
    "type" : "CREATED",
    "subject" : "enterprises/project-id/structures/structure-id",
    "object" : "enterprises/project-id/devices/device-id"
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
}

在关系事件中，object 是触发事件的资源，subject 是 object 现在与之相关的资源。在上面的示例中， user 已向 developer授予对此特定设备的访问权限，并且 user的已获授权设备现在与其已获授权的结构相关联，从而触发了事件。

subject 只能是房间或结构。如果 a developer 无权查看 user的结构，subject 始终为空。

字段

字段	说明	数据类型
`eventId`	事件的唯一标识符。	`string` 示例：“665fa8b2-ba4a-401f-aad7-bd2740f7ec41”
`timestamp`	事件发生的时间。	`string` 示例：“2019-01-01T00:00:01Z”
`relationUpdate`	一个对象，详细说明了与关系更新相关的信息。	`object`
`userId`	代表用户的唯一经过混淆处理的标识符。	`string` 示例：“AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi”

如需详细了解不同类型的事件及其工作原理，请参阅事件。

示例

每种类型的关系事件的事件载荷都不同：

创建时间

已创建结构

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

设备已创建

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

创建了设备

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

已更新

设备移动完毕

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

已删除

结构已删除

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

已删除设备

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

已删除设备

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

在以下情况下，系统不会发送关联事件：

删除了聊天室

资源事件

资源事件表示特定于资源的更新。它可以响应 trait 字段的值发生更改，例如更改温控器的模式。它还可以表示不更改特征字段的设备操作，例如按设备按钮。

为响应特征值变更而生成的事件包含 traits 对象，类似于设备 GET 调用：

载荷

{
  "eventId" : "d89bda44-0d9d-42aa-9ab2-a685a0f1ca0d",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatMode" : {
        "mode" : "COOL"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

请参阅各个特征文档，了解任何特征字段更改资源事件的载荷格式。

为响应不会更改 trait 字段的设备操作而生成的事件也包含包含 resourceUpdate 对象的载荷，但使用 events 对象，而不是 traits 对象：

载荷

{
  "eventId" : "d7b54476-0d5d-4d37-8d80-14261981144b",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "E5kcTftnwgacvbdKS69vufvvP0...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

这些类型的资源事件在特定 trait 中定义。例如，Motion 事件在 CameraMotion trait 中定义。请参阅每个特征的文档，了解这些类型资源事件的载荷格式。

字段

字段	说明	数据类型
`eventId`	事件的唯一标识符。	`string` 示例：“d7b54476-0d5d-4d37-8d80-14261981144b”
`timestamp`	事件发生的时间。	`string` 示例：“2019-01-01T00:00:01Z”
`resourceUpdate`	详细介绍资源更新相关信息的对象。	`object`
`userId`	用于代表用户的唯一且经过混淆处理的标识符。	`string` 示例：“AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi”
`eventThreadId`	事件线程的唯一标识符。	`string` 示例：“d67cd3f7-86a7-425e-8bb3-462f92ec9f59”
`eventThreadState`	事件线程的状态。	`string` 值：“STARTED”“UPDATED”“ENDED”
`resourceGroup`	一个对象，用于指明可能与此事件具有类似更新的资源。事件本身的资源（来自 `resourceUpdate` 对象）将始终显示在此对象中。	`object`

如需详细了解不同类型的事件及其运作方式，请参阅事件。

可更新的通知

您可以在应用（例如 Android 或 iOS 应用）中实现基于资源事件的通知。为了减少发送的通知数量，可以实现一项名为可更新通知的功能，其中会根据同一事件线程中的后续事件，使用新信息更新现有通知。

部分事件支持可更新通知，并在文档中标记为可更新。这些事件的载荷中包含一个名为 eventThreadId 的额外字段。使用此字段可将各个事件关联起来，以便更新已向用户显示的现有通知。

事件线程与事件会话不同。事件线程用于标识同一线程中上一个事件的更新状态。事件会话用于标识彼此相关的单独事件，给定事件会话可以有多个事件线程。

出于通知目的，系统会将不同类型的事件分组到不同的线程中。

此线程分组和时间逻辑由 Google 处理，可能会随时发生变化。 developer 应根据 SDM API 提供的事件线程和会话更新通知。

线程状态

支持可更新通知的事件还有一个 eventThreadState 字段，用于指示事件线程在该时间点的状态。此字段具有以下值：

STARTED - 事件线程中的第一个事件。
已更新 - 正在进行的事件线程中的事件。单个线程中可以有零个或多个具有此状态的事件。
ENDED - 事件串中的最后一个事件，可能与上一个 UPDATED 事件重复，具体取决于线程类型。

此字段可用于跟踪事件线程的进度以及其结束时间。

事件过滤

在某些情况下，设备检测到的事件可能会被滤除，而无法发布到 SDM Pub/Sub 主题。此行为称为“事件过滤”。事件过滤的目的是避免在短时间内发布过多类似的事件消息。

例如，系统可能会向 SDM 主题发布消息，以便处理初始动作事件。之后，系统会在指定时间段过后滤除 Motion 的其他消息，直到发布。在该时间段过后，系统可能会再次发布该事件类型的事件消息。

在 Google Home 应用 (GHA) 中，被滤除的事件仍会显示在 user的事件记录中。不过，此类事件不会生成应用通知（即使该通知类型已启用）。

每种类型的事件都有自己的事件过滤逻辑，该逻辑由 Google 定义，随时都可能发生变化。此事件过滤逻辑独立于事件线程和会话逻辑。

服务账号

建议使用服务账号来管理 SDM API 订阅和事件消息。服务账号由应用或虚拟机（而非个人）使用，并且具有自己的唯一账号密钥。

Pub/Sub API 的服务账号授权使用两段式 OAuth (2LO)。

在 2LO 授权流程中：

developer 使用服务密钥请求访问令牌。
developer 会在调用 API 时使用访问令牌。

如需详细了解 Google 2LO 以及如何进行设置，请参阅将 OAuth 2.0 用于服务器到服务器应用。

授权

该服务账号应获得使用 Pub/Sub API 的授权：

在 Google Cloud 中启用 Cloud Pub/Sub API。
按照创建服务账号中的说明创建服务账号和服务账号密钥。我们建议仅为其授予 Pub/Sub Subscriber 角色。请务必将服务账号密钥下载到将使用 Pub/Sub API 的机器。
按照上一步中页面上的说明向应用代码提供身份验证凭据（服务账号密钥），或者使用 oauth2l 手动获取访问令牌（如果您想快速测试 API 访问权限）。
将服务账号凭据或访问令牌与 Pub/Sub project.subscriptions API 搭配使用，以拉取和确认消息。

oauth2l

Google oauth2l 是使用 Go 编写的 OAuth 命令行工具。请使用 Go 为 Mac 或 Linux 安装该工具。

如果您的系统中没有 Go，请先下载并安装 Go。
安装 Go 后，安装 oauth2l 并将其位置添加到 PATH 环境变量中：
```
go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
```

使用 oauth2l 获取适当 OAuth 范围的 API 访问令牌：

oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

例如，如果您的服务密钥位于 ~/myServiceKey-eb0a5f900ee3.json：

oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...

如需了解更多使用信息，请参阅 oauth2l 自述文件。

Google API 客户端库

利用 OAuth 2.0 的 Google API 有多个客户端库可用。如需详细了解您偏好的语言，请参阅 Google API 客户端库。

将这些库与 Pub/Sub API搭配使用时，请使用以下作用域字符串：

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

错误

与本指南相关的以下错误代码可能会返回：

错误消息	RPC	问题排查
相机图片无法再下载。	`DEADLINE_EXCEEDED`	活动图片会在活动发布 30 秒后过期。请务必在图片过期前下载。
事件 ID 不属于摄像头。	`FAILED_PRECONDITION`	使用相机事件返回的正确 `eventID`。

如需查看 API 错误代码的完整列表，请参阅 API 错误代码参考。