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

スマートホーム アクションで通知を使用すると、デバイスに関する重要なイベントや変更について、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 デバイス コマンド実行後の完了ステータスと、ステータスの変化を通知します。例: 「掃除機が始動しました。」

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

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

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

  1. スマートホーム デバイス アプリで通知が有効になっているかどうかを Google に知らせる必要があります。ユーザーがアプリ内で通知をオンまたはオフにした場合は、SYNC リクエストを送信してデバイスでの変更を Google に知らせます。
  2. デバイスのイベントまたはステータスの変化によって通知がトリガーされたら、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 を有効にする

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

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

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

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

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

    [サービス アカウント キーの作成] ページに移動
  2. [サービス アカウント] リストから [新しいサービス アカウント] を選択します。
  3. [サービス アカウント名] フィールドに名前を入力します。
  4. [サービス アカウント ID] フィールドに ID を入力します。
  5. [ロール] リストから、[サービス アカウント] > [サービス アカウント トークン作成者] を選択します。

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

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

通知を送信する

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

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

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

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

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

HTTP

HomeGraph 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 と 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 ホームグラフ エンドポイントに送信する HTTP POST リクエストに、Report State JSON、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"
    

gRPC

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

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

Node.js

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

Java 用 HomeGraph API クライアント ライブラリは、HomeGraph 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 を呼び出すには、次のいずれかのタブを選択してください。

HTTP

HomeGraph 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 と 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 ホームグラフ エンドポイントに送信する HTTP POST リクエストに、Report State JSON、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"
    

gRPC

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

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

Node.js

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

Java 用 HomeGraph API クライアント ライブラリは、HomeGraph 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);
    

ロギング

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

次に、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 など)を格納することもできます。