Request Sync は、指定された agentUserId
が関連付けられている(元の SYNC リクエストで送信した)デバイスがある Google ユーザーのために、フルフィルメントへの SYNC
リクエストをトリガーします。これにより、アカウントのリンク解除と再リンクを行わずにユーザーのデバイスを更新できます。この ID にリンクされているすべてのユーザーに SYNC
リクエストが送信されます。
SYNC
リクエストは次の場合にトリガーします。
- ユーザーが新しいデバイスを追加した場合
- ユーザーが既存のデバイスを削除した場合
- ユーザーが既存のデバイスの名前を変更した場合
- 新しいデバイスタイプ、トレイトを実装したか、新しいデバイス機能を追加した場合
使ってみる
Request Sync を実装する方法は次のとおりです。
Google HomeGraph API を有効にする
-
Google Cloud Platform Console で、[HomeGraph API] ページに移動します。
[HomeGraph API] ページに移動 - 自分のスマートホーム プロジェクトと ID が一致するプロジェクトを選択します。
- [有効にする] をクリックします。
サービス アカウント キーを作成する
GCP Console からサービス アカウント キーを生成する手順は次のとおりです。
-
GCP Console で [サービス アカウント キーの作成] ページに移動します。
[サービス アカウント キーの作成] ページに移動 - [サービス アカウント] リストから [新しいサービス アカウント] を選択します。
- [サービス アカウント名] フィールドに名前を入力します。
- [サービス アカウント ID] フィールドに ID を入力します。
[ロール] リストから、[サービス アカウント] > [サービス アカウント トークン作成者] を選択します。
[キーのタイプ] として [JSON] を選択します。
- [作成] をクリックするとキーが含まれている JSON ファイルがパソコンにダウンロードされます。
API を呼び出す
HTTP
HomeGraph API は HTTP エンドポイントを提供します。
- ダウンロードしたサービス アカウントの JSON ファイルを使用して、JSON ウェブトークン(JWT)を作成します。詳細については、サービス アカウントを使用した認証をご覧ください。
- oauth2l を使用し、
https://www.googleapis.com/auth/homegraph
スコープを指定して OAuth 2.0 アクセス トークンを取得します。 agentUserId
を使用して JSON リクエストを作成します。 次に、Request Sync に対する JSON リクエストの例を示します。- Request Sync JSON と HTTP POST リクエスト内のトークンを Google ホームグラフ エンドポイントに結合します。次の例では、テストとして
curl
を使用してコマンドラインでリクエストを行う方法を示します。
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "user-123" }
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);
Error responses(エラー応答)
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 つの同期リクエストのみを発行できます。