對於擁有與其相關聯 agentUserId
(在原始 SYNC 要求中傳送) 的 Google 使用者,「Request Sync」(要求同步處理) 會觸發對執行要求的任何 Google 使用者發出 SYNC
要求。這樣您就能更新使用者的裝置,而不必取消連結及重新連結帳戶。所有連結至這個 ID 的使用者都會收到 SYNC
要求。
您必須觸發 SYNC
要求:
- 使用者新增裝置。
- 使用者移除現有裝置:
- 如果使用者重新命名現有裝置。
- 如果您實作新的裝置類型、特徵或新增裝置功能。
開始使用
如要實作「要求同步處理」,請按照下列步驟操作:
啟用 Google HomeGraph API
-
前往 Google Cloud Console 中的「HomeGraph API」頁面。
前往 HomeGraph API 頁面 - 選取 smart home 專案 ID 相符的專案。
- 按一下「ENABLE」(啟用)。
建立服務帳戶金鑰
請按照下列操作說明,從 Google Cloud Console 產生服務帳戶金鑰:
-
前往 Google Cloud Console 的「Create service account key」(建立服務帳戶金鑰) 頁面。
前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。 - 從「服務帳戶」清單中,選取「新增服務帳戶」。
- 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
- 在「服務帳戶 ID」欄位中輸入 ID。
在「角色」清單中,選取「服務帳戶」 >「服務帳戶權杖建立者」。
在「Key type」(金鑰類型) 部分,選取「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 要求。以下是 Request Sync 的 JSON 要求範例: - 將 Request Sync 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
方法。它會傳回包含空白 RequestSyncDevicesResponse 的Promise
。
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,否則呼叫端只能發出一項並行同步要求。