授權帳戶

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

連結帳戶

如要查看結構和裝置，您必須使用 PCM 將 Google 帳戶連結至Device Access 專案。PCM 可讓 user 授予權限，允許 developer存取其結構和裝置資料。

在本指南中，您會使用 user 和 developer。

注意： 如果您之前未複製 OAuth 2.0 用戶端 ID 和用戶端密鑰值，請立即透過 Google Cloud 憑證頁面取得。

1. 在網路瀏覽器中開啟下列連結，取代：

   1. project-id您的 Device Access Project 身分證件
   2. 將 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. 如果您最近使用多個帳戶登入 Google，系統可能會顯示最初的「Choose an account」(選擇帳戶) 畫面，並提供您的 Google 帳戶清單。如果是，請針對您要授權「 Device Access」的裝置，選取與該裝置相關聯的 Google 帳戶。
3. 「Google Nest permissions」(Google Nest 權限) 畫面是 PCM 本身。您可以在這裡授予結構和裝置權限。開啟住家 (步驟 1) 的權限，以及 SDM API (步驟 2) 支援的任何住家裝置，然後點選「下一步」。
4. 在「Choose an account to continue」(專案名稱) 畫面中，將「Project Name」(專案名稱) 設為 Google Cloud 專案的名稱，然後選取要授予 SDM API 的 Google 帳戶。使用相同的 Google 帳戶。
5. 選擇帳戶後，系統可能會顯示警告畫面，指出「Google 尚未驗證這個應用程式」。如要繼續，請按一下「Advanced」(進階) 選項，然後點選「Go to Project Name」(前往專案名稱) (不安全的)。詳情請參閱「Google 尚未驗證這個應用程式」。
6. 在授予專案名稱權限畫面中，按一下允許授予專案存取 Google 帳戶的權限。
7. 在「Confirm selection」畫面中，確認已授予的權限，然後按一下「Allow」確認。

8. 系統應會將您重新導向 https://www.google.com。授權碼會以 code 參數的形式傳回，格式如下：

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

9. 複製授權碼。

取得存取權杖

請使用授權碼擷取存取權杖，以便呼叫 SDM API。

1. 開啟終端機並執行下列 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'
   

2. 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 訂閱項目，這項初始呼叫即可完成授權程序並啟用事件。

此呼叫需要授權。此呼叫之前：

• 授權專案不會顯示在 PCM 上。
• 系統不會發布活動。

使用 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。

1. 開啟終端機並執行下列 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'
   

2. Google OAuth 會傳回新的存取權杖。

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

注意：如果您的Device Access 整合作業依賴 Pub/Sub 事件且很少進行 API 呼叫，那麼 user授權會在更新權杖過期時撤銷。 如要繼續存取，您必須使用更新權杖在 6 個月內重新整理存取權杖。如需更多授權方面的協助，請參閱「更新權杖效期」。

疑難排解

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

存取遭拒

如果您已在 Google Cloud 中設定 OAuth 同意畫面，且「使用者類型」為「外部」，但如果您嘗試使用的 Google 帳戶未連結至應用程式的測試使用者，就會看到「存取權遭拒」錯誤。請務必將 Google 帳戶新增至 OAuth 同意畫面的測試使用者部分。

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

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

Google 尚未驗證這個應用程式

SDM API 使用受限制的範圍，也就是說，除非使用 OAuth API 驗證，否則在授權期間使用這個範圍的應用程式都會「未經驗證」。將 Device Access 用於個人用途時，不需要 OAuth OAuth 驗證。

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

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

用戶端無效

如果您提供的 OAuth 2.0 用戶端密鑰有誤，在嘗試取得存取權或更新權杖時，系統會顯示「用戶端無效」錯誤。請確認您在存取和重新整理權杖呼叫中使用的 client_secret 值是關於 OAuth 2.0 用戶端 ID 的值 (如「Google Cloud 憑證」頁面所示)。

要求無效，缺少必要範圍

授予 PCM 權限後，您可能會遇到「Invalid request」(錯誤要求) 錯誤「缺少必要的參數：範圍」。請確認您在授權呼叫中使用的 scope 值與您為 OAuth 2.0 用戶端設定的值相同，如 Google Cloud 憑證頁面所示。

重新導向 URI 不符

授權過程中可能會發生「重新導向 URI 不符」錯誤，請確認您在授權呼叫中使用的 redirect_uri 值與您為 OAuth 2.0 用戶端設定的值相同，如 Google Cloud 憑證頁面所示。

修改帳戶權限

如要修改授予 Device Access 專案的權限或完全取消連結，請前往 PCM：

https://nestservices.google.com/partnerconnections

這個頁面會顯示與您的帳戶連結的所有第三方開發人員服務 (Device Access 專案)。選取您要變更的 Device Access 專案。使用下一個畫面視需要修改權限。

如要撤銷授權服務的特定權限，請切換您要撤銷的權限，然後按一下返回箭頭儲存。

如果要完全取消連結授權服務，請按一下「取消連結您的 Google 帳戶」，即可撤銷專案授予的所有權限和存取權杖。

注意： 您也可以透過 https://myaccount.google.com/permissions 的 Google 帳戶權限完全中斷授權服務。

如果 PCM 未顯示所需的服務，您可能需要先進行裝置清單呼叫。

快速參考指引

使用這個參考資料，快速實作user 並連結其 Google 帳戶的步驟。

若要使用這項快速參照，可使用程式碼範例中特定整合的值，編輯範例中的每個預留位置變數，然後視需要複製及貼上：

1 百萬瓦

在網路瀏覽器中開啟下列連結，取代：

1. project-id您的 Device Access Project 身分證件
2. 將 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 存取權杖

請使用授權碼擷取存取權杖，以便呼叫 SDM API。

開啟終端機並執行下列 curl 指令，藉此取代：

1. 將 oauth2-client-id 和 oauth2-client-secret 替換成 Google Cloud 憑證中的 OAuth2 用戶端 ID 和用戶端密鑰
2. 將 authorization-code 替換成您在上一個步驟中收到的代碼

Google OAuth 會傳回兩個權杖，分別是存取權杖和更新權杖。

要求

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 訂閱項目，這項初始呼叫即可完成授權程序並啟用事件。

此呼叫需要授權。此呼叫之前：

• 授權專案不會顯示在 PCM 上。
• 系統不會發布活動。

您必須使用指定範圍中的任一 API 呼叫才能完成授權。

dd.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 的存取權杖有效期限只有 1 小時，如 Google OAuth 傳回的 expires_in 參數所示。如果存取權杖已過期，請使用更新權杖取得新的權杖。

開啟終端機並執行下列 curl 指令，藉此取代：

1. 將 oauth2-client-id 和 oauth2-client-secret 替換成 Google Cloud 憑證中的 OAuth2 用戶端 ID 和用戶端密鑰
2. 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"
}