歡迎使用 Google Home 開發人員中心,探索全新功能,瞭解如何開發智慧住宅動作。注意:請繼續在「動作」控制台中建立動作。

要求同步

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

如果 Google 使用者的裝置具有與指定 agentUserId 相關聯的裝置 (您在原始的 SYNC 要求中傳送),則要求同步處理會觸發 SYNC 要求。這可讓您更新使用者的裝置,而無需中斷帳戶再重新連結。所有連結至這個 ID 的使用者都會收到 SYNC 要求。

您必須觸發 SYNC 要求:

  • 使用者新增裝置時。
  • 使用者移除現有裝置時。
  • 使用者為現有裝置重新命名時。
  • 如果您導入了新的裝置類型,可以新增或新增裝置功能。

立即開始

如要執行「要求同步」,請依照下列步驟進行:

啟用 Google HomeGraph API

  1. Google Cloud Console, go to the HomeGraph API page.

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

建立服務帳戶金鑰

請按照下列操作說明,從 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. 使用 oauth2l 取得具有 https://www.googleapis.com/auth/homegraph 範圍的 OAuth 2.0 存取憑證:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. 使用 agentUserId 建立 JSON 要求。 以下是「要求同步」的 JSON 要求範例:
  5. {
      "agentUserId": "user-123"
    }
    
  6. 將您的 Request Sync JSON 和 HTTP POST 要求中的憑證合併至 Google Home Graph 端點。以下示範如何使用指令列在 curl 中發出要求,以進行測試:
  7. 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 方法。其會傳回含有空白 RequestSyncDevicesResponsePromise
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);
    

錯誤回應

您可能會在呼叫「要求同步」時收到下列其中一個錯誤回應。這些回應都是以 HTTP 狀態碼的形式呈現。

  • 400 Bad Request:由於語法無效,伺服器無法處理用戶端傳送的要求。常見原因包括 JSON 格式錯誤,或使用 null 而非字串值。
  • 403 Forbidden - 重新整理憑證時發生錯誤,伺服器無法處理指定的 agentUserId 要求。確認您的 OAuth 端點正確回應,以重新整理憑證要求並檢查使用者的帳戶連結狀態。
  • 404 Not Found:找不到要求的資源,但日後或許可以使用。這通常表示使用者帳戶未與 Google 建立連結,或者收到無效的 agentUserId。確認 agentUserIdSYNC 回應中提供的值相符,且您已正確處理 DISCONNECT 意圖。
  • 429 Too Many Requests:指定 agentUserId 的並行同步要求數量已達上限。除非 async 標記設為 true,否則呼叫者只能發出一個同步同步要求。