事件

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

啟用活動功能

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

Google Cloud Pub/Sub

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

事件訂閱

為 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

關係事件

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

關聯事件分為三種類型:

  • 建立時間:
  • 已刪除
  • 已更新

關聯事件的酬載如下:

酬載

{
  "eventId" : "d93fe80c-dd14-4afb-80bd-b12dc7dca526",
  "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 是觸發事件的資源, subjectobject 現在有關聯的資源。在 就上述範例而言,「 user 」已授予此特定裝置的存取權 「 developer」,且「 user」的授權裝置現在已與這位使用者的授權裝置相關聯 並觸發事件

subject 只能是房間或結構。如果 a developer 沒有 查看 user結構的權限,subject 一律會 並將空無一物。

欄位

欄位 說明 資料類型
eventId 事件的專屬 ID。 string
例如:「96305092-d82e-4e52-9115-29bfd0594bf0」
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" : "ba462282-5053-4e3c-bf38-612b802dfa53",
  "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" : "a556db20-2bab-4bd4-bb39-9c036a252a7e",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "MnCcivUK74q3Zq7CNUSsnYcAcM...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }

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

欄位

欄位 說明 資料類型
eventId 事件的專屬 ID。 string
例如:「a556db20-2bab-4bd4-bb39-9c036a252a7e」
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:

  1. 啟用 Cloud Pub/Sub API 或是 Google Cloud 中的任何項目
  2. 按照下列說明建立服務帳戶和服務帳戶金鑰: 建立服務帳戶。 建議您只授予此角色 Pub/Sub 訂閱者角色。請務必 將服務帳戶金鑰下載到要使用 Pub/Sub API。
  3. 將驗證憑證 (服務帳戶金鑰) 提供給 修改應用程式的程式碼 步驟,或使用 oauth2l 手動取得存取權杖 (如有) 進行快速測試 API 存取
  4. 將服務帳戶憑證或存取權杖與 Pub/Sub project.subscriptions API 提取及確認訊息

OAuth2l

Google oauth2l 是使用以 Go 編寫的 OAuth 適用的指令列工具。安裝 使用 Go 的 Mac 或 Linux。

  1. 如果您的系統中沒有 Go,請先下載並安裝 Go
  2. 安裝 Go 後,請安裝 oauth2l 並將位置資訊新增至 PATH 環境變數:
    go install github.com/google/oauth2l@latest
    export PATH=$PATH:~/go/bin
  3. 使用適當的指令,使用 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

錯誤

根據本指南的規定,系統可能傳回下列錯誤代碼:

錯誤訊息 單次點擊收益 疑難排解
相機圖片已不再開放下載。 DEADLINE_EXCEEDED 事件圖片會在事件發布 30 秒後失效。請務必在到期前下載映像檔。
事件 ID 不屬於攝影機。 FAILED_PRECONDITION 請使用攝影機事件傳回的正確 eventID

請參閱 API 錯誤代碼參考資料: API 錯誤代碼的完整清單