歡迎使用 Google Home 開發人員中心,探索全新功能,瞭解如何開發智慧住宅動作。注意:請繼續在「動作」控制台中建立動作。

報告狀態

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Report State 是一項重要功能,可讓 Home 動作主動將使用者的裝置的最新狀態回報給 Google Home Graph,而不是等待 QUERY 意圖。

Report State 會向 Google 回報使用者與其相關聯的指定裝置 (在原始 SYNC 要求中傳送) 的狀態。當 Google Assistant 想要採取需要瞭解裝置目前狀態的動作時,可以直接查詢 Home Graph 中的狀態資訊,而不必在發出 EXECUTE 意圖之前向各個第三方雲端發出 QUERY 意圖。

如果沒有 Report State, 由在客廳內的多個提供者提供光源,「Ok Google,調亮我的客廳」指令會需要解析多個傳送至不同雲端的 QUERY 意圖,而不是根據先前回報的資料查詢目前亮度值。為了提供最佳使用者體驗,Assistant 必須取得裝置目前的狀態,而不需要往返裝置。

在裝置的初始 SYNC 之後,平台會傳送 QUERY 意圖,以收集裝置的狀態來填入 Home Graph。之後,Home Graph 只會儲存透過 Report State 傳送的狀態。

呼叫 Report State 時,請務必提供特定特徵的完整狀態資料。Home Graph 會根據個別特性更新狀態,並在發出 Report State 呼叫時覆寫該特性的所有資料。例如,如果您要回報 StartStop 特性的狀態,酬載就必須同時包含 isRunningisPaused 的值。

開始使用

如要實作 Report State,請按照下列步驟操作:

啟用 Google HomeGraph API

  1. 前往 Google Cloud Platform Console 中的「HomeGraph API」頁面。

    前往 HomeGraph API 頁面
  2. 選取與您的 smart home 專案 ID 相符的專案。
  3. 按一下 [啟用]

建立服務帳戶金鑰

請按照下列操作說明,從 GCP Console 產生服務帳戶金鑰:

注意:執行這些步驟時,請確認您使用的 GCP 專案正確無誤。這是與您的 smart home 專案 ID 相符的專案。
  1. 前往 GCP Console 中的「Create service account key」(建立服務帳戶金鑰) 頁面。

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

  6. 在「Key type」(金鑰類型) 部分,選取 [JSON] 選項。

  7. 按一下「建立」,包含金鑰的 JSON 檔案會下載到您的電腦。

呼叫 API

從以下分頁選取一個選項:

HTTP

Home Graph 提供 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
    
  4. 使用 agentUserId 建立 JSON 要求。 以下是報告狀態和通知的 JSON 要求範例:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. 將 HTTP POST 要求中的報告狀態與通知 JSON 和憑證與 Google Home Graph 端點合併在一起。以下示範如何使用指令列在 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 提供 gRPC 端點

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

Node.js

Google API Node.js 用戶端提供 Home 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',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});
    

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 state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request);
}
    

測試報告狀態

這項工作的建議工具

準備好測試您的認證時,請務必測試 Report State

如要這麼做,建議您使用 Home Graph 檢視器工具,這項工具是獨立的網路應用程式,不需要下載或部署。

Report State 資訊主頁仍可使用,但已淘汰且不再受支援。

報告狀態資訊主頁

必要條件

測試用服務帳戶金鑰和agentUserId時,您才能測試動作。如果您已有服務帳戶金鑰,且 agentUserId 請參閱部署 Report State 資訊主頁的說明。

部署報告狀態資訊主頁

為專案取得服務帳戶金鑰和代理程式使用者 ID 後,請從 Report State 資訊主頁下載及部署最新版本。下載最新版本後,請按照隨附的 README.MD 檔案中的指示操作。

部署 Report State 資訊主頁後,請透過以下網址存取資訊主頁 (將 your_project_id 替換為您的專案 ID):

http://<your-project-id>.appspot.com

在資訊主頁上執行下列操作:

  • 選擇您的帳戶金鑰檔案
  • 新增代理程式使用者 ID

然後按一下 [清單]。

系統隨即會列出所有裝置。清單填入完成後,您可以使用 [Refresh] 按鈕重新整理裝置狀態。如果有裝置狀態變更,該列就會以綠色醒目顯示。

錯誤回應

您可能會在呼叫 Report State 時收到下列其中一個錯誤回應。這些回應會以 HTTP 狀態碼的形式提供。

  • 400 Bad Request:由於語法無效,伺服器無法處理用戶端傳送的要求。常見原因包括 JSON 格式錯誤,或使用 null 而非字串值。
  • 404 Not Found:找不到要求的資源,但日後或許可以使用。這通常表示我們無法找到你要求的裝置這也可能表示使用者帳戶未與 Google 建立連結,或者收到無效的 agentUserId。確認 agentUserIdSYNC 回應中提供的值相符,且您已正確處理 DISCONNECT 意圖。