このページは Cloud Translation API によって翻訳されました。

イベント

イベントは非同期で、 Projectごとに 1 つのトピックで Google Cloud Pub/Sub によって管理されます。イベントはすべてのデバイスと構造の更新情報を提供します。アクセストークンがユーザーによって取り消されず、イベントメッセージが期限切れになっていなければ、イベントの受信は保証されます。

イベントを有効にする

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

Google Cloud Pub/Sub

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 サブスクリプションが作成された後にイベントを初めて開始するには、1 回限りのトリガーとして devices.list API 呼び出しを行います。すべての構造とデバイスのイベントが、この呼び出し後に公開されます。

例については、クイックスタートガイドの承認ページをご覧ください。

イベントの順序

Pub/Sub はイベントの順序配信を保証するものではなく、イベントの受信順序はイベントが実際に発生した順序と一致しない場合があります。イベントの順序の調整に役立つように、timestamp フィールドを使用します。イベントは個別に届く場合もあれば、1 つのイベントメッセージに統合されて届く場合もあります。

詳細については、メッセージの順序指定をご覧ください。

ユーザー ID

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

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

関係イベント

関係イベントは、リソースのリレーショナルアップデートを表します。たとえば、デバイスが構造に追加されたときや、デバイスが構造から削除されたときなどです。

関係イベントには次の 3 種類があります。

CREATED
削除済み
更新済み

関係イベントのペイロードは次のとおりです。

ペイロード

{
  "eventId" : "fe7f839d-6fa6-45bb-894e-e30091b0bb06",
  "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` 例:「d77dba23-91d4-4b2e-b44a-acffe1614a66」
`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"
}

次の場合、関係イベントは送信されません。

部屋が削除された

リソースイベント

リソースイベントは、リソースに固有の更新を表します。サーモスタットのモードの変更など、トレイトフィールドの値の変更に応じて実行できます。トレイトフィールドを変更しないデバイス操作（デバイスのボタンの押下など）を表すこともできます。

特徴フィールドの値の変更に応じて生成されたイベントには、デバイスの GET 呼び出しと同様に traits オブジェクトが含まれます。

ペイロード

{
  "eventId" : "164cc0d5-2e47-4011-81be-d0f8e24e4dfa",
  "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 オブジェクトを含むペイロードがありますが、traits オブジェクトではなく events オブジェクトが含まれています。

ペイロード

{
  "eventId" : "283c3325-df63-4c77-a5cf-a432892c22d9",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "OaBUs9ajAiPhwrGCG5H-_Sb5ZX...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

フィールド

フィールド	説明	データ型
`eventId`	イベントの一意の識別子。	`string` 例: 283c3325-df63-4c77-a5cf-a432892c22d9
`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 - イベントスレッドの最初のイベント。
更新済み - 進行中のスレッド内のイベント。1 つのスレッドに、この状態のイベントが 0 個以上存在する場合があります。
終了 - イベントスレッドの最後のイベント。スレッドの種類によっては、最後の更新イベントの重複となる場合があります。

このフィールドは、イベントスレッドの進行状況と終了時間を追跡するために使用できます。

イベントフィルタリング

デバイスで検出されたイベントが、SDM Pub/Sub トピックへのパブリッシュから除外される場合があります。この動作はイベントフィルタリングと呼ばれます。イベントフィルタリングは、短時間に類似のイベントメッセージを過度に公開しないようにするためのものです。

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

Google Home アプリ（GHA）では、フィルタされたアクティビティは userのアクティビティ履歴に引き続き表示されます。ただし、このようなイベントでは、（その通知タイプが有効になっている場合でも）アプリ通知は生成されません。

各イベントタイプには独自のイベントフィルタリングロジックがあります。このロジックは Google によって定義され、随時変更される可能性があります。このイベントフィルタリングロジックは、イベントスレッドとセッションロジックとは独立しています。

サービスアカウント

SDM API サブスクリプションとイベントメッセージを管理するには、サービスアカウントを使用することをおすすめします。サービスアカウントは、ユーザーではなくアプリケーションまたは仮想マシンで使用され、独自のアカウントキーを持ちます。

Pub/Sub API のサービスアカウント認可では、Two-legged OAuth（2LO）が使用されます。

2LO 認可フローでは、次のようにします。

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

Google 2LO の詳細と設定方法については、サーバー間アプリケーションに OAuth 2.0 を使用するをご覧ください。

承認

サービスアカウントは、Pub/Sub API での使用が承認されている必要があります。

Google Cloud で Cloud Pub/Sub API を有効にする。
サービスアカウントの作成の説明に従って、サービスアカウントとサービスアカウントキーを作成します。Pub/Sub サブスクライバーのロールのみを付与することをおすすめします。Pub/Sub API を使用するマシンにサービスアカウントキーをダウンロードしてください。
前の手順のページの手順に沿って、認証情報（サービスアカウントキー）をアプリケーションコードに指定します。API アクセスをすばやくテストする場合は、oauth2l を使用してアクセストークンを手動で取得します。
Pub/Sub project.subscriptions API でサービスアカウントの認証情報またはアクセストークンを使用して、メッセージを pull して確認します。

oauth2l

Google oauth2l は、Go で記述された OAuth 用のコマンドラインツールです。Go を使用して Mac または Linux にインストールします。

システムに 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 README をご覧ください。

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 エラーコードのリファレンスをご覧ください。

イベント

イベントを有効にする

Google Cloud Pub/Sub

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

イベントを開始する

イベントの順序

ユーザー ID

関係イベント

ペイロード

フィールド

例

CREATED

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

デバイスが作成されました

デバイスが作成されました

更新済み

デバイスを移動しました

削除済み

構造物が削除されました

デバイスを削除しました

デバイスを削除しました

リソース イベント

ペイロード

ペイロード

フィールド

更新可能な通知

スレッドの状態

イベント フィルタリング

サービス アカウント

承認

oauth2l

Google API クライアント ライブラリ

エラー

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

リソースイベント

イベントフィルタリング

サービスアカウント

Google API クライアントライブラリ