本頁面由 Cloud Translation API 翻譯而成。

事件

事件由 Google Cloud Pub/Sub 非同步管理，各主題位於單一主題 Project。「事件」提供所有裝置和結構的更新，且會收到事件：只要使用者沒有撤銷存取權杖，且事件訊息未遭到系統撤銷，即可放心已過期。

啟用活動功能

事件是 SDM API 的選用功能。詳情請見啟用事件瞭解如何為「 Project」啟用這些功能。

Google Cloud Pub/Sub

詳情請參閱 Google Cloud Pub/Sub 說明文件。進一步瞭解 Pub/Sub 的運作方式請特別注意以下幾點：

瞭解 Pub/Sub 的基本概念使用指南。
瞭解驗證的運作方式。
選擇我們提供的用戶端程式庫也可以自行撰寫 REST/HTTP 或 gRPC API 介面：

事件訂閱

為 Project啟用事件後，系統會提供該主題的相關主題 Project ID，格式為：

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

如要接收事件，請建立 pull 或「推送」push訂閱該主題 (視具體來說，您可以設計提示來解決業務工作系統支援多個 SDM 主題的訂閱項目。詳情請見管理訂閱項目以瞭解詳情可能不準確或不適當

啟動事件

如要在 Pub/Sub 訂閱項目建立後首次啟動事件，請 devices.list 將 API 呼叫視為一次性觸發程序在這之後，系統會發布所有結構和裝置的事件呼叫。

如需範例，請參閱快速入門的「授權」頁面指南。

活動順序

Pub/Sub 不保證會按順序傳送事件，事件的接收順序也可能不會對應至事件實際發生的順序。使用「timestamp」欄位來協助對事件順序進行協調。活動也可能會個別參加或合併合併為單一事件訊息

若需更多資訊，請參閲排序訊息。

使用者 ID

如果您導入作業是以使用者 (而非結構或裝置) 為主，請使用事件酬載中的 userID 欄位，藉此與資源和事件建立關聯。這個欄位代表特定使用者的 ID (經過模糊處理)。

每個 API 呼叫的 HTTP 回應標頭中也提供 userID。

關係事件

關係事件代表資源的關聯更新。假設裝置新增至結構或裝置從結構中刪除時。

關聯事件分為三種類型：

建立時間：
已刪除
已更新

關聯事件的酬載如下：

酬載

{
  "eventId" : "0ebaf6d5-c3a6-4da0-8b36-53b8dc74ed97",
  "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`	事件的專屬 ID。	`string` 例如：「f044e0e8-a92a-4096-8cee-52d0700f2881」
`timestamp`	事件發生的時間。	`string` 例如：「2019-01-01T00:00:01Z」
`relationUpdate`	詳述關聯更新相關資訊的物件。	`object`
`userId`	代表使用者的不重複且經過模糊處理的 ID。	`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"
}

在下列情況中，系統不會傳送關係事件：

已刪除會議室

資源事件

資源事件代表資源專屬的更新。因應變更例如變更溫度控制器的模式也可能代表會觸發這些動作的裝置動作都不會變更特徵欄位，例如按下裝置按鈕。

為了因應特徵欄位值的變化而產生的事件，會含有 traits 物件，類似於裝置的 GET 呼叫：

酬載

{
  "eventId" : "7ced16bd-0bcb-4134-a9b3-835da0457557",
  "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"
  ]
}

使用個人特徵說明文件，瞭解任何特徵欄位變更資源的酬載格式活動。

在未變更特徵欄位的情況下，為了回應裝置動作而產生的事件，也有具有 resourceUpdate 物件，但具有 events 物件的酬載而不是 traits 物件：

酬載

{
  "eventId" : "284c805e-b846-43b4-8f5b-680b75b29d61",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "wPN0CWvIgPreoQmZmIg9rkLLq2...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

這些類型的資源事件是在特定特徵中定義。舉例來說，動作事件是在 CameraMotion 特徵。查看每種特徵的說明文件瞭解這些資源事件類型的酬載格式。

欄位

欄位	說明	資料類型
`eventId`	事件的專屬 ID。	`string` 例如：「284c805e-b846-43b4-8f5b-680b75b29d61」
`timestamp`	事件發生的時間。	`string` 例如：「2019-01-01T00:00:01Z」
`resourceUpdate`	詳細列出資源更新相關資訊的物件。	`object`
`userId`	代表使用者的不重複且經過模糊處理的 ID。	`string` 例如：「AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi」
`eventThreadId`	事件執行緒的專屬 ID。	`string` 例如：「d67cd3f7-86a7-425e-8bb3-462f92ec9f59」
`eventThreadState`	事件執行緒的狀態。	`string` 值：「STARTED」、「UPDATED」、「ENDED」
`resourceGroup`	這個物件代表資源可能具有與此事件類似的更新。事件本身的資源 (來自 `resourceUpdate` 物件) 一律會顯示在這個物件中。	`object`

如要進一步瞭解事件類型及其運作方式

可更新的通知

您可以根據資源事件在應用程式中實作通知，例如： Android 或 iOS。如要減少傳送的通知數量，我們推出了一項功能， 可更新的通知可能會導入，其中現有的通知會根據同一事件的後續事件更新資訊。

選取事件功能支援可更新的通知，並標記為可更新。這些活動在其酬載中都有一個名為 eventThreadId 的欄位。使用這份草稿欄位來連結個別事件，以便更新現有事件提供給使用者的通知。

事件執行緒與事件工作階段不同。事件執行緒 代表在同一執行緒中前一個事件的更新狀態。 事件工作階段：識別彼此相關的個別事件；針對特定事件工作階段可以有多個事件執行緒。

為了提供通知，不同類型的事件會歸入不同的事件類別。

這個討論串的分組和時間邏輯是由 Google 處理，隨時變更。 developer 應根據以下項目更新通知：事件執行緒和工作階段。

執行緒狀態

支援可更新通知的事件同時具備 eventThreadState 欄位，以指出該時間點的事件執行緒狀態。這個欄位中的值如下：

已開始：事件執行緒中的第一個事件。
已更新：進行中事件執行緒中的事件。單一執行緒中可能有零或多個處於此狀態的事件。
ENDED — 事件執行緒中的最後一個事件，視執行緒類型而定，此事件可能與最近 UPDATED 事件重複。

這個欄位可用來追蹤事件執行緒的進度，以及已結束。

事件篩選

在某些情況下，裝置偵測到的事件可能會遭到篩除，不再顯示複製到 SDM Pub/Sub 主題行為稱為事件篩選。事件篩選的目的是避免在短時間內發布過多類似活動訊息。

例如，訊息可發布至 SDM 主題啟動 Motion 事件其他之後就會等一段時間才會發布這段期間過後時間過後，針對該事件類型的事件訊息可能會再次發布。

在 Google Home 應用程式 (GHA) 中，曾發生的事件你過濾掉的仍會顯示在 user的事件記錄中。不過，事件就不會產生應用程式通知 (即使該通知類型啟用)。

每個事件類型都有各自的事件篩選邏輯，由且可能隨時變更。這個事件篩選邏輯是完全獨立於事件執行緒和工作階段邏輯

服務帳戶

建議使用服務帳戶管理 SDM API 包括訂閱和活動訊息等等服務帳戶可以由應用程式使用並且擁有專屬帳戶金鑰，而非個人。

Pub/Sub API 使用的服務帳戶授權雙足式 OAuth (2LO)。

在 2LO 授權流程中：

developer 使用服務金鑰要求存取權杖。
developer 會使用存取權杖與 API 呼叫。

如要進一步瞭解 Google 2LO 及設定方式，請參閱：針對伺服器對伺服器使用 OAuth 2.0 應用程式。

授權

服務帳戶應取得授權，才能使用 Pub/Sub API：

啟用 Cloud Pub/Sub API 或是 Google Cloud 中的任何項目
按照下列說明建立服務帳戶和服務帳戶金鑰：建立服務帳戶。建議您只授予此角色 Pub/Sub 訂閱者角色。請務必將服務帳戶金鑰下載到要使用 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 取得 API 的存取權杖 OAuth 範圍：

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 README 可能不準確或不適當

Google API 用戶端程式庫

為使用 OAuth 的 Google API 提供數種用戶端程式庫 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 錯誤代碼的完整清單