授權帳戶

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

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

在本指南中,您同時具有 user 和 developer兩種身分。

  1. 請在網路瀏覽器中開啟以下連結,並取代:

    1. project-id (使用 Device Access Project ID)
    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,系統可能會顯示初始「選擇帳戶」畫面,列出您的 Google 帳戶。如果是的話,請選取與您想授權 Device Access的裝置相連結的 Google 帳戶。
  3. 「Google Nest 權限」畫面為 PCM 本身。您可以在這裡授予結構與裝置權限。啟用住家的權限 (步驟 1) 以及 SDM API 支援的所有裝置 (步驟 2),然後點選「下一步」
  4. 在「Choose an account to continue to Project Name畫面中,其中「Project Name」為您的 Google Cloud 專案名稱,選取要為 SDM API 授權的 Google 帳戶。使用和先前相同的 Google 帳戶。
  5. 選擇帳戶後,您可能會看見警告畫面,其中指出「Google 尚未驗證這個應用程式」。如果是的話,請按一下「Advanced」選項,然後點選「Go to Project Name (unsafe)」,即可繼續操作。詳情請參閱「Google 未驗證這個應用程式」一文。
  6. 在「Grant Project Name」(授予專案名稱) 權限畫面中,按一下「Allow」(允許),授予專案存取 Google 帳戶的權限。
  7. 在「Confirm your choose」(確認選擇) 畫面中,確認要授予的權限已勾選,然後按一下「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-idoauth2-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 訂閱項目,就會啟用事件。

使用 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-idoauth2-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"
    }

疑難排解

如要進一步瞭解 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 Cloud 的 OAuth 同意畫面中設定 sdm.service 範圍,可能會看到「Google 尚未驗證這個應用程式」畫面。如要略過這個畫面,請按一下「Advanced」選項,然後點選「Go to Project Name (unsafe)」

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

客戶無效

嘗試取得存取權或更新權杖時,如果您提供的 OAuth 2.0 用戶端密鑰不正確,您會收到「無效的用戶端」錯誤。請確認您在存取及更新權杖呼叫中使用的 client_secret 值與目前使用的 OAuth 2.0 用戶端 ID 相同,如 Google Cloud Credentials (Google Cloud 憑證) 頁面所述。

要求無效,缺少必要範圍

在 PCM 中授予權限後,您可能會遇到「缺少必要的參數:範圍」的「無效要求」錯誤。請確認您在授權呼叫中使用的 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 帳戶」,撤銷帳戶已授予的所有權限和存取權杖。

如果 PCM 未顯示所需服務,您可能需要先發出裝置清單呼叫

快速參考指引

使用此參考資料,快速實作授權user 並連結其 Google 帳戶的步驟。

如要使用這個快速參照,請使用特定整合的值編輯程式碼範例中的每個預留位置變數,並視需要複製及貼上:

1 PCM

請在網路瀏覽器中開啟以下連結,並取代:

  1. project-id (使用 Device Access Project ID)
  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-idoauth2-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 訂閱項目,就會啟用事件。

必須使用針對指定範圍列出的其中一個 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 的存取權杖有效期限只有 1 小時,如 Google OAuth 傳回的 expires_in 參數所示。如果存取權杖過期,請使用更新權杖取得新的權杖。

開啟終端機並執行以下 curl 指令,並替換:

  1. oauth2-client-idoauth2-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"
}