如果 Google 使用者的裝置具有與指定 agentUserId
相關聯的裝置 (您在原始的 SYNC 要求中傳送),則要求同步處理會觸發 SYNC
要求。這可讓您更新使用者的裝置,而無需中斷帳戶再重新連結。所有連結至這個 ID 的使用者都會收到 SYNC
要求。
您必須觸發 SYNC
要求:
- 使用者新增裝置時。
- 使用者移除現有裝置時。
- 使用者為現有裝置重新命名時。
- 如果您導入了新的裝置類型,可以新增或新增裝置功能。
立即開始
如要執行「要求同步」,請依照下列步驟進行:
啟用 Google HomeGraph API
-
Google Cloud Console, go to the HomeGraph API page.中
前往 HomeGraph API 頁面 - 選取與您的 smart home 專案 ID 相符的專案。
- 按一下 [啟用]。
建立服務帳戶金鑰
請按照下列操作說明,從 Google Cloud Console 產生服務帳戶金鑰:
注意:執行這些步驟時,請確認您使用的 GCP 專案正確無誤。這是與您的 smart home 專案 ID 相符的專案。
-
前往 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 要求。 以下是「要求同步」的 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);
錯誤回應
您可能會在呼叫「要求同步」時收到下列其中一個錯誤回應。這些回應都是以 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,否則呼叫者只能發出一個同步同步要求。