Request Sync

Request Sync は、指定された agentUserId が関連付けられているデバイス(最初の SYNC リクエストで送信されたもの)を持つすべての Google ユーザーの SYNC リクエストをフルフィルメントに送信します。これにより、ユーザーのアカウントのリンクをいったん解除して再びリンクしなくても、ユーザーのデバイスを更新できます。この識別子にリンクされているすべてのユーザーが SYNC リクエストを受け取ります。

SYNC リクエストは次の場合にトリガーします。

  • ユーザーが新しいデバイスを追加した場合
  • ユーザーが既存のデバイスを削除した場合
  • ユーザーが既存のデバイスの名前を変更した場合
  • 新しいデバイスタイプ、トレイトを実装したか、新しいデバイス機能を追加した場合

使ってみる

Request Sync を実装する方法は次のとおりです。

Google HomeGraph API を有効にする

  1. Google Cloud Platform Console で、[HomeGraph API] ページに移動します。

    [HomeGraph API] ページに移動
  2. 自分のスマートホーム プロジェクトと ID が一致するプロジェクトを選択します。
  3. [有効にする] をクリックします。

サービス アカウント キーを作成する

GCP Console からサービス アカウント キーを生成する手順は次のとおりです。

: 以下の手順を行う場合は、正しい GCP プロジェクト(スマートホーム プロジェクト ID と一致するプロジェクト)を使用していることをご確認ください。
  1. GCP Console で [サービス アカウント キーの作成] ページに移動します。

    [サービス アカウント キーの作成] ページに移動
  2. [サービス アカウント] リストから [新しいサービス アカウント] を選択します。
  3. [サービス アカウント名] フィールドに名前を入力します。
  4. [サービス アカウント ID] フィールドに ID を入力します。
  5. [ロール] リストから、[サービス アカウント] > [サービス アカウント トークン作成者] を選択します。

  6. [キーのタイプ] として [JSON] を選択します。

  7. [作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。

API を呼び出す

HTTP POST

  1. ダウンロードしたサービス アカウントの JSON ファイルを使用して、JSON ウェブトークン(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 リクエストを作成します。 次に、Request Sync に対する JSON リクエストの例を示します。
  5. {
      "agentUserId": "user-123"
    }
    
  6. Request Sync JSON と HTTP POST リクエスト内のトークンを Google ホームグラフ エンドポイントに結合します。次に、テストのために 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"
    

Node.js

Node.js 用の Actions on Google ライブラリは、HTTP 経由で Request Sync をサポートしています。

  1. ダウンロードしたサービス アカウント JSON をプロジェクト ディレクトリに配置します。
  2. ファイルの場所を smarthome コンストラクタに渡します。
  3. ペイロードを引数にして requestSync メソッドを呼び出すと、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 用の Actions on Google ライブラリは、gRPC 経由で Request Sync をサポートしています。

  1. ダウンロードしたサービス アカウント JSON をプロジェクト ディレクトリに配置します。
  2. ファイルの場所を読み取り、GoogleCredentials オブジェクトを生成します。
  3. ペイロードを使用して requestSync メソッドを呼び出すと、サーバー レスポンスが返されます。
// 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 - 失敗: 不正な構文のため、サーバーがクライアントから送信されたリクエストを処理できませんでした。一般的な原因としては、不正な形式の JSON や、文字列値に "" でなく null を使っていることなどが挙げられます。
  • 403 - 失敗: トークンの更新中にエラーが発生したため、サーバーは指定された agentUserId のリクエストを処理できませんでした。OAuth エンドポイントが更新トークン リクエストに正しく応答することを確認し、ユーザーのアカウントのリンク ステータスをチェックしてください。
  • 404 - 失敗: リクエストされたリソースは見つかりませんでしたが、将来使用可能になる可能性があります。このエラーは通常、ユーザー アカウントが Google とリンクしていないか、無効な agentUserId を受け取ったことを意味します。agentUserIdSYNC レスポンスで提供された値と一致していること、DISCONNECT インテントが適切に処理されていることを確認してください。
  • 429 - 失敗: 指定された agentUserId に対する同時同期リクエストが最大数を超えました。async フラグが true に設定されていない限り、呼び出し元が同時に発行できる同期リクエストは 1 つのみです。