智慧住宅動作通知

通知可讓 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 日中午 12 點偵測到動作。」

下列特徵支援後續回覆：

特徵 活動
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 裝置的應用程式中，視需要加入讓使用者從裝置明確切換通知的功能，例如透過應用程式設定。

發出 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. 按一下「ENABLE」(啟用)。

建立服務帳戶金鑰

請按照下列操作說明，從 Google Cloud Console 產生服務帳戶金鑰：

注意：執行下列步驟時，請確認您使用的 GCP 專案正確無誤。這是與您的 smart home 專案 ID 相符的專案。

  1. 前往 Google Cloud Console 的「Create service account key」(建立服務帳戶金鑰) 頁面。

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

  5. 在「角色」清單中，選取「服務帳戶」 >「服務帳戶權杖建立者」。

  6. 在「Key type」(金鑰類型) 部分，選取「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 和通知 JSON 中的權杖與 HTTP POST 要求中的權杖結合至 Google Home Graph 端點。以下範例說明如何執行 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 和通知 JSON 中的權杖與 HTTP POST 要求中的權杖結合至 Google Home Graph 端點。以下範例說明如何執行 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);

Logging

通知支援事件記錄，詳情請參閱「透過 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)。

上一頁
導入報表狀態
下一頁
測試及分享動作