Google Home Developer Center への移行が完了しました。

このページは Cloud Translation API によって翻訳されました。

Request Sync

Cloud-to-cloud

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

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

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

使ってみる

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

Google HomeGraph API を有効にする
サービスアカウントキーを作成する
API を呼び出す

Google HomeGraph API を有効にする

Google Cloud Console で [HomeGraph API] ページに移動します。
[HomeGraph API] ページに移動
smart home プロジェクト ID と一致するプロジェクトを選択します。
[有効にする] をクリックします。

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

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

注: 以下の手順を行う場合は、正しい GCP プロジェクト（smart home プロジェクト ID と一致するプロジェクト）を使用していることをご確認ください。

Google Cloud Console で、[サービスアカウント] ページに移動します。
[サービスアカウント] ページに移動します。
[サービスアカウント] ページに進むには、プロジェクトの選択が必要になることがあります。
[サービスアカウントを作成] をクリックします。
[サービスアカウント名] フィールドに名前を入力します。
[サービスアカウント ID] フィールドに ID を入力します。
[サービスアカウントの説明] フィールドに説明を入力します。
[作成して続行] をクリックします。
[ロール] プルダウンから、[サービスアカウント] > [サービスアカウントの OpenID Connect ID トークン作成者] を選択します。
[続行] をクリックします。
[完了] をクリックします。
サービスアカウントのリストから、作成した上記のサービスアカウントを選択し、の [操作] メニューから [鍵を管理] を選択します。
[鍵を追加] > [新しい鍵を作成] を選択します。
[キーのタイプ] として [JSON] を選択します。
[作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。

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

API を呼び出す

HTTP

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

ダウンロードしたサービスアカウントの JSON ファイルを使用して、JSON ウェブトークン（JWT）を作成します。詳細については、サービスアカウントを使用した認証をご覧ください。
oauth2l を使用し、https://www.googleapis.com/auth/homegraph スコープを指定して OAuth 2.0 アクセストークンを取得します。

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

agentUserId を使用して JSON リクエストを作成します。次に、Request Sync に対する JSON リクエストの例を示します。

{
  "agentUserId": "user-123"
}

Request Sync JSON と HTTP POST リクエスト内のトークンを Google ホームグラフエンドポイントに結合します。次の例では、テストとして curl を使用してコマンドラインでリクエストを行う方法を示します。

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 エンドポイントを提供します。

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

Node.js

Google API Node.js クライアントは、HomeGraph API のバインディングを提供します。

アプリケーションのデフォルト認証情報を使用して、google.homegraph サービスを初期化します。
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 用のバインディングを提供します。

アプリケーションのデフォルト認証情報を使用して HomeGraphApiService を初期化します。
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 つのみです。

接続解除

Report State の実装