Request Sync

Cloud-to-cloud

Request Sync は、指定された agentUserId が関連付けられているデバイス（最初の SYNC リクエストで送信されたもの）を持つすべての Google ユーザーの SYNC リクエストをフルフィルメントに送信します。これにより、ユーザーのアカウントのリンクをいったん解除して再びリンクしなくても、ユーザーのデバイスを更新できます。この識別子にリンクされているすべてのユーザーが 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[**サービス アカウント**] ページに移動します。

    [サービス アカウント] ページに移動します。

    [サービス アカウント] ページに進むには、プロジェクトの選択が必要になることがあります。

  2. [**サービス アカウントを作成**] をクリックします。

  3. [サービス アカウント名] フィールドに名前を入力します。

  4. [サービス アカウント ID] フィールドに ID を入力します。

  5. [サービス アカウントの説明] フィールドに説明を入力します。

  6. [作成して続行] をクリックします。

  7. [**ロール**] プルダウンから、[**サービス アカウント**] > [サービス アカウントの OpenID Connect ID トークン作成者] を選択します。

  8. [続行] をクリックします。

  9. [完了] をクリックします。

  10. サービス アカウントのリストから、作成した上記のサービス アカウントを選択し、 [鍵を管理] を [操作] メニューから選択します。

  11. [鍵を追加] > [新しい鍵を作成] を選択します。

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

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

サービス アカウント キーの詳しい作成手順と情報については、 Google Cloud コンソールのヘルプサイトの サービス アカウント キーの作成と削除をご覧ください。

API を呼び出す

HTTP

HomeGraph API は HTTP エンドポイントを提供します。

  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
  3. agentUserId を使用して JSON リクエストを作成します。 次に、Request Sync に対する JSON リクエストの例を示します。
    4. {
  "agentUserId": "user-123"
}
  4. Request Sync JSON と HTTP POST リクエスト内のトークンを Google ホームグラフ エンドポイントに結合します。次の例では、テストとして 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

HomeGraph API は gRPC エンドポイントを提供します。

  1. HomeGraph API 用のプロトコル バッファ サービス定義を取得します。
  2. gRPC デベロッパー向けドキュメントに沿って、サポートされている言語のうちいずれかのクライアント スタブを生成します。
  3. RequestSync メソッドを呼び出します。

Node.js

Google API Node.js クライアントは、HomeGraph 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 クライアント ライブラリは、HomeGraph API 用のバインディングを提供します。

  1. HomeGraphApiService を アプリケーションのデフォルト認証情報を使用して初期化します。
  2. requestSync メソッドを RequestSyncDevicesRequest を使用して呼び出します。空の 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 に設定されていない限り、呼び出し元は同時同期リクエストを 1 つしか発行できません。
前へ
接続解除
次へ
Report State の実装