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

通知により、Cloud-to-cloud 統合は Google Assistantを使用して重要なデバイス関連のアクティビティや変更をユーザーに伝えることができます。通知を実装することで、デバイスのアクティビティ(誰かが玄関に来ているなど)についてユーザーに適宜知らせたり、リクエストされたデバイスのステータスが変わったこと(ドアの鍵が正常にかかったかどうかなど)を報告したりできます。

Cloud-to-cloud 統合がユーザーに送信できる通知の種類は次のとおりです。

  • パーソナル通知: 事前にユーザーからのリクエストなしでsmart home デバイスのアクティビティ(玄関のドアホンが鳴ったなど)を通知します。

  • フォローアップ レスポンス: デバイス コマンドのリクエスト(ドアのロックなど)が成功したか失敗したかの確認です。この種類の通知は、完了までに時間がかかるデバイス コマンドに使用します。フォローアップ レスポンスは、デバイス コマンドのリクエストがスマート スピーカーやスマートディスプレイから送信される場合のみサポートされます。

Assistantは、これらの通知をスマート スピーカーやスマートディスプレイを通じてお知らせとしてユーザーに提供します。パーソナル通知は、デフォルトでは無効になっています。ユーザーは、Google Home app (GHA)からのすべてのパーソナル通知のオン / オフを切り替えることができます。

通知をトリガーするアクティビティ

デバイスのアクティビティが発生すると、フルフィルメントから Google に通知リクエストが送信されます。どの種類の通知アクティビティが利用可能で、それらの通知にどの種類のデータを追加できるかは、Cloud-to-cloud 統合がサポートするデバイス トレイトによって異なります。

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

トレイト アクティビティ
ObjectDetection デバイスによって物体などが検出されたときに通知します。たとえば、認識済みの顔を玄関で検出した場合などです。例:「玄関に愛理さんと祐介さんがいます。」
RunCycle デバイスがサイクルを完了したときに通知します。例: 「洗濯が完了しました。」
SensorState デバイスが、サポートされているセンサーの状態を検出したときに通知します。例: 「煙探知器が煙を検知しました。」

以下のトレイトではフォローアップ レスポンスがサポートされます。

トレイト アクティビティ
LockUnlock action.devices.commands.LockUnlock デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「玄関のドアをロックしました。」、「玄関のドアが正常に動作しません。」
NetworkControl action.devices.commands.TestNetworkSpeed デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「ネットワーク速度のテストが完了しました。オフィス ルーターの現在のダウンロード速度は 80.2 Kbps、アップロード速度は 9.3 Kbps です。」
OpenClose action.devices.commands.OpenClose デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例:「玄関のドアを開けました。」、「玄関のドアを開けることができませんでした。」

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

Cloud-to-cloud 統合の通知の作成

以下のステージで Cloud-to-cloud 統合に通知を追加します。

  1. smart home デバイス アプリから通知が有効になっているかどうかを Google に知らせます。ユーザーがアプリ内で通知をオンまたはオフにしたら、SYNC リクエストを送信してデバイスでの変更を Google に伝えます。
  2. デバイスのアクティビティまたはステータスの変化によって通知がトリガーされたら、Report State reportStateAndNotification API を呼び出して通知リクエストを送信します。デバイスのステータスが変化した場合は、ステータスと通知ペイロードの両方を一緒に Report State and Notification 呼び出しで送信できます。

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

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

ユーザーは、パーソナル通知の受信を希望する場合は GHA でこの機能を有効にすることで指定できます。smart home デバイスのアプリ自体(たとえば、アプリの設定)に、ユーザーがデバイスからの通知を明示的に切り替える機能を追加することもできます。

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

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

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

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

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

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

フルフィルメントは、Assistantで通知をトリガーするため、Report State and Notification API 呼び出しGoogle Home Graph に通知ペイロードを送信します。

Google HomeGraph API を有効にする

  1. Google Cloud Consoleで [HomeGraph API] ページに移動します。

    [HomeGraph API] ページに移動します。
  2. smart home プロジェクト ID と一致するプロジェクトを選択します。
  3. [有効にする] をクリックします。

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

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

: 以下の手順を行う場合は、正しい GCP プロジェクト(smart home プロジェクト ID と一致するプロジェクト)を使用していることをご確認ください。
  1. Google Cloud Consoleで [サービス アカウント] ページに移動します。

    [サービス アカウント] ページに移動します。

    [サービス アカウント] ページに進むには、プロジェクトの選択が必要になることがあります。

  2. [ サービス アカウントを作成] をクリックします。

  3. [サービス アカウント名] フィールドに名前を入力します。

  4. [サービス アカウント ID] フィールドに ID を入力します。

  5. [サービス アカウントの説明] フィールドに説明を入力します。

  6. [作成して続行] をクリックします。

  7. [ロール] プルダウンから、[サービス アカウント] > [サービス アカウントの OpenID Connect ID トークン作成者] を選択します。

  8. [続行] をクリックします。

  9. [完了] をクリックします。

  10. サービス アカウントのリストから、作成した上記のサービス アカウントを選択し、 の [操作] メニューから [鍵を管理] を選択します。

  11. [鍵を追加] > [新しい鍵を作成] を選択します。

  12. [キーのタイプ] として [JSON] を選択します。

  13. [作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。

サービス アカウント キーの詳しい作成手順と情報については、Google Cloud コンソールのヘルプサイトのサービス アカウント キーの作成と削除をご覧ください。

通知を送信する

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

API 呼び出しに渡す notifications オブジェクトには、通知をどう表示するかを定義する priority 値を含めます。notifications オブジェクト内のフィールドは、デバイス トレイトに応じて異なります。

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

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

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

HTTPgRPCNode.jsJava

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

  1. ダウンロードしたサービス アカウントの JSON ファイルを使用して、JSON ウェブトークン(JWT)を作成します。詳細については、サービス アカウントを使用した認証をご覧ください。
  2. oauth2l を使用し、https://www.googleapis.com/auth/homegraph スコープを指定して OAuth 2.0 アクセス トークンを取得します。
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId を使用して JSON リクエストを作成します。 次に、Report State and Notification の JSON リクエストの例を示します。
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
  6. Google Home Graph エンドポイントへの HTTP POST リクエストに、Report State and Notification の JSON とトークンを含めます。次の例では、テストとして curl を使用してコマンドラインでリクエストを行う方法を示します。
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

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

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

Google API Node.js クライアントは、Home Graph API のバインディングを提供します。

  1. アプリケーションのデフォルト認証情報を使用して、google.homegraph サービスを初期化します。
  2. ReportStateAndNotificationRequest を使用して reportStateAndNotification メソッドを呼び出します。ReportStateAndNotificationResponsePromise が返されます。
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 用 HomeGraph API クライアント ライブラリは、Home Graph API のバインディングを提供します。

  1. アプリケーションのデフォルト認証情報を使用して HomeGraphApiService を初期化します。
  2. 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 を呼び出すには、次のいずれかのタブを選択してください。

HTTPgRPCNode.jsJava

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

  1. ダウンロードしたサービス アカウントの JSON ファイルを使用して、JSON ウェブトークン(JWT)を作成します。詳細については、サービス アカウントを使用した認証をご覧ください。
  2. oauth2l を使用し、https://www.googleapis.com/auth/homegraph スコープを指定して OAuth 2.0 アクセス トークンを取得します。
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId を使用して JSON リクエストを作成します。 次に、Report State and Notification の JSON リクエストの例を示します。
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
  6. Google Home Graph エンドポイントへの HTTP POST リクエストに、Report State and Notification の JSON とトークンを含めます。次の例では、テストとして curl を使用してコマンドラインでリクエストを行う方法を示します。
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

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

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

Google API Node.js クライアントは、Home Graph API のバインディングを提供します。

  1. アプリケーションのデフォルト認証情報を使用して、google.homegraph サービスを初期化します。
  2. ReportStateAndNotificationRequest を使用して reportStateAndNotification メソッドを呼び出します。 ReportStateAndNotificationResponsePromise が返されます。
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 用 HomeGraph API クライアント ライブラリは、Home Graph API のバインディングを提供します。

  1. アプリケーションのデフォルト認証情報を使用して HomeGraphApiService を初期化します。
  2. 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-to-cloud の 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 など)を格納することもできます。