授權帳戶

建立 Google Cloud 和 Device Access 專案後，您就能授權 Google 帳戶使用 SDM API 存取支援的 Google Nest 裝置。

連結你的帳戶

如要查看結構和裝置，必須使用 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。授權碼會以網址中的 code 參數形式傳回，格式如下：
```
https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
```
複製授權碼。

取得存取憑證

使用授權碼擷取存取權杖，即可呼叫 SDM API。

開啟終端機並執行下列curl指令，然後取代：
1. oauth2-client-id 和 oauth2-client-secret ，並使用 Google Cloud 憑證中的 OAuth2 用戶端 ID 和用戶端密鑰
2. 將 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 會傳回兩個權杖：存取權杖和更新權杖。

{
  "access_token": "access-token",
  "expires_in": 3599,
  "refresh_token": "refresh-token",
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

複製這兩個值。存取權杖用於呼叫 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"
        }
      ]
    }
  ]
}

如何使用更新權杖

SDM API 的存取憑證效期只有 1 小時，如 Google OAuth 傳回的 expires_in 參數所示。如果存取權杖過期，請使用更新權杖取得新的存取權杖。

這項指令與存取權杖指令類似，但您會使用不同的 grant_type。

開啟終端機並執行下列curl指令，並取代：
1. oauth2-client-id 和 oauth2-client-secret ，並使用 Google Cloud 憑證中的 OAuth2 用戶端 ID 和用戶端密鑰
2. 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 會傳回新的存取權杖。

{
  "access_token": "new-access-token",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

疑難排解

如要進一步瞭解 Google OAuth，請參閱「使用 OAuth 2.0 存取 Google API」。

更新權杖持續過期

如果用戶端 ID 未獲核准，更新權杖可能會在 7 天後失效。7 天權杖效期與商業或沙箱核准無關。服務或使用者帳戶必須先取得 OAuth 2.0 用戶端 ID 的核准，並投入生產環境，才能取得效期較長的權杖。詳情請參閱「更新權杖到期日」。

存取遭拒

如果您已在 Google Cloud 中設定 OAuth 同意畫面，且「使用者類型」為「外部」，當您嘗試連結未列為應用程式測試使用者的 Google 帳戶時，系統會顯示「存取遭拒」錯誤訊息。請務必將 Google 帳戶新增至 OAuth 同意畫面的「測試使用者」部分。

合作夥伴連線管理工具 (PCM) 錯誤

如需存取 PCM 時發生任何錯誤的相關說明，請參閱合作夥伴連結管理工具 (PCM) 錯誤參考資料。

這個應用程式未經 Google 驗證

SDM API 使用受限制的範圍，因此除非完成 OAuth API 驗證，否則在授權期間使用這個範圍的任何應用程式都會「未經驗證」。如果 Device Access 僅供個人使用，則無須進行 OAuth API 驗證。

授權程序期間，您可能會看到「Google 尚未驗證這個應用程式」畫面。如果 Google Cloud 的 OAuth 同意畫面未設定 sdm.service 範圍，就會顯示這個畫面。如要略過這個畫面，請按一下「進階」選項，然後按一下「前往『專案名稱』 (不安全)」。

詳情請參閱「未驗證的應用程式畫面」。

無效的用戶端

嘗試取得存取或更新權杖時，如果提供的 OAuth 2.0 用戶端密碼不正確，就會收到「無效的用戶端」錯誤訊息。請確認您在存取和更新權杖呼叫中使用的 client_secret 值，是您在 Google Cloud 憑證頁面中找到的 OAuth 2.0 用戶端 ID 值。

要求無效，缺少必要範圍

在 PCM 中授予權限後，您可能會遇到「Invalid request」錯誤，並顯示「Missing required parameter: scope」。請確認您在授權呼叫中使用的 scope 值，與您為 OAuth 2.0 用戶端設定的值相同，如Google Cloud 憑證頁面所示。

重新導向 URI 不符

進行授權時，您可能會遇到「Redirect uri mismatch」錯誤。請確認您在授權呼叫中使用的 redirect_uri 值，與您為 OAuth 2.0 用戶端設定的值相同，該值位於Google Cloud 憑證頁面。

修改帳戶權限

如要修改授予 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。授權碼會以網址中的 code 參數形式傳回，格式如下：

https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service

3 存取權杖