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

イベント

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

イベントを有効にする

イベントは、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

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

イベントを開始する

Pub/Sub サブスクリプションの作成後にイベントを初めて開始するには、1 回限りのトリガーとして devices.list API 呼び出しを行います。この呼び出しの後に、すべてのストラクチャとデバイスのイベントが公開されます。

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

イベントの順序

Pub/Sub はイベントの順序付けされた配信を保証するものではありません。イベントの受信順序は、イベントが実際に発生した順序と一致しない場合があります。timestamp フィールドは、イベントの順序の調整に役立ちます。イベントは、個別に到着することも、単一のイベントメッセージに結合されて到着することもできます。

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

ユーザー ID

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

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

関係イベント

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

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

CREATED
DELETED
更新済み

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

ペイロード

{
  "eventId" : "3848e75c-5107-4673-bb67-c40ff5958d23",
  "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 に指定できるのは、部屋またはストラクチャのみです。 userの構造を表示する権限が a developer に付与されていない場合、subject は常に空になります。

フィールド

項目	説明	データの種類
`eventId`	イベントの一意の識別子。	`string` 例: 「bb68e556-1bd5-42ba-bf60-c342ac58553f」
`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"
}

DELETED

ストラクチャを削除しました

"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" : "bc3b577f-d64b-4a50-bdbd-0a9348d1d811",
  "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" : "a90fd495-ffcd-420a-a847-1bc1166d46e0",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "pzUpWL30pkOOESIoh5X10D8sum...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

フィールド

項目	説明	データの種類
`eventId`	イベントの一意の識別子。	`string` 例: "a90fd495-ffcd-420a-a847-1bc1166d46e0"
`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 - イベントスレッドの最初のイベント。
UPDATED - 進行中のイベントスレッド内のイベント。1 つのスレッドに、この状態のイベントが 0 個以上存在する可能性があります。
ENDED - イベントスレッドの最後のイベント。スレッドの種類によっては、最後の UPDATED イベントと重複する場合があります。

このフィールドを使用して、イベントスレッドの進行状況と終了タイミングを追跡できます。

イベントフィルタリング

場合によっては、デバイスによって検出されたイベントが、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

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

デバイスを作成しました

デバイスを作成しました

更新済み

デバイスを移動しました

DELETED

ストラクチャを削除しました

デバイスを削除しました

デバイスを削除しました

リソース イベント

ペイロード

ペイロード

フィールド

更新可能な通知

スレッドの状態

イベント フィルタリング

サービス アカウント

認可

OAuth2l

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

エラー

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

リソースイベント

イベントフィルタリング

サービスアカウント

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