要求同步處理

如果 Google 使用者的裝置與指定的 agentUserId 相關聯 (您在原始 SYNC 要求中傳送)，Request Sync 會觸發 SYNC 要求，傳送至您的執行要求。這樣一來，您就能更新使用者的裝置，不必取消連結再重新連結帳戶。與這個 ID 連結的所有使用者都會收到 SYNC 要求。

您必須觸發 SYNC 要求：

  • 使用者新增裝置。
  • 使用者移除現有裝置。
  • 使用者重新命名現有裝置。
  • 導入新的裝置類型、特徵，或新增裝置功能。

開始使用

如要實作 Request Sync，請按照下列步驟操作：

啟用 Google HomeGraph API

  1. 在 Google Cloud Console 中，前往 HomeGraph API 頁面。

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

建立服務帳戶金鑰

請按照下列操作說明，從 Google Cloud Console 產生服務帳戶金鑰：

注意：執行這些步驟時，請務必使用正確的 GCP 專案。這個專案與您的 smart home 專案 ID 相符。

  1. 前往 Google Cloud Console 的「Service accounts」(服務帳戶) 頁面。

    前往「Service Accounts」(服務帳戶) 頁面。

    您可能需要先選取專案，才能前往「服務帳戶」頁面。

  2. 按一下「 Create service account」(建立服務帳戶)。

  3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。

  4. 在「Service account ID」(服務帳戶 ID) 欄位中輸入 ID。

  5. 在「Service account description」(服務帳戶說明) 欄位中輸入說明。

  6. 按一下 [建立並繼續]。

  7. 在「Role」(角色) 下拉式選單中，依序選取「Service Accounts」(服務帳戶) >「Service Account OpenID Connect Identity Token Creator」(服務帳戶 OpenID Connect 身分識別權杖建立者)。

  8. 按一下「繼續」。

  9. 按一下「完成」。

  10. 從服務帳戶清單中選取您剛建立的服務帳戶，然後從 「Actions」(動作) 選單中選取「Manage keys」(管理金鑰)。

  11. 依序選取「新增金鑰」 >「建立新的金鑰」。

  12. 在「金鑰類型」部分，選取「JSON」選項。

  13. 按一下「建立」，系統會將含有金鑰的 JSON 檔案下載到您的電腦。

如需建立服務帳戶金鑰的詳細操作說明和資訊，請參閱 Google Cloud 控制台說明網站上的「建立及刪除服務帳戶金鑰」。

呼叫 API

HTTP

Home Graph API 提供 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
  3. 使用 agentUserId 建立 JSON 要求。以下是 Request Sync 的 JSON 要求範例：
    4. {
  "agentUserId": "user-123"
}
  4. 在傳送至 Google Home Graph 端點的 HTTP POST 要求中，合併要求同步 JSON 和權杖。以下範例說明如何使用 curl 在指令列中提出要求，做為測試：
    5. 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 端點

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

Node.js

Google API Node.js 用戶端提供 Home Graph API 的繫結。

  1. 使用應用程式預設憑證初始化 google.homegraph 服務。
  2. 使用 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 的繫結。

  1. 使用應用程式預設憑證初始化 HomeGraphApiService。
  2. 使用 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，否則呼叫端只能發出一個並行同步要求。
上一頁
中斷連線
下一頁
導入報表狀態