智慧住宅動作通知

通知可讓 Cloud-to-cloud 整合使用 Google Assistant，向使用者傳達與裝置相關的重要事件或變更。您可以實作通知，讓使用者及時收到裝置事件通知，例如有人在門口時，或是回報要求的裝置狀態變更，例如門鎖栓已成功連結或卡住時。

您的 Cloud-to-cloud 整合功能可以向使用者傳送下列類型的通知：

  • 主動通知：在使用者未向裝置提出任何要求 (例如門鈴響鈴) 的情況下，提醒使用者有關 smart home 裝置事件的資訊。

  • 後續回應：確認裝置指令要求是否成功或失敗，例如鎖門時。請針對需要較長時間才能完成的裝置指令使用這些快訊。只有在智慧音箱和智慧螢幕傳送裝置指令要求時，系統才會支援後續回應。

Assistant 會將這些通知以廣播形式傳送給使用者，並透過智慧型喇叭和智慧型螢幕播放。主動式通知預設為關閉。使用者可以透過 Google Home app (GHA) 開啟或關閉所有主動通知。

觸發通知的事件

裝置事件發生時，執行要求會將通知要求傳送給 Google。Cloud-to-cloud 整合功能支援的裝置特徵會決定可用的通知事件類型，以及您可在這些通知中加入的資料。

下列特徵支援主動通知：

特徵 活動
ObjectDetection 裝置偵測到的物體，例如在門口偵測到已辨識的臉孔。例如：「Alice 和 Bob 在前門外。」
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 整合新增通知：

  1. 請向 Google 指出是否已在 smart home 裝置應用程式中啟用通知。如果使用者在您的應用程式中開啟或關閉通知，請傳送 SYNC 要求，通知 Google 裝置變更。
  2. 當相關裝置事件或狀態變更觸發通知時，請呼叫 Report State reportStateAndNotification API 傳送通知要求。如果裝置狀態有所變更，您可以在 Report State 和 Notification 呼叫中同時傳送狀態和通知酬載。

下列章節將詳細說明這些步驟。

指出應用程式是否已啟用通知

使用者可以在 GHA 中啟用這項功能，選擇是否要接收主動通知。在 smart home 裝置的應用程式中，您也可以選擇新增功能，讓使用者明確地在裝置上切換通知，例如在應用程式設定中切換通知。

透過 Request SYNC 呼叫更新裝置資料，向 Google 指出已為裝置啟用通知。每當使用者在應用程式中變更這項設定時，您都應傳送類似的 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 中，前往「Create service account key」頁面。

    前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。
  2. 從「Service account」(服務帳戶) 清單中選取「New service account」(新增服務帳戶)。
  3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
  4. 在「Service account ID」欄位中輸入 ID。

  5. 在「Role」清單中，依序選取「Service Accounts」 >「Service Account Token Creator」。

  6. 在「金鑰類型」中，選取「JSON」選項。

  7. 按一下「建立」，系統就會將含有金鑰的 JSON 檔案下載至您的電腦。

傳送通知

使用 devices.reportStateAndNotification API 發出通知要求呼叫。JSON 要求中必須包含 eventId，這是平台針對觸發通知的事件產生的專屬 ID。eventId 應為隨機 ID，每次傳送通知要求時都會不同。

在您在 API 呼叫中傳遞的 notifications 物件中，加入 priority 值，定義通知的顯示方式。notifications 物件可能會根據裝置特徵包含不同的欄位。

請按照下列任一途徑設定酬載並呼叫 API：

傳送主動式通知酬載

如要呼叫 API，請從下列其中一個分頁中選取選項：

HTTP

Home Graph API 提供 HTTP 端點

  1. 使用下載的服務帳戶 JSON 檔案建立 JSON Web Token (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
  3. 使用 agentUserId 建立 JSON 要求。以下是 Report State 和通知的 JSON 要求範例：
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. 將 Report State 和 Notification JSON 與 Google Home Graph 端點的 HTTP POST 要求中的權杖合併。以下範例說明如何在指令列中使用 curl 提出要求，做為測試：
    5. 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 用戶端提供 Home Graph API 的繫結。

  1. 使用 應用程式預設憑證初始化 google.homegraph 服務。
  2. 請使用 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 提供繫結。

  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 必須在五分鐘內使用，才能保持有效，並正確將回應與原始要求建立關聯。

以下程式碼片段顯示含有 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"
          }
        }]
      }]
    }
  }]
};

Google 會使用 followUpToken，只在使用者最初互動的裝置上輸出通知，不會廣播至使用者的所有裝置。

如要呼叫 API，請從下列其中一個分頁中選取選項：

HTTP

Home Graph API 提供 HTTP 端點

  1. 使用下載的服務帳戶 JSON 檔案建立 JSON Web Token (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
  3. 使用 agentUserId 建立 JSON 要求。以下是 Report State 和通知的 JSON 要求範例：
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. 將 Report State 和 Notification JSON 與 Google Home Graph 端點的 HTTP POST 要求中的權杖合併。以下範例說明如何在指令列中使用 curl 提出要求，做為測試：
    5. 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 用戶端提供 Home Graph API 的繫結。

  1. 使用 應用程式預設憑證初始化 google.homegraph 服務。
  2. 使用 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 提供繫結。

  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」一文所述，通知可支援記錄事件。這些記錄檔可用於測試及維持 Action 中的通知品質。

以下是 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)。

上一頁
導入報表狀態
下一頁
測試雲端到雲端整合