スマートホームアクションの通知

スマートホームアクションで通知を使用すると、デバイスに関する重要なイベントや変更について、Google アシスタントを介してユーザーに通知できます。通知を実装することで、デバイスイベント（誰かが玄関に来ているなど）についてユーザーにタイミングよく知らせたり、リクエストされたデバイスのステータスが変わったこと（ドアの鍵が正常にかかったかどうかなど）を報告したりできます。

スマートホームアクションでは、ユーザーに対して以下のタイプの通知を送信できます。

パーソナル通知: スマートホームデバイスイベント（玄関のドアフォンが鳴ったなど）について、ユーザーからのリクエストなしで通知します。
フォローアップレスポンス: デバイスコマンドのリクエスト（ドアのロックなど）が成功したか失敗したかを確認できます。このタイプのアラートは、完了までに時間がかかるデバイスコマンドに使用します。

Google アシスタントはこれらの通知を、スマートスピーカーやスマートディスプレイを通じてお知らせとして提供します。パーソナル通知は、デフォルトでは無効になっています。ユーザーは、Google Home アプリからすべてのパーソナル通知をオンまたはオフにできます。

通知をトリガーするイベント

デバイスイベントが発生すると、アクションのフルフィルメントから Google に通知リクエストが送信されます。どのタイプの通知イベントを使用でき、それらの通知にどのデータを含めることができるかは、スマートホームアクションがサポートするデバイストレイトによって異なります。

以下のトレイトではパーソナル通知がサポートされます。

トレイト	イベント
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` デバイスコマンド実行後の完了ステータスと、ステータスの変化を通知します。例: 「掃除機が始動しました。」

すべてのデバイスタイプは、該当するトレイトの通知をサポートします。

スマートホームアクションの通知の作成

スマートホームアクションに通知を追加する手順は次のとおりです。

スマートホームデバイスアプリで通知が有効になっているかどうかを Google に知らせる必要があります。ユーザーがアプリ内で通知をオンまたはオフにした場合は、SYNC リクエストを送信してデバイスでの変更を Google に知らせます。
デバイスのイベントまたはステータスの変化によって通知がトリガーされたら、Report State reportStateAndNotification API を呼び出して通知リクエストを送信します。デバイスのステータスが変化した場合は、Report State 呼び出しと Notification 呼び出しで、ステータスペイロードと通知ペイロードを一緒に送信できます。

以下のセクションでは、その手順について詳しく説明します。

アプリで通知が有効になっているかどうかを知らせる

ユーザーは、Google Home アプリで通知を有効または無効にすることで、パーソナル通知を受け取るかどうかを選択できます。スマートホームデバイスアプリ自体（たとえばアプリの設定）に、ユーザーが明示的に通知機能を切り替える機能を追加することもできます。

デバイスへの通知が有効になっていることを Google に知らせるため、Request SYNC を呼び出してデバイスデータを更新します。ユーザーがアプリでこの設定を変更したときは、このような SYNC リクエストを送信する必要があります。

SYNC レスポンスで、次のいずれかの更新を送信します。

ユーザーがデバイスアプリで通知を明示的に切り替えた場合や、切り替えオプションを提供していない場合は、devices.notificationSupportedByAgent プロパティを true に設定します。
ユーザーがデバイスアプリで通知を明示的にオフにした場合は、devices.notificationSupportedByAgent プロパティを false に設定します。

次のスニペットに、SYNC レスポンスを設定する例を示します。

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Google に通知リクエストを送信する

フルフィルメントは、アシスタントで通知をトリガーするため、Report State と Notification の API 呼び出しによって Google ホームグラフに通知ペイロードを送信します。

Google HomeGraph API を有効にする

Google Cloud Platform Console で、[HomeGraph API] ページに移動します。
[HomeGraph API] ページに移動
自分のスマートホームプロジェクトと ID が一致するプロジェクトを選択します。
[有効にする] をクリックします。

サービスアカウントキーを作成する

GCP Console からサービスアカウントキーを生成する手順は次のとおりです。

注: 以下の手順を行う場合は、正しい GCP プロジェクト（スマートホームプロジェクト ID と一致するプロジェクト）を使用していることをご確認ください。

GCP Console で [サービスアカウントキーの作成] ページに移動します。
[サービスアカウントキーの作成] ページに移動
[サービスアカウント] リストから [新しいサービスアカウント] を選択します。
[サービスアカウント名] フィールドに名前を入力します。
[サービスアカウント ID] フィールドに ID を入力します。
[ロール] リストから、[サービスアカウント] > [サービスアカウントトークン作成者] を選択します。
[キーのタイプ] として [JSON] を選択します。
[作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。

通知を送信する

devices.reportStateAndNotification API を使用して通知リクエストを呼び出します。JSON リクエストには、どのイベントが通知をトリガーしたかを特定するための eventId を含める必要があります。eventId は、通知リクエストを送信するたびに変える必要があるため、プラットフォームでランダムな ID を生成してください。

API 呼び出しに渡す notifications オブジェクトには、通知をどう提供するかを定義する priority 値を含めます。notifications オブジェクトには、デバイストレイトに応じてさまざまなフィールドが含まれます。

次のいずれかの方法でペイロードを設定し、API を呼び出します。

パーソナル通知ペイロードを送信する
フォローアップレスポンスペイロードを送信する

パーソナル通知ペイロードを送信する

API を呼び出すには、次のいずれかのタブを選択してください。

HTTP

HomeGraph API は HTTP エンドポイントを提供します。

ダウンロードしたサービスアカウントの JSON ファイルを使用して、JSON ウェブトークン（JWT）を作成します。詳細については、サービスアカウントを使用した認証をご覧ください。
oauth2l を使用し、https://www.googleapis.com/auth/homegraph スコープを指定して OAuth 2.0 アクセストークンを取得します。

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

agentUserId を使用して JSON リクエストを作成します。次に Report State と Notification の JSON リクエストの例を示します。

{
  "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
            }
          }
        }
      }
    }
  }
}

Google ホームグラフエンドポイントに送信する HTTP POST リクエストに、Report State JSON、Notification JSON、アクセストークンを含めます。次の例では、テストとして curl を使用してコマンドラインでリクエストを行う方法を示します。

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

HomeGraph API は gRPC エンドポイントを提供します。

HomeGraph API 用のプロトコルバッファサービス定義を取得します。
gRPC デベロッパー向けドキュメントに沿って、サポートされている言語のうちいずれかのクライアントスタブを生成します。
ReportStateAndNotification メソッドを呼び出します。

Node.js

Google API Node.js クライアントは、HomeGraph 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 クライアントライブラリは、HomeGraph 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

HomeGraph API は HTTP エンドポイントを提供します。

ダウンロードしたサービスアカウントの JSON ファイルを使用して、JSON ウェブトークン（JWT）を作成します。詳細については、サービスアカウントを使用した認証をご覧ください。
oauth2l を使用し、https://www.googleapis.com/auth/homegraph スコープを指定して OAuth 2.0 アクセストークンを取得します。

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

agentUserId を使用して JSON リクエストを作成します。次に Report State と Notification の JSON リクエストの例を示します。

{
  "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
            }
          }
        }
      }
    }
  }
}

Google ホームグラフエンドポイントに送信する HTTP POST リクエストに、Report State JSON、Notification JSON、アクセストークンを含めます。次の例では、テストとして curl を使用してコマンドラインでリクエストを行う方法を示します。

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

HomeGraph API は gRPC エンドポイントを提供します。

HomeGraph API 用のプロトコルバッファサービス定義を取得します。
gRPC デベロッパー向けドキュメントに沿って、サポートされている言語のうちいずれかのクライアントスタブを生成します。
ReportStateAndNotification メソッドを呼び出します。

Node.js

Google API Node.js クライアントは、HomeGraph 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 クライアントライブラリは、HomeGraph 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);

ロギング

スマートホームのモニタリングとロギングに関するドキュメントで説明されているように、通知ではイベントログがサポートされます。イベントログは、アクション内の通知品質のテストや維持に活用できます。

次に、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`	Google Home アプリで、通知対象デバイスの通知が有効になっていないことを示します。このステータスは、まだ本番環境にリリースされていないアクションでのみ使用できます。
`NOTIFYING_DEVICE_NOT_IN_STRUCTURE`	通知対象デバイスが、家またはストラクチャに割り当てられていないことを示します。このステータスは、まだ本番環境にリリースされていないアクションでのみ使用できます。

status フィールドには、すべての通知に適用できる一般的なステータスに加え、トレイト固有のステータス（OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING など）を格納することもできます。

スマートホーム アクションの通知

通知をトリガーするイベント

スマートホーム アクションの通知の作成

アプリで通知が有効になっているかどうかを知らせる

Google に通知リクエストを送信する

Google HomeGraph API を有効にする

サービス アカウント キーを作成する

通知を送信する

パーソナル通知ペイロードを送信する

HTTP

gRPC

Node.js

Java

フォローアップ レスポンス ペイロードを送信する

HTTP

gRPC

Node.js

Java

ロギング

スマートホームアクションの通知

スマートホームアクションの通知の作成

サービスアカウントキーを作成する

フォローアップレスポンスペイロードを送信する