本頁面由 Cloud Translation API 翻譯而成。

授權帳戶

建立 Google Cloud 和裝置存取權專案後，您就可以為支援 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 帳戶。如果是，請選取與要授權的裝置相關聯的 Google 帳戶。 Device Access
「Google Nest 權限」畫面就是 PCM。您可以在此授予結構體和裝置權限。開啟住家許可權 (步驟 1) 和住家中 SDM API 支援的任何裝置 (步驟 2)，然後按一下「下一步」。
在「Choose an account to continue to Project Name」畫面 (「Project Name」是 Google Cloud 專案的名稱) 中，選取要授權使用 SDM API 的 Google 帳戶。使用先前使用的 Google 帳戶。
選擇帳戶後，您可能會看到一則警告畫面，指出「Google 尚未驗證此應用程式」。如果出現這則訊息，請按一下「進階」選項，然後點選「前往 Project Name (不安全)」。詳情請參閱「這個應用程式未經 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"
        }
      ]
    }
  ]
}

如何使用重新整理權杖

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

這項指令與存取權憑證指令類似，但您會使用不同的 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 時發生錯誤的相關說明，請參閱 Partner Connections Manager (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 中授予權限後，您可能會遇到「缺少必要參數：範圍」的「無效要求」錯誤。請確認您在授權呼叫中使用的 scope 值，與您在 Google Cloud 憑證頁面中為 OAuth 2.0 用戶端設定的值相同。

重新導向 URI 不符

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

修改帳戶權限

如要修改授予 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 存取權杖

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

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

oauth2-client-id 和 oauth2-client-secret 使用 Google Cloud 憑證中的 OAuth2 用戶端 ID 和用戶端密鑰
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 呼叫

您必須使用指定範圍中列出的其中一個 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 更新權杖

開啟終端機並執行下列 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"
}

1. 開始使用

3. 使用 API