歡迎來到 Google Home 開發人員中心,你可以在這裡學習如何學習智慧型住宅動作。注意事項:您將在 Actions 主控台建構動作。

要求同步

按一下

如果有 Google 使用者裝置具有指定的 agentUserId (並透過原始同步處理要求傳送),系統會透過 SYNC 要求觸發執行要求,直到出貨。如此一來,使用者無需更新及重新連結帳戶,就能更新使用者的裝置。已連結至這個 ID 的所有使用者將收到 SYNC 要求。

您必須觸發 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 中,前往「建立服務帳戶金鑰」頁面。

    前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。
  2. 從「服務帳戶」清單中,選取「新增服務帳戶」
  3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
  4. 在「Service account ID」(服務帳戶 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. 結合「要求同步處理 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 方法。其會傳回 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。確認 agentUserIdSYNC 回應中提供的值相符,您已正確處理 DISCONNECT 意圖。
  • 429 Too Many Requests - 指定的 agentUserId 的並行同步要求數量已超過上限。除非 async 標記設為 true,否則呼叫者只能發出一個並行同步要求。