通知を使用すると、smart home アクションは Google Assistant を使用して、デバイスに関する重要なイベントや変更についてユーザーとやり取りできます。通知を設定しておくと、玄関に人がいるときや、デバイスの状態の変化(ドアの錠が正常に取り付けられたときや詰まったときなど)について通知を受け取ることができます。
smart home アクションでは、次のタイプの通知をユーザーに送信できます。
パーソナル通知: デバイスへの事前のリクエスト(ドアホンのベルの呼び出しなど)なしで smart home デバイス イベントについてユーザーに通知します。
フォローアップ レスポンス: デバイス コマンドのリクエスト(ドアのロックなど)が成功したか失敗したかを確認できます。これらのアラートは、完了に時間がかかるデバイス コマンドに使用します。フォローアップ レスポンスは、デバイス コマンド リクエストがスマート スピーカーとスマートディスプレイから送信されている場合にのみサポートされます。
Assistant は、スマート スピーカーやスマートディスプレイでユーザーに通知として通知します。プロアクティブな通知はデフォルトでオフになっています。ユーザーは Google Home app (GHA) からのすべての通知を個別にオンまたはオフにできます。
通知をトリガーするイベント
デバイス イベントが発生すると、アクションのフルフィルメントから Google に通知リクエストが送信されます。smart home アクションがサポートするデバイス トレイトにより、利用可能な通知イベントの種類と、そうした通知に含めるデータが決まります。
以下のトレイトではパーソナル通知がサポートされます。
トレイト | イベント |
---|---|
ObjectDetection | デバイスによって物体などが検出されたときに通知します。たとえば、認識済みの顔を玄関で検出した場合などです。例:「玄関に愛理さんと祐介さんがいます。」 |
RunCycle | デバイスがサイクルを完了したときに通知します。例: 「洗濯が完了しました。」 |
SensorState | デバイスが、サポートされているセンサーの状態を検出したときに通知します。例: 「煙探知器が煙を検知しました。」 |
TemperatureControl | デバイスが設定温度に達したときに通知します。例: 「オーブンが 350 度に予熱されました。」 |
ArmDisarm | ドアが開くと、システムが作動待機のカウントダウンが設定された事前アラームの状態になります。 |
CameraStream | デバイスで物体やモーションが検知されると、カメラのライブ ストリームにリンクします。 |
MotionDetection | 「2020 年 7 月 1 日午後 0 時にモーションが検知されました。」 |
以下のトレイトではフォローアップ レスポンスがサポートされます。
トレイト | イベント |
---|---|
ArmDisarm | action.devices.commands.ArmDisarm デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「セキュリティ システムの監視を有効にしました。」 |
LockUnlock | action.devices.commands.LockUnlock デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「玄関のドアをロックしました。」、「玄関のドアが正常に動作しません。」
|
NetworkControl | action.devices.commands.TestNetworkSpeed デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「ネットワーク速度のテストが完了しました。オフィス ルーターの現在のダウンロード速度は 80.2 Kbps、アップロード速度は 9.3 Kbps です。」
|
OpenClose | action.devices.commands.OpenClose デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「玄関のドアを開けました。」、「ドアを開けることができませんでした。」
|
StartStop | action.devices.commands.StartStop デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例: 「掃除機が始動しました。」
|
すべてのデバイスタイプは、該当するトレイトの通知をサポートします。
スマートホーム アクションの通知の作成
次の段階で、smart home アクションに通知を追加します。
- smart home デバイスアプリから通知が有効になっているかどうかを Google に通知します。ユーザーがアプリで通知をオンまたはオフにする場合は、
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 で通知をトリガーするには、フルフィルメントが Report State と Notification API 呼び出しを介して Google Home Graph に通知ペイロードを送信します。
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 リクエストの例を次に示します。- Google Home Graph エンドポイントへの Report State および通知 JSON と、HTTP POST リクエストのトークンを組み合わせます。次の例では、テストとして
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 Client は 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);
フォローアップ レスポンス ペイロードを送信する
フォローアップ レスポンスのペイロードには、リクエストのステータス、イベント障害のエラーコード(該当する場合)、EXECUTE
インテント リクエスト中に指定された有効な followUpToken
が含まれます。followUpToken
は、有効な状態が維持され、レスポンスが元のリクエストと正しく関連付けられるように、5 分以内に使用する必要があります。
次のスニペットは、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 リクエストの例を次に示します。- Google Home Graph エンドポイントへの Report State および通知 JSON と、HTTP POST リクエストのトークンを組み合わせます。次の例では、テストとして
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 Client は 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
など)を格納することもできます。