通知により、smart home アクションで使用できるようになります 重要なポイントについてユーザーとやり取りするには、Google Assistant デバイス関連のイベントや変更を検出します。特定のアラートやケースに デバイスのイベント(玄関に誰かが来たとき、または リクエストされたデバイス状態の変化(ドアのロックボルトが 正常にエンゲージしているか ジャムが発生しているかがわかります
smart home アクションは、次のタイプのメッセージを送信できます。 ユーザーに通知することができます。
プロアクティブ通知: smart home に関するアラートをユーザーに通知します。 ユーザーのデバイスへの事前リクエストがないデバイス イベント ドアホンのベルが鳴ります。
フォローアップ レスポンス: デバイス コマンドのリクエスト(ドアのロックなど)が成功したか失敗したかを確認できます。これらのアラートの用途 完了に時間がかかるデバイス コマンドです。フォローアップの回答は、 スマート スピーカーやスマート スピーカーからデバイス コマンド リクエストが送信される場合のサポート 表示されます。
Assistant は、これらの通知を次のユーザーに提供します。 スマート スピーカーやスマートディスプレイでの通知を確認できます。パーソナル通知 デフォルトで無効になっています。 ユーザーは、Google Chat で Google Home app (GHA)。
通知をトリガーするイベント
デバイス イベントが発生すると、アクションのフルフィルメントから Google に通知リクエストが送信されます。smart home アクションのデバイス トレイト は、使用可能な通知イベントのタイプと、 できます。
以下のトレイトではパーソナル通知がサポートされます。
トレイト | イベント |
---|---|
ObjectDetection | デバイスによって物体などが検出されたときに通知します。たとえば、認識済みの顔を玄関で検出した場合などです。例:「玄関に愛理さんと祐介さんがいます。」 |
RunCycle | デバイスがサイクルを完了したときに通知します。例: 「洗濯が完了しました。」 |
SensorState | デバイスが、サポートされているセンサーの状態を検出したときに通知します。例: 「煙探知器が煙を検知しました。」 |
以下のトレイトではフォローアップ レスポンスがサポートされます。
トレイト | イベント |
---|---|
LockUnlock | action.devices.commands.LockUnlock デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「玄関のドアをロックしました。」、「玄関のドアが正常に動作しません。」
|
NetworkControl | action.devices.commands.TestNetworkSpeed デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「ネットワーク速度のテストが完了しました。オフィス ルーターの現在のダウンロード速度は 80.2 Kbps、アップロード速度は 9.3 Kbps です。」
|
OpenClose | action.devices.commands.OpenClose デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「玄関のドアを開けました。」、「ドアを開けることができませんでした。」
|
すべてのデバイスタイプは、該当するトレイトの通知をサポートします。
スマートホーム アクションの通知の作成
次のステージで smart home アクションに通知を追加します。
- あなたのソースからの通知が有効になっているかどうかを Google に知らせる
smart home デバイスアプリ。ユーザーが通知をオンまたはオフにするかどうか
アプリで
SYNC
リクエストを送信して、デバイスの変更を Google に通知します。 - 関連するデバイスのイベントまたは状態変化が発生し、
次のメソッドを呼び出して通知リクエストを送信します。
Report State
reportStateAndNotification
API。もし デバイスの状態が変更された場合は、状態と通知ペイロードの両方を Report State と通知の呼び出しで一緒に使用できます。
以下のセクションでは、その手順について詳しく説明します。
アプリで通知が有効になっているかどうかを知らせる
ユーザーは次の方法でプロアクティブな通知を受け取るかどうかを選択できます。 GHA でこの機能を有効にします。お使いの smart home デバイスでは、次の機能を必要に応じて追加することもできます。 ユーザーがデバイスからの通知を明示的に切り替えます。たとえば、 アプリの設定を変更します。
デバイスへの通知が有効になっていることを Google に知らせるため、Request SYNC を呼び出してデバイスデータを更新します。ユーザーがアプリでこの設定を変更したときは、このような SYNC
リクエストを送信する必要があります。
SYNC
レスポンスで、次のいずれかの更新を送信します。
- ユーザーがデバイスアプリで通知を明示的に切り替えた場合や、切り替えオプションを提供していない場合は、
devices.notificationSupportedByAgent
プロパティをtrue
に設定します。 - ユーザーがデバイスアプリで通知を明示的にオフにした場合は、
devices.notificationSupportedByAgent
プロパティをfalse
に設定します。
次のスニペットに、SYNC レスポンスを設定する例を示します。
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Google に通知リクエストを送信する
Assistant で通知をトリガーするには、 フルフィルメントが通知ペイロードを Google Home Graph に送信 Report State と Notification API 呼び出し。
Google HomeGraph API を有効にする
-
Google Cloud Console で、[HomeGraph API] ページに移動します。
[HomeGraph API] ページに移動 - smart home プロジェクト ID と一致するプロジェクトを選択します。
- [有効にする] をクリックします。
サービス アカウント キーを作成する
Google Cloud Console からサービス アカウント キーを生成する手順は次のとおりです。
-
Google Cloud Console で、[サービス アカウント キーの作成] ページに移動します。
[サービス アカウント キーの作成] ページに移動 - [サービス アカウント] リストから [新しいサービス アカウント] を選択します。
- [サービス アカウント名] フィールドに名前を入力します。
- [サービス アカウント ID] フィールドに ID を入力します。
[ロール] リストから、[サービス アカウント] > [サービス アカウント トークン作成者] を選択します。
[キーのタイプ] として [JSON] を選択します。
- [作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。
通知を送信する
次のコマンドを使用して通知リクエストの呼び出しを行います。
devices.reportStateAndNotification
API。
JSON リクエストには、どのイベントが通知をトリガーしたかを特定するための eventId
を含める必要があります。eventId
は、通知リクエストを送信するたびに変える必要があるため、プラットフォームでランダムな ID を生成してください。
API 呼び出しに渡す notifications
オブジェクトには、通知をどう提供するかを定義する priority
値を含めます。お客様の
notifications
オブジェクトに含まれるフィールドは、デバイスによって異なります。
あります。
次のいずれかの方法でペイロードを設定し、API を呼び出します。
パーソナル通知ペイロードを送信する
API を呼び出すには、次のいずれかのタブを選択してください。
HTTP
Home Graph API は HTTP エンドポイントを提供します。
- ダウンロードしたサービス アカウントの JSON ファイルを使用して、JSON ウェブトークン(JWT)を作成します。詳細については、サービス アカウントを使用した認証をご覧ください。
- oauth2l を使用し、
https://www.googleapis.com/auth/homegraph
スコープを指定して OAuth 2.0 アクセス トークンを取得します。 agentUserId
を使用して JSON リクエストを作成します。 以下に、Report State と通知に対する JSON リクエストの例を示します。- Report State および通知 JSON と、HTTP POST のトークンを組み合わせる
Google Home Graph エンドポイントに送信します。これは
コマンドラインで
curl
を使用してリクエストを行います。 テスト:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "ObjectDetection": { "priority": 0, "detectionTimestamp": 1534875126750, "objects": { "named": [ "Alice" ], "unclassified": 2 } } } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
Home Graph API は、 gRPC エンドポイント
- Home Graph API のプロトコル バッファ サービス定義を取得します。
- gRPC デベロッパー向けドキュメントに沿って、サポートされている言語のうちいずれかのクライアント スタブを生成します。
- ReportStateAndNotification メソッドを呼び出します。
Node.js
Google API Node.js クライアントは、Home Graph API のバインディングを提供します。
- アプリケーションのデフォルト認証情報を使用して、
google.homegraph
サービスを初期化します。 - ReportStateAndNotificationRequest を使用して
reportStateAndNotification
メソッドを呼び出します。ReportStateAndNotificationResponse でPromise
が返されます。
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.reportStateAndNotification({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { ObjectDetection: { priority: 0, detectionTimestamp: 1534875126750, objects: { named: ['Alice'], unclassified: 2 } } } } } } } });
Java
Java 用 HomeGraph API クライアント ライブラリには、Home Graph API のバインディングが用意されています。
- アプリケーションのデフォルト認証情報を使用して
HomeGraphApiService
を初期化します。 ReportStateAndNotificationRequest
を使用してreportStateAndNotification
メソッドを呼び出します。ReportStateAndNotificationResponse
が返されます。
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Build device notification payload. Map<?, ?> notifications = Map.of( "ObjectDetection", Map.of( "priority", 0, "detectionTimestamp", 1534875126, "objects", Map.of("named", List.of("Alice"), "unclassifed", 2))); // Send notification. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications)))); homegraphService.devices().reportStateAndNotification(request);
フォローアップ レスポンス ペイロードを送信する
フォローアップ レスポンスのペイロードには、リクエストのステータス、エラーが含まれる
イベント障害のコード(該当する場合)と有効な followUpToken
。
EXECUTE
インテントのリクエスト時に指定します。followUpToken
を使用する必要があります。
有効な状態を維持し、レスポンスを適切に関連付けて
変換できます
次のスニペットは、followUpToken
フィールドを使用した EXECUTE
リクエスト ペイロードの例を示しています。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123", }], "execution": [{ "command": "action.devices.commands.TestNetworkSpeed", "params": { "testDownloadSpeed": true, "testUploadSpeed": false, "followUpToken": "PLACEHOLDER" } }] }] } }] };
followUpToken
を使用することで、通知をすべてのデバイスにブロードキャストするのではなく、ユーザーが元々対話していたデバイスにのみ出力することができます。
API を呼び出すには、次のいずれかのタブを選択してください。
HTTP
Home Graph API は HTTP エンドポイントを提供します。
- ダウンロードしたサービス アカウントの JSON ファイルを使用して、JSON ウェブトークン(JWT)を作成します。詳細については、サービス アカウントを使用した認証をご覧ください。
- oauth2l を使用し、
https://www.googleapis.com/auth/homegraph
スコープを指定して OAuth 2.0 アクセス トークンを取得します。 agentUserId
を使用して JSON リクエストを作成します。 以下に、Report State と通知に対する JSON リクエストの例を示します。- Report State および通知 JSON と、HTTP POST のトークンを組み合わせる
Google Home Graph エンドポイントに送信します。これは
コマンドラインで
curl
を使用してリクエストを行います。 テスト:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "NetworkControl": { "priority": 0, "followUpResponse": { "status": "SUCCESS", "followUpToken": "PLACEHOLDER", "networkDownloadSpeedMbps": 23.3, "networkUploadSpeedMbps": 10.2 } } } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
Home Graph API は gRPC エンドポイントを提供します。
- Home Graph API のプロトコル バッファ サービス定義を取得します。
- gRPC デベロッパー向けドキュメントに沿って、サポートされている言語のうちいずれかのクライアント スタブを生成します。
- ReportStateAndNotification メソッドを呼び出します。
Node.js
Google API Node.js クライアントは、Home Graph API のバインディングを提供します。
- アプリケーションのデフォルト認証情報を使用して、
google.homegraph
サービスを初期化します。 - ReportStateAndNotificationRequest を使用して
reportStateAndNotification
メソッドを呼び出します。ReportStateAndNotificationResponse でPromise
が返されます。
const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken; const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.reportStateAndNotification({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { NetworkControl: { priority: 0, followUpResponse: { status: 'SUCCESS', followUpToken, networkDownloadSpeedMbps: 23.3, networkUploadSpeedMbps: 10.2, } } } } } } } });
Java
Java 用 HomeGraph API クライアント ライブラリには、Home Graph API のバインディングが用意されています。
- アプリケーションのデフォルト認証情報を使用して
HomeGraphApiService
を初期化します。 ReportStateAndNotificationRequest
を使用してreportStateAndNotification
メソッドを呼び出します。ReportStateAndNotificationResponse
が返されます。
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Extract follow-up token. ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0]; String followUpToken = (String) executeInputs .getPayload() .getCommands()[0] .getExecution()[0] .getParams() .get("followUpToken"); // Build device follow-up response payload. Map<?, ?> followUpResponse = Map.of( "NetworkControl", Map.of( "priority", 0, "followUpResponse", Map.of( "status", "SUCCESS", "followUpToken", followUpToken, "networkDownloadSpeedMbps", 23.3, "networkUploadSpeedMbps", 10.2))); // Send follow-up response. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse)))); homegraphService.devices().reportStateAndNotification(request);
ロギング
Cloud Logging を使用してイベントログにアクセスするで説明されているように、通知はイベント ロギングをサポートしています。 イベントログは、アクション内の通知品質のテストや維持に活用できます。
次に、notificationLog
エントリのスキーマを示します。
プロパティ | 説明 |
---|---|
requestId |
通知リクエスト ID。 |
structName |
通知構造体の名前(「ObjectDetection」など)。 |
status |
通知のステータス。 |
status
フィールドには、エラーを示すさまざまなステータスが表示されます。
記述できます。その一部は、特定のアクションでしか利用できない
まだリリースされていない状態です
以下にステータスの例を示します。
ステータス | 説明 |
---|---|
EVENT_ID_MISSING |
必須の eventId フィールドが欠落していることを示します。 |
PRIORITY_MISSING |
priority フィールドが欠落していることを示します。 |
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
SYNC で指定された通知デバイスの notificationSupportedByAgent プロパティが false であることを示します。
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
GHA で、ユーザーが通知元のデバイスで通知を有効にしていないことを示します。このステータスは、本番環境にリリースされていないアクションでのみ使用できます。 |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
通知対象デバイスが、家またはストラクチャに割り当てられていないことを示します。このステータスは、まだ本番環境にリリースされていないアクションでのみ使用できます。 |
status
フィールドには、すべての通知に適用できる一般的なステータスに加え、トレイト固有のステータス(OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
など)を格納することもできます。