要求同步處理

要求同步處理功能會向任何 Google 使用者觸發 SYNC 要求，傳送至執行要求 具有指定 有 agentUserId 個相關聯的憑證 (您 原始 SYNC 要求中傳送)。您可以藉此更新使用者裝置 不必取消連結帳戶再重新連結所有連結至這個帳戶的使用者 ID 會收到 SYNC 要求。

您必須觸發 SYNC 要求：

  • 使用者新增裝置。
  • 使用者移除現有裝置：
  • 如果使用者重新命名現有裝置。
  • 如果您實作新的裝置類型、特徵或新增裝置功能。

開始使用

如要實作「要求同步處理」，請按照下列步驟操作：

啟用 Google HomeGraph API

  1. 前往 Google Cloud Console 中的「HomeGraph API」頁面。

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

建立服務帳戶金鑰

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

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

  1. 前往 Google Cloud Console 的「Create service account key」(建立服務帳戶金鑰) 頁面。

    前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。
  2. 在「服務帳戶」清單中，選取 新增服務帳戶：
  3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
  4. 在「服務帳戶 ID」欄位中輸入 ID。

  5. 在「角色」清單中，選取「服務帳戶」> 服務帳戶權杖建立者：

  6. 在「Key type」(金鑰類型) 部分，選取「JSON」選項。

  7. 點選「建立」。包含金鑰的 JSON 檔案 下載至您的電腦中。

呼叫 API

HTTP

Home Graph API 會提供 HTTP 端點

  1. 使用下載的服務帳戶 JSON 檔案建立 JSON Web Token (JWT)。若需更多資訊，請參閲 使用服務帳戶進行驗證。
  2. 使用 使用 https://www.googleapis.com/auth/homegraph 個範圍 oauth2l：
    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. 結合 Request Sync JSON 和 HTTP POST 中的憑證 要求傳送至 Google Home Graph 端點。以下範例將說明 使用 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 方法。它會傳回包含空白 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 的繫結。

  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
上一頁
中斷連線
下一頁
導入報表狀態