イベント

イベントは非同期で、Google Cloud Pub/Sub によって管理され、 Project。イベントは、すべてのデバイスとストラクチャの更新を提供します。イベントの受信は、 ユーザーによってアクセス トークンが取り消されておらず、イベント メッセージが 期限切れになりました。

イベントを有効にする

イベントは、SDM API のオプション機能です。詳しくは、 イベントを有効にする で Projectを有効にする方法をご確認ください。

Google Cloud Pub/Sub

詳しくは、Google Cloud Pub/Sub のドキュメントをご覧ください。 詳しく学びます具体的には、次のとおりです。

イベント サブスクリプション

Projectでイベントを有効にすると、そのイベントに固有のトピックが提供されます Project ID。形式は以下のようになります。

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

イベントを受信するには、pull または push サブスクリプションをそのトピックに 構築できますSDM トピックへの複数のサブスクリプションがサポートされています。詳しくは、 詳しくは、定期購入の管理をご覧ください。 情報です。

イベントを開始する

Pub/Sub サブスクリプションの作成後に初めてイベントを開始するには、 <ph type="x-smartling-placeholder"></ph> devices.list 1 回限りのトリガーとして指定することもできます。この後、すべてのストラクチャとデバイスのイベントが公開されます 呼び出します。

例については、 クイック スタートの [承認] ページ ガイド。

イベントの順序

Pub/Sub はイベントの順序付けされた配信を保証するものではありません。イベントの受信順序は、 イベントが発生した順序に対応します。timestamp を使用する イベントの順序の調整に使用できます。イベントは個別に、または複合して届く場合もあります。 1 つのイベント メッセージにまとめます。

詳細については、次をご覧ください: メッセージを並べ替える

ユーザー ID

構造やデバイスではなく、ユーザーに基づいて実装する場合は、 リソースとイベントを関連付けるイベント ペイロードの userID フィールド。このフィールドは 特定のユーザーを表す難読化された ID。

userID は、各 API 呼び出しの HTTP レスポンス ヘッダーでも使用できます。

関係イベント

リレーション イベントは、リソースのリレーショナル更新を表します。たとえば、デバイスが ストラクチャに追加された場合や、デバイスがストラクチャから削除された場合にも発生します。

リレーション イベントには次の 3 種類があります。

  • 作成日:
  • 削除済み
  • 更新済み

リレーション イベントのペイロードは次のとおりです。

ペイロード

{
  "eventId" : "f90aac0b-3637-4681-aac0-18f3be6f0892",
  "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
例: 「ed4cd8c3-eb6c-41bb-81be-30379cc713a5」
timestamp イベントが発生した時刻。 string
例: 「2019-01-01T00:00:01Z」
relationUpdate リレーションの更新に関する詳細情報を含むオブジェクト。 object
userId ユーザーを表す、難読化された一意の識別子。 string
例: 「AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi」

各種のイベントについて詳しくは、イベントをご覧ください。 その仕組みを学びました。

イベント ペイロードは、リレーション イベントのタイプごとに異なります。

CREATED

ストラクチャを作成しました

"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" : "840d511c-bc6f-429f-8e81-36ec258ab0c0",
  "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" : "ed21b6b0-791f-46ab-bac1-868c78020b5f",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "SERtdqmTk0FDDDP_M9NE-H-bY9...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }

これらのタイプのリソース イベントは、特定のトレイトで定義されます。たとえば、 モーション イベントは CameraMotion トレイト。各トレイトのドキュメントをご覧ください。 これらの種類のリソース イベントのペイロード形式を理解できます。

フィールド

項目 説明 データ型
eventId イベントの一意の識別子。 string
例: "ed21b6b0-791f-46ab-bac1-868c78020b5f"
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 という追加フィールドがあります。使用する フィールドを使用して個々のイベントをリンクし、既存の メッセージを表示することもできます

イベント スレッドはイベント セッションとは異なります。イベント スレッド は、同じスレッド内の前のイベントで更新されたステータスを識別します。「 イベント セッションは、互いに関連する個別のイベントを識別します。 1 つのイベント セッションに複数のイベント スレッドが存在する場合があります。

通知では、イベントの種類によってイベントがグループ分けされます。 説明します。

このスレッドのグループ化とタイミングのロジックは Google によって処理され、 いつでも変更できます。A developer は以下に基づいて通知を更新します。 イベント スレッドとセッションを提供します。

スレッドの状態

更新可能な通知をサポートするイベントには、eventThreadState もあります。 フィールドに、その時点のイベント スレッドの状態を示します。この フィールドには、次の値があります。

  • STARTED - イベント スレッドの最初のイベント。
  • UPDATED - 進行中のイベント スレッド内のイベント。1 つのスレッドに、この状態のイベントが 0 個以上存在する可能性があります。
  • ENDED - イベント スレッドの最後のイベント。スレッドの種類によっては、最後の UPDATED イベントと重複する場合があります。

このフィールドを使用して、イベント スレッドの進行状況と、イベントがいつ発生したかを追跡できます。 終了です。

イベント フィルタリング

場合によっては、デバイスで検出されたイベントが公開から除外されることがあります Pub/Sub トピックに送信しますこの動作 イベント フィルタリングと呼ばれます。イベントのフィルタリングの目的は、 短期間に大量の類似イベントメッセージをパブリッシュする

たとえば、メッセージが SDM トピックにパブリッシュされる場合です。 最初のモーションイベントのその他 その後のモーションに関するメッセージは 一定期間が経過するまで公開対象から除外されます。その期間に 時間が経過すると、そのイベントタイプのイベント メッセージが再度パブリッシュされる可能性があります。

Google Home アプリ(GHA)で、 フィルタしたアイテムは、 userのアクティビティ履歴に引き続き表示されます。ただし、 イベントでは、アプリの通知は生成されません(その通知タイプが 有効にします)。

各タイプのイベントには、独自のイベント フィルタリング ロジックがあります。このロジックは、 いつでも変更される場合があります。このイベント フィルタリング ロジックは、 セッション ロジックに依存しません。

サービス アカウント

SDM API の管理にはサービス アカウントをおすすめします サブスクリプションとイベントメッセージです。サービス アカウントは、アプリケーションや 仮想マシンであり、固有のアカウント キーがあります。

Pub/Sub API に対するサービス アカウントの認可では、 Two-legged OAuth(2LO)。

2LO 承認フローでは、次のようになります。

  • developer はサービスキーを使用してアクセス トークンをリクエストします。
  • developer は、API の呼び出しでアクセス トークンを使用します。

Google 2LO の詳細と設定方法については、 サーバー間での OAuth 2.0 の使用 アプリケーション

承認

このサービス アカウントは、Cloud KMS 鍵と Pub/Sub API:

  1. Cloud Pub/Sub を有効にする API 説明します。
  2. 次の説明に沿って、サービス アカウントとサービス アカウント キーを作成する サービス アカウントを作成するPub/Sub サブスクライバーのロールのみ付与することをおすすめします。必ず サービス アカウント キーを、Compute Engine インスタンス Pub/Sub API。
  3. 認証情報(サービス アカウント キー)を 前のスライドのページの手順に沿って、アプリケーション コードを 取得するか、必要に応じて oauth2l を使用してアクセス トークンを手動で取得します。 API アクセスを迅速にテストしたい場合です
  4. サービス アカウントの認証情報またはアクセス トークンを Pub/Sub project.subscriptions API メッセージを pull して確認応答できます。

OAuth2l

Google oauth2l は、Go で作成された OAuth 用のコマンドライン ツールです。インストール対象 Go を使用する Mac または Linux です。

  1. システムに 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 クライアント ライブラリをご覧ください。 できます。

これらのライブラリを 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 エラーコードの完全なリスト。