Google Home デベロッパー センターにようこそ。スマートホーム アクションの開発方法を学ぶことができます。注: アクションの作成は、引き続き Actions Console で行います。

Request Sync

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。
全アセットの再ビルドが必要

Request Sync は、指定された agentUserId が関連付けられている(元の SYNC リクエストで送信した)デバイスがある Google ユーザーのために、フルフィルメントへの SYNC リクエストをトリガーします。これにより、アカウントのリンク解除と再リンクを行わずにユーザーのデバイスを更新できます。この ID にリンクされているすべてのユーザーに 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

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
    
  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"
    

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 メソッドを呼び出します。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 クライアント ライブラリは、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);
    

Error responses(エラー応答)

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 に設定されていない限り、呼び出し元は 1 つの同期リクエストのみを発行できます。