Request Sync 會針對任何 Google 使用者，向你的服務傳送 SYNC 要求，前提是這些使用者必須有與其相關聯的指定agentUserId裝置 (你已在原始 SYNC 要求中傳送)。這樣一來，您就能更新使用者的裝置，不必取消連結及重新連結帳戶。所有連結至這個 ID 的使用者都會收到 SYNC 要求。
您必須觸發 SYNC 要求：
- 使用者新增裝置。
- 使用者移除現有裝置。
- 如果使用者重新命名現有裝置。
- 實作新的裝置類型、特徵或新增裝置功能。
開始使用
如要實作要求同步，請按照下列步驟操作：
啟用 Google HomeGraph API
-
在 Google Cloud Console 中，前往 HomeGraph API 頁面。
前往 HomeGraph API 頁面 - 選取與 smart home 專案 ID 相符的專案。
- 按一下「啟用」。
建立服務帳戶金鑰
請按照下列操作說明，從 Google Cloud Console 產生服務帳戶金鑰：
-
前往 Google Cloud Console 的「Service accounts」(服務帳戶) 頁面。
前往「Service Accounts」(服務帳戶) 頁面。系統可能會要求您選取專案，才會前往「服務帳戶」頁面。
按一下「建立服務帳戶」。
在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
在「Service account ID」(服務帳戶 ID) 欄位中輸入 ID。
在「服務帳戶說明」欄位中輸入說明。
按一下 [建立並繼續]。
在「Role」(角色) 下拉式選單中，選取「Service Accounts」(服務帳戶) >「Service Account OpenID Connect Identity Token Creator」(服務帳戶 OpenID Connect 身分識別權杖建立者)。
按一下「繼續」。
按一下 [完成]。
從服務帳戶清單中選取您剛建立的服務帳戶，然後從「動作」選單中選取「管理金鑰」。
依序選取「新增金鑰」 >「建立新的金鑰」。
在「金鑰類型」中，選取「JSON」選項。
按一下「建立」，系統就會將含有金鑰的 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 要求範例： - 在 HTTP POST 要求中，將要求同步 JSON 和權杖一併傳送至 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);
錯誤回應
呼叫「要求同步」時，您可能會收到下列其中一項錯誤回應。 這些回應會以 HTTP 狀態碼的形式傳回。
400 Bad Request：伺服器無法處理用戶端傳送的要求，因為語法無效。常見原因包括 JSON 格式錯誤，或是字串值使用null而非「""」。403 Forbidden：伺服器無法處理指定agentUserId的要求，因為在重新整理權杖時發生錯誤。請確認 OAuth 端點對重新整理權杖要求的回應正確無誤，並檢查使用者的帳戶連結狀態。404 Not Found- 找不到要求的資源，但日後可能提供。通常表示使用者帳戶未連結 Google，或是我們收到無效的agentUserId。確認agentUserId與 SYNC 回應中提供的值相符，且你正確處理 DISCONNECT 意圖。429 Too Many Requests- Maximum number of concurrent sync requests has been exceeded for the givenagentUserId. 除非async旗標設為 true，否則呼叫端一次只能發出一個同步要求。