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

イベント

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

イベントを有効にする

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

Google Cloud Pub/Sub

Pub/Sub の仕組みについては、Google Cloud Pub/Sub のドキュメントをご覧ください。具体的には、次のとおりです。

入門ガイドで Pub/Sub の基本を学びます。
認証の仕組みを理解します。
提供されているクライアントライブラリを選択するか、独自のライブラリを作成してREST/HTTP または gRPC API サーフェスを使用します。

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

2025 年 1 月より前は、 Projectでイベントが有効になっている場合、その Project ID に固有のトピックが次の形式で提供されていました。

projects/gcp-project-name/subscriptions/topic-id

2025 年 1 月以降に作成されたプロジェクトでは、Pub/Sub トピックをセルフホストする必要があります。独自のトピック ID を指定する必要があります。詳細については、トピックを作成するをご覧ください。

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

イベントを開始する

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

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

イベントの順序

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

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

ユーザー ID

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

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

関係者イベント

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

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

CREATED
削除済み
更新済み

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

ペイロード

{
  "eventId" : "81688b62-4f69-432f-bbe0-5270032f5466",
  "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 が関連付けられたリソースです。上記の例では、a user がこの特定のデバイスへのアクセスを developerに許可し、 userの承認済みデバイスが承認済み構造に関連付けられたため、イベントがトリガーされています。

subject はルームまたは構造体のみにできます。 a developer に userの構造を表示する権限がない場合、subject は常に空になります。

フィールド

フィールド	説明	データ型
`eventId`	イベントの一意の識別子。	`string` 例: 「4ec221c5-4cbc-4fd5-ae2e-6eebd1311876」
`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" : "b5a3cb32-3ca8-4b0b-9510-c6a9e70f00f4",
  "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" : "803821e5-2626-41d5-8ea2-04b6fdb88f8c",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "HEQiFiTuneH7NJVZ-kHxnbZyU9...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

フィールド

フィールド	説明	データ型
`eventId`	イベントの一意の識別子。	`string` 例: 「803821e5-2626-41d5-8ea2-04b6fdb88f8c」
`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 によって処理され、いつでも変更される可能性があります。A developer は、SDM API によって提供されるイベントスレッドとセッションに基づいて通知を更新する必要があります。

スレッドの状態

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

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

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

イベントフィルタリング

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

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

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

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

サービスアカウント

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

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

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 クライアントライブラリ