Google Home Developer Center へようこそ。スマートホーム アクションの開発方法を学習できます。注: アクションの構築は、引き続き Actions Console で行います。

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

通知を使用すると、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 アクションに通知を追加します。

  1. smart home デバイスアプリから通知が有効になっているかどうかを Google に通知します。ユーザーがアプリで通知をオンまたはオフにする場合は、SYNC リクエストを送信してデバイスの変更を Google に通知します。
  2. 通知をトリガーするデバイスのイベントまたは状態の変化が発生した場合は、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 を有効にする

  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. [キーのタイプ] として [JSON] を選択します。

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

通知を送信する

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

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

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

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

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

HTTP

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 と通知の 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 エンドポイントへの Report State および通知 JSON と、HTTP POST リクエストのトークンを組み合わせます。次の例では、テストとして 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

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

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

Node.js

Google API Node.js ClientHome 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

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 を呼び出すには、次のいずれかのタブを選択してください。

HTTP

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 と通知の 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 エンドポイントへの Report State および通知 JSON と、HTTP POST リクエストのトークンを組み合わせます。次の例では、テストとして 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

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

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

Node.js

Google API Node.js ClientHome 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

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