Google Cloud プロジェクトと Device Access プロジェクトを作成すると、SDM API でサポートされている Google Nest デバイスで 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)の権限をオンに切り替え、[次へ] をクリックします。
- [アカウントを選択して [プロジェクト名] に移動する] 画面で、[プロジェクト名] は 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 つのトークンを返します。
{
これらの値を両方ともコピーします。アクセス トークンは SDM API の呼び出しに使用され、更新トークンは新しいアクセス トークンを取得するために使用されます。
デバイスリスト呼び出しを行う
新しいアクセス トークンを使用して最初の 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" } ] } ] }
更新トークンの使用方法
Google OAuth から返される expires_in
パラメータにあるように、SDM API のアクセス トークンは 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 が承認されない場合、1 つの考えられる原因として、更新トークンが 7 日後に機能しなくなることがあります。7 日間のトークンの有効期限は、商用またはサンドボックスの承認とは関係ありません。トークンの寿命を延ばすには、サービス アカウントまたはユーザー アカウントで OAuth 2.0 クライアント ID を承認して本番環境に移行する必要があります。詳細については、更新トークンの有効期限をご覧ください。
アクセスが拒否されました
Google Cloud で OAuth 同意画面を設定していて、ユーザータイプが [外部] の場合、アプリのテストユーザーとして登録されていない Google アカウントにアカウントをリンクしようとすると、「アクセスが拒否されました」というエラーが表示されます。OAuth 同意画面の [テストユーザー] セクションに Google アカウントを追加してください。
パートナー コネクション マネージャー(PCM)エラー
PCM へのアクセス時に発生したエラーについては、パートナー コネクション マネージャー(PCM)エラー リファレンスをご覧ください。
このアプリは Google によって確認されていません
SDM API は制限付きのスコープを使用します。つまり、OAuth API の確認が完了しない限り、承認時にこのスコープを使用するアプリは「未確認」となります。個人的に Device Access を使用する場合、OAuth API の確認は必要ありません。
承認プロセス中に、「このアプリは Google で確認されていません」という画面が表示されることがあります。これは、Google Cloud の OAuth 同意画面で sdm.service
スコープが構成されていない場合に表示されます。この画面を省略するには、[Advanced] オプションをクリックしてから、[Go to Project Name (unsafe)] をクリックします。
詳しくは、未確認のアプリの画面をご覧ください。
クライアントが無効です
アクセス トークンまたは更新トークンを取得する際に正しくない OAuth 2.0 クライアント シークレットを指定すると、「無効なクライアント」というエラーが表示されます。アクセス トークンと更新トークンの呼び出しに使用している client_secret
の値が、使用されている OAuth 2.0 クライアント ID の値であることを確認します。この値は、Google Cloud の認証情報ページで確認できます。
リクエストが無効です。必要なスコープがありません
PCM で権限を付与した後、「必須パラメータがありません: スコープ」という「無効なリクエスト」エラーが発生することがあります。認証呼び出しで使用している scope
値は、Google Cloud の認証情報ページにある OAuth 2.0 クライアント用に設定した値と同じであることを確認します。
リダイレクト URI の不一致
承認中に「Redirect URI の不一致」エラーが発生することがあります。認可呼び出しで使用している redirect_uri
の値は、Google Cloud の認証情報ページにある OAuth 2.0 クライアントに設定した値と同じであることを確認します。
アカウントの権限を変更
プロジェクトに付与されている権限を変更するか、 Device Access 全体との接続を解除するには、PCM に移動します。
https://nestservices.google.com/partnerconnections
このページには、アカウントに接続されているすべてのサードパーティ デベロッパー サービス(Device Access プロジェクト)が表示されます。変更する Device Access プロジェクトを選択します。次の画面で、必要に応じて権限を変更します。
承認済みのサービスに対して特定の権限のみを取り消すには、取り消す権限を切り替え、戻る矢印をクリックして保存します。
承認済みサービスを完全に切断するには、[Google アカウントのリンクを解除] をクリックして、プロジェクトに付与されているすべての権限とアクセス トークンを取り消します。
PCM に目的のサービスが表示されない場合は、まずデバイスリストの呼び出しを行う必要があります。
クイック リファレンス
このリファレンスを使用すると、user を承認して Google アカウントをリンクする手順を簡単に実装できます。
このクイック リファレンスを使用するには、特定の統合の値でコードサンプルの各プレースホルダ変数を編集し、必要に応じてコピーして貼り付けます。
PCM 1 回
ウェブブラウザで次のリンクを開きます。置き換えてください。
- 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 更新トークン
Google OAuth から返される expires_in
パラメータにあるように、SDM API のアクセス トークンは 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" }