授權帳戶

建立 Google Cloud 和裝置存取權專案後 只要使用支援的 Google Nest 裝置，即可授權 Google 帳戶 SDM API。

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

在本指南中，您同時扮演 user 和 developer的角色。

  1. 在網頁上開啟以下連結 ，取代：

    1. 使用 Device Access Project ID 可享 project-id
    2. 將 oauth2-client-id 替換為您 Google Cloud 憑證
    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 帳戶。如果有，請選取與裝置連結的 Google 帳戶 希望為 Device Access授權。
  3. 「Google Nest 權限」畫面本身就是 PCM。 您可以在這裡授予結構和裝置權限。開啟 授予住家 (步驟 1) 和住家中所有裝置的權限 (步驟 2) 支援 SDM API，然後點選「下一步」。
  4. 在「Choose an account to continue」「Project Name」畫面，其中 「專案名稱」是您的 Google Cloud 專案名稱。選取 您要授權的 Google 帳戶 SDM API。使用先前使用的 Google 帳戶。
  5. 選擇帳戶後，您可能會看到一則警告畫面，指出「Google 尚未驗證此應用程式」。如果出現這則訊息，請按一下「進階」選項，然後點選「前往 Project Name (不安全)」。詳情請見 Google 尚未驗證這個應用程式 可能不準確或不適當
  6. 在「授予「專案名稱」權限」畫面中按一下「允許」，即可授予相關權限 可存取您 Google 帳戶的權限。
  7. 在「確認您的選擇」畫面上，確認已勾選要授予的權限，然後按一下「允許」確認。

  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」 複製而來的 OAuth2 用戶端 ID 和用戶端密鑰 Google Cloud 憑證
    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"
        }
      ]
    }
  ]
}

如何使用重新整理權杖

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

這項指令與存取權憑證指令類似，但您會使用不同的 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"
}

疑難排解

如要進一步瞭解 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 尚未驗證這個應用程式」訊息瀏覽授權期間的畫面 程序，如果未設定 sdm.service 範圍，系統就會顯示這個 Google Cloud 中的 OAuth 同意畫面。您可以使用 按一下進階選項，然後按一下前往專案 名稱 (不安全)。

請參閱「未驗證的應用程式」 螢幕 瞭解詳情

用戶端無效

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

要求無效，缺少必要範圍

在 PCM 中授予權限後，您可能需要執行 「要求無效」或顯示「缺少必要參數：範圍」錯誤請確認 您在授權呼叫中使用的 scope 值與您為 OAuth 2.0 用戶端設定的值相同。 Google Cloud 憑證 頁面。

重新導向 URI 不符

按照授權程序操作時，您可能會遇到「重新導向 URI 不符」問題 錯誤。請確認您在授權呼叫中使用的 redirect_uri 值，與您在 Google Cloud 憑證頁面中為 OAuth 2.0 用戶端設定的值相同。

修改帳戶權限

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

https://nestservices.google.com/partnerconnections

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

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

如要完全取消連結授權服務，請按一下「取消連結你的 Google 帳戶」 這個帳戶：用於撤銷專案曾擁有的所有權限和存取權杖 授予該帳戶使用權限

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

快速參考指引

請參考這份參考文件，快速執行授權 user 並連結他們的 Google 帳戶 ，直接在 Google Cloud 控制台實際操作。

如要使用這份快速參照資料，請將程式碼範例中的每個預留位置變數，修改為特定整合項目的值，並視需要複製及貼上：

1 PCM

在網頁上開啟以下連結 ，取代：

  1. 將 project-id 改成您的 Device Access Project ID
  2. 將 oauth2-client-id 替換為您 Google Cloud 憑證
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」 複製而來的 OAuth2 用戶端 ID 和用戶端密鑰 Google Cloud 憑證
  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 更新權杖

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

開啟終端機並執行下列 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"
}
上一頁
1. 開始使用
下一頁
3. 使用 API