Google Cloud プロジェクトと Device Access プロジェクトを作成したら、サポートされている Google Nest デバイスで SDM API を使用する Google アカウントを承認できます。
アカウントをリンクする
構造とデバイスを表示するには、PCM を使用して Google アカウントをDevice Access プロジェクトにリンクする必要があります。PCM を使用すると、 user は developerが構造とデバイスデータにアクセスできるように権限を付与できます。
このガイドでは、 user と developerの両方を担当します。
ウェブブラウザで次のリンクを開き、次のように置き換えます。
- project-id は、実際の Device Access Project ID に置き換えます。
- oauth2-client-id には、Google Cloud 認証情報の OAuth2 クライアント ID を指定します。
https://nestservices.google.com/partnerconnections/project-id/auth?
redirect_uri=https://www.google.com& access_type=offline& prompt=consent& client_id=oauth2-client-id& response_type=code& scope=https://www.googleapis.com/auth/sdm.service - 最近複数のアカウントで Google にログインしている場合は、Google アカウントのリストが表示された最初の [アカウントを選択] 画面が表示されることがあります。その場合は、 Device Accessの承認を希望するデバイスに関連付けられている Google アカウントを選択します。
- [Google Nest の権限] 画面は PCM そのものです。ここでは、構造とデバイスの権限を付与できます。家（ステップ 1）と、その家にある SDM API でサポートされているデバイス（ステップ 2）の権限をオンにして、[次へ] をクリックします。
- [Choose an account to continue to Project Name] 画面（Project Name は Google Cloud プロジェクトの名前）で、SDM API の認証に使用する Google アカウントを選択します。以前と同じ Google アカウントを使用します。
- アカウントを選択すると、[Google はこのアプリを確認していません] という警告画面が表示されることがあります。その場合は、[詳細] オプションをクリックし、[プロジェクト名（安全でない）に移動] をクリックして続行します。詳しくは、このアプリは Google で確認されていませんをご覧ください。
- [プロジェクト名の権限を付与] 画面で、[許可] をクリックして、プロジェクトに Google アカウントへのアクセス権限を付与します。
- [選択内容を確認] 画面で、付与する権限にチェックが入っていることを確認し、[許可] をクリックして確定します。
https://www.google.com にリダイレクトされます。認証コードは URL の
codeパラメータとして返されます。このパラメータは次の形式になります。https://www.google.com?code=authorization-code&
scope=https://www.googleapis.com/auth/sdm.service - 認証コードをコピーします。
アクセス トークンを取得する
認証コードを使用してアクセス トークンを取得し、SDM API の呼び出しに使用します。
ターミナルを開き、次の
curlコマンドを実行します。- oauth2-client-id と oauth2-client-secret には、Google Cloud 認証情報の OAuth2 クライアント ID とクライアント シークレットを指定します。
- authorization-code は、前の手順で受け取ったコードに置き換えます。
curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id& client_secret=oauth2-client-secret& code=authorization-code& grant_type=authorization_code& redirect_uri=https://www.google.com' Google OAuth は、アクセス トークンと更新トークンの 2 つのトークンを返します。
{
デバイスリストの呼び出しを行う
新しいアクセス トークンを使用して最初の devices.list 呼び出しを行うまで、承認は完了しません。この最初の呼び出しは、承認プロセスを完了し、Pub/Sub サブスクリプションをすでに設定している場合はイベントを有効にします。
curl を使用して、devices エンドポイントに対して次の呼び出しを行います。
curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer access-token'呼び出しが成功すると、 Device Accessプロジェクトにリンクされているデバイスのリストが返されます。各デバイスには、利用可能なトレイトの独自のリストがあります。
{
"devices": [
{
"name": "enterprises/project-id/devices/device-id",
"type": "sdm.devices.types.device-type",
"traits": { ... },
"parentRelations": [
{
"parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
"displayName": "device-room-name"
}
]
}
]
}更新トークンの使用方法
SDM API のアクセス トークンは、Google OAuth から返される expires_in パラメータに記載されているように、1 時間のみ有効です。アクセス トークンの有効期限が切れた場合は、更新トークンを使用して新しいアクセス トークンを取得します。
このコマンドはアクセス トークン コマンドと似ていますが、使用する grant_type が異なります。
ターミナルを開き、次の
curlコマンドを実行します。- oauth2-client-id と oauth2-client-secret には、Google Cloud 認証情報の OAuth2 クライアント ID とクライアント シークレットを指定します。
- refresh-token は、アクセス トークンを最初に取得したときに受け取ったコードに置き換えます。
curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id& client_secret=oauth2-client-secret& refresh_token=refresh-token& grant_type=refresh_token' Google OAuth から新しいアクセス トークンが返されます。
{
トラブルシューティング
Google OAuth の詳細については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。
更新トークンが期限切れになる
クライアント ID が承認されていない場合、更新トークンが 7 日後に機能しなくなる可能性があります。7 日間のトークンの有効期限は、商用環境またはサンドボックス環境の承認とは関係ありません。トークンの有効期間を長くするには、サービス アカウントまたはユーザー アカウントの OAuth 2.0 クライアント ID を承認して、本番環境に移行する必要があります。詳細については、更新トークンの有効期限をご覧ください。
アクセスが拒否されました
Google Cloud で OAuth 同意画面を設定し、ユーザータイプが [外部] になっている場合、アプリのテストユーザーとして登録されていない Google アカウントでアカウント リンクを試みると、「アクセスが拒否されました」というエラーが表示されます。OAuth 同意画面の [テストユーザー] セクションに Google アカウントを追加してください。
Partner Connections Manager（PCM）エラー
PCM へのアクセス時に発生したエラーについては、パートナー接続マネージャー（PCM）エラー リファレンスをご覧ください。
このアプリは Google で確認されていません
SDM API は制限付きスコープを使用します。つまり、認可時にこのスコープを使用するアプリは、OAuth API の確認が完了していない限り「未確認」になります。個人使用で Device Access を使用する場合、OAuth API の確認は必要ありません。
認証プロセス中に「Google はこのアプリを確認していません」という画面が表示されることがあります。これは、Google Cloud の OAuth 同意画面で sdm.service スコープが構成されていない場合に表示されます。この画面は、[詳細設定] オプションをクリックしてから、[プロジェクト名（安全ではないページ）に移動] をクリックするとバイパスできます。
詳しくは、未確認アプリの画面をご覧ください。
クライアントが無効です
アクセス トークンまたは更新トークンを取得しようとしたときに、誤った OAuth 2.0 クライアント シークレットを指定すると、「Invalid client」エラーが発生します。アクセス トークンと更新トークンの呼び出しで使用している client_secret 値が、Google Cloud 認証情報ページで確認できる、使用されている OAuth 2.0 クライアント ID の値であることを確認します。
リクエストが無効です。必要なスコープがありません
PCM で権限を付与した後、「Missing required parameter: scope」という「Invalid request」エラーが発生することがあります。承認呼び出しで使用している scope 値が、Google Cloud 認証情報ページに表示されている OAuth 2.0 クライアントに設定した値と同じであることを確認します。
リダイレクト URI の不一致
認証を行う際に、「Redirect uri mismatch（リダイレクト URI の不一致）」エラーが発生することがあります。認証呼び出しで使用している redirect_uri の値が、Google Cloud 認証情報ページで確認できる OAuth 2.0 クライアントに設定した値と同じであることを確認します。
アカウントの権限を変更する
Device Access プロジェクトに付与された権限を変更するか、完全に接続を解除するには、PCM に移動します。
https://nestservices.google.com/partnerconnections
このページには、アカウントに接続されているすべてのサードパーティ デベロッパー サービス（Device Access プロジェクト）が表示されます。変更する Device Access プロジェクトを選択します。次の画面で、必要に応じて権限を変更します。
承認済みサービスの特定の権限のみを取り消すには、取り消す権限を切り替えて、戻る矢印をクリックして保存します。
承認済みのサービスを完全に切断するには、[Google アカウントのリンクを解除] をクリックして、プロジェクトに付与されたアカウントのすべての権限とアクセス トークンを取り消します。
PCM に目的のサービスが表示されない場合は、まずデバイスリストの呼び出しが必要になることがあります。
クイック リファレンス
このリファレンスを使用して、user の承認と Google アカウントのリンクの手順をすばやく実装します。
このクイック リファレンスを使用するには、コードサンプルの各プレースホルダ変数を特定の統合の値で編集し、必要に応じてコピーして貼り付けます。
1 PCM
ウェブブラウザで次のリンクを開き、次のように置き換えます。
- project-id は、実際の Device Access Project ID に置き換えます。
- oauth2-client-id には、Google Cloud 認証情報の OAuth2 クライアント ID を指定します。
https://nestservices.google.com/partnerconnections/project-id/auth?redirect_uri=https://www.google.com& access_type=offline& prompt=consent& client_id=oauth2-client-id& response_type=code& scope=https://www.googleapis.com/auth/sdm.service
2 認証コード
https://www.google.com にリダイレクトされます。認証コードは URL の code パラメータとして返されます。このパラメータは次の形式になります。
https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
3 アクセス トークン
認証コードを使用してアクセス トークンを取得し、SDM API の呼び出しに使用します。
ターミナルを開き、次の curl コマンドを実行します。
- oauth2-client-id と oauth2-client-secret には、Google Cloud 認証情報の OAuth2 クライアント ID とクライアント シークレットを指定します。
- authorization-code は、前の手順で受け取ったコードに置き換えます。
Google OAuth は、アクセス トークンと更新トークンの 2 つのトークンを返します。
リクエスト
curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&code=authorization-code&grant_type=authorization_code&redirect_uri=https://www.google.com' レスポンス
{
"access_token": "access-token",
"expires_in": 3599,
"refresh_token": "refresh-token",
"scope": "https://www.googleapis.com/auth/sdm.service",
"token_type": "Bearer"
}4 API 呼び出し
新しいアクセス トークンを使用して最初の devices.list 呼び出しを行うまで、承認は完了しません。この最初の呼び出しは、認証プロセスを完了し、Pub/Sub サブスクリプションをすでに設定している場合はイベントを有効にします。
指定されたスコープにリストされている API 呼び出しのいずれかを使用して、認証を完了する必要があります。
sdm.service
デバイス
詳細については、devices.list API リファレンスをご覧ください。
curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer access-token'5 更新トークン
SDM API のアクセス トークンは、Google OAuth から返される expires_in パラメータに記載されているように、1 時間のみ有効です。アクセス トークンの有効期限が切れた場合は、更新トークンを使用して新しいアクセス トークンを取得します。
ターミナルを開き、次の curl コマンドを実行します。
- oauth2-client-id と oauth2-client-secret には、Google Cloud 認証情報の OAuth2 クライアント ID とクライアント シークレットを指定します。
- refresh-token は、アクセス トークンを最初に取得したときに受け取ったコードに置き換えます。
Google OAuth から新しいアクセス トークンが返されます。
リクエスト
curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&refresh_token=refresh-token&grant_type=refresh_token' レスポンス
{
"access_token": "new-access-token",
"expires_in": 3599,
"scope": "https://www.googleapis.com/auth/sdm.service",
"token_type": "Bearer"
}