如果有 Google 使用者裝置具有指定的 agentUserId
(並透過原始同步處理要求傳送),系統會透過 SYNC
要求觸發執行要求,直到出貨。如此一來,使用者無需更新及重新連結帳戶,就能更新使用者的裝置。已連結至這個 ID 的所有使用者將收到 SYNC
要求。
您必須觸發 SYNC
要求:
- 使用者新增裝置。
- 使用者移除現有裝置時。
- 使用者重新命名現有裝置時。
- 如果您實作新的裝置類型、特性或新增裝置功能,
開始使用
如要實作「要求同步處理」,請執行下列步驟:
啟用 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] 選項。
- 按一下「Create」(建立)。含有金鑰的 JSON 檔案會下載到電腦上。
呼叫 API
HTTP
Home Graph API 提供 HTTP 端點
- 使用下載的服務帳戶 JSON 檔案,建立 JSON Web Token (JWT)。詳情請參閱「 使用服務帳戶進行驗證」。
- 使用 OAuth2l 取得含有
https://www.googleapis.com/auth/homegraph
範圍的 OAuth 2.0 存取權杖: - 使用
agentUserId
建立 JSON 要求。以下是要求同步處理的 JSON 要求範例: - 結合「要求同步處理 JSON」與 HTTP POST 要求中的權杖與 Google Home Graph 端點。以下範例說明如何在測試中使用
curl
透過指令列提出要求:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "user-123" }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:requestSync"
gRPC
Home Graph API 提供 gRPC 端點
- 取得 Home Graph API 的通訊協定緩衝區服務定義。
- 按照 gRPC 開發人員說明文件產生其中一種支援的語言的用戶端虛設常式。
- 呼叫 RequestSync 方法。
Node.js
Google API Node.js 用戶端提供 Home Graph API 的繫結。
- 使用應用程式預設憑證,初始化
google.homegraph
服務。 - 使用 RequestSyncDevicesRequest 呼叫
requestSync
方法。其會傳回Promise
為空白的 RequestSyncDevicesResponse。
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.requestSync({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', async: false } });
Java
Java 適用的 HomeGraph API 用戶端程式庫提供 Home Graph API 的繫結項目。
- 使用應用程式預設憑證,初始化
HomeGraphApiService
。 - 使用
RequestSyncDevicesRequest
呼叫requestSync
方法。其會傳回空白的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(); // Request sync. RequestSyncDevicesRequest request = new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false); homegraphService.devices().requestSync(request);
錯誤回應
呼叫 Request Sync 時,可能會收到下列其中一個錯誤回應。這些回應會以 HTTP 狀態碼的形式。
400 Bad Request
:伺服器因語法無效而無法處理用戶端傳送的要求。常見原因包括格式錯誤的 JSON 或使用null
而不是字串值。403 Forbidden
:伺服器在重新整理權杖時發生錯誤,因此無法處理指定的agentUserId
要求。請確認您的 OAuth 端點正確回應,才能更新權杖要求並檢查使用者的帳戶連結狀態。404 Not Found
:找不到要求的資源,但日後可能提供。這通常表示使用者帳戶並未與 Google 連結,或是我們收到無效的agentUserId
。確認agentUserId
與 SYNC 回應中提供的值相符,您已正確處理 DISCONNECT 意圖。429 Too Many Requests
- 指定的agentUserId
的並行同步要求數量已超過上限。除非async
標記設為 true,否則呼叫者只能發出一個並行同步要求。