本頁面由 Cloud Translation API 翻譯而成。

智慧住宅動作通知

通知可讓 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` 裝置指令後，完成狀態和狀態變更。例如：「保全系統已經啟動」。
鎖定	執行 `action.devices.commands.LockUnlock` 裝置指令後，完成狀態和狀態變更。例如：「前門已上鎖」或「前門卡住了」。
NetworkControl	執行 `action.devices.commands.TestNetworkSpeed` 裝置指令後，完成狀態和狀態變更。例如：「你的網路速度測試已完成。辦公室路由器的下載速度目前為 80.2 Kbps，上傳速度為 9.3 Kbps。
OpenClose	執行 `action.devices.commands.OpenClose` 裝置指令後，完成狀態和狀態變更。例如：「前門打開了」或「前門打開了」。
啟動	執行 `action.devices.commands.StartStop` 裝置指令後，完成狀態和狀態變更。例如：「吸塵器已啟動。」

所有裝置類型都會針對適用特徵提供支援通知。

為智慧型住宅動作建立通知

請在以下階段為 smart home 動作新增通知：

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

以下各節將詳細說明這些步驟。

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

使用者只要在 GHA 中啟用此功能，即可選擇是否要接收主動通知。在 smart home 裝置的應用程式中，您也可以選擇加入使用者明確從裝置切換通知的功能，例如從應用程式設定等等。

發出「要求同步處理」呼叫裝置資料，即可通知 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

在 Google Cloud Console 中，前往「HomeGraph API」頁面。
前往 HomeGraph API 頁面
選取與「smart home」專案 ID 相符的專案。
按一下「啟用」。

建立服務帳戶金鑰

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

注意：執行這些步驟時，請務必使用正確的 GCP 專案。這是指與 smart home 專案 ID 相符的專案。

在 Google Cloud Console 中，前往「建立服務帳戶金鑰」頁面。
前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。
從「服務帳戶」清單中，選取「新增服務帳戶」。
在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
在「Service account ID」(服務帳戶 ID) 欄位中輸入 ID。
在「角色」清單中，依序選取「服務帳戶」 >「服務帳戶權杖建立者」。
針對「Key type」(金鑰類型)，選取 [JSON] 選項。
按一下「建立」，含有金鑰的 JSON 檔案會下載到電腦上。

傳送通知

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

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

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

傳送主動式通知酬載
傳送後續回應酬載

傳送主動式通知酬載

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

HTTP

Home Graph API 提供 HTTP 端點

使用下載的服務帳戶 JSON 檔案，建立 JSON Web Token (JWT)。詳情請參閱「使用服務帳戶進行驗證」。
使用 OAuth2l 取得含有 https://www.googleapis.com/auth/homegraph 範圍的 OAuth 2.0 存取權杖：

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

使用 agentUserId 建立 JSON 要求。以下是 Report State 和通知的 JSON 要求範例：

{
  "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
            }
          }
        }
      }
    }
  }
}

將 Report State 和 Notification JSON 與 HTTP POST 要求中的權杖結合至 Google Home Graph 端點。以下範例說明如何在測試中使用 curl 透過指令列提出要求：

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 端點

取得 Home Graph API 的通訊協定緩衝區服務定義。
按照 gRPC 開發人員說明文件產生其中一種支援的語言的用戶端虛設常式。
呼叫 ReportStateAndNotification 方法。

Node.js

Google API Node.js 用戶端提供 Home Graph API 的繫結，

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

使用應用程式預設憑證，初始化 HomeGraphApiService。
使用 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"
          }
        }]
      }]
    }
  }]
};

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

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

HTTP

Home Graph API 提供 HTTP 端點

使用下載的服務帳戶 JSON 檔案，建立 JSON Web Token (JWT)。詳情請參閱「使用服務帳戶進行驗證」。
使用 OAuth2l 取得含有 https://www.googleapis.com/auth/homegraph 範圍的 OAuth 2.0 存取權杖：

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

使用 agentUserId 建立 JSON 要求。以下是 Report State 和通知的 JSON 要求範例：

{
  "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
            }
          }
        }
      }
    }
  }
}

將 Report State 和 Notification JSON 與 HTTP POST 要求中的權杖結合至 Google Home Graph 端點。以下範例說明如何在測試中使用 curl 透過指令列提出要求：

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 端點

取得 Home Graph API 的通訊協定緩衝區服務定義。
按照 gRPC 開發人員說明文件產生其中一種支援的語言的用戶端虛設常式。
呼叫 ReportStateAndNotification 方法。

Node.js

Google API Node.js 用戶端提供 Home Graph API 的繫結，

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

使用應用程式預設憑證，將 HomeGraphApiService 初始化
使用 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)。

導入報表狀態

測試及分享動作