Request Sync

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. 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 に設定されていない限り、呼び出し元が同時に発行できる同期リクエストは 1 つのみです。
前へ
Disconnect
次へ
Implement Report State