Uỷ quyền tài khoản

Sau khi tạo dự án Google Cloud và Device Access, bạn có thể uỷ quyền cho một Tài khoản Google có thiết bị Google Nest được hỗ trợ cho SDM API.

Để xem các cấu trúc và thiết bị, bạn phải liên kết một Tài khoản Google vớiDevice Access dự án của mình bằng PCM. PCM cho phép user cấp quyền cho phép developertruy cập vào dữ liệu về cấu trúc và thiết bị của họ.

Trong hướng dẫn này, bạn đóng vai trò là cả user và developer.

  1. Mở đường liên kết sau đây trong trình duyệt web, thay thế:

    1. project-id bằng Device Access Project giấy tờ tuỳ thân
    2. oauth2-client-id bằng Mã ứng dụng OAuth2 trong Thông tin đăng nhập trên 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. Nếu gần đây bạn đã đăng nhập vào Google bằng nhiều tài khoản, thì có thể bạn sẽ thấy màn hình Chọn một tài khoản ban đầu kèm theo danh sách Tài khoản Google của bạn. Nếu có, hãy chọn Tài khoản Google được liên kết với(các) thiết bị mà bạn muốn uỷ quyền cho Device Access.
  3. Màn hình Quyền đối với các thiết bị Google Nest chính là PCM. Tại đây, bạn có thể cấp quyền đối với cấu trúc và thiết bị. Bật quyền cho nhà của bạn (Bước 1) và mọi thiết bị trong nhà đó được SDM API hỗ trợ (Bước 2), sau đó nhấp vào Tiếp theo.
  4. Trên màn hình Chọn một tài khoản để tiếp tục đến Tên dự án, trong đó Tên dự án là tên dự án Google Cloud của bạn, hãy chọn Tài khoản Google mà bạn muốn uỷ quyền cho SDM API. Sử dụng cùng một Tài khoản Google như trước đây.
  5. Sau khi chọn một tài khoản, bạn có thể thấy màn hình cảnh báo cho biết Google chưa xác minh ứng dụng này. Nếu vậy, để tiếp tục, hãy nhấp vào lựa chọn Nâng cao rồi nhấp vào Chuyển đến Tên dự án (không an toàn). Hãy xem phần Google chưa xác minh ứng dụng này để biết thêm thông tin.
  6. Trên màn hình Cấp quyền cho Tên dự án, hãy nhấp vào Cho phép để cấp cho dự án quyền truy cập vào Tài khoản Google của bạn.
  7. Trên màn hình Xác nhận lựa chọn của bạn, hãy đảm bảo rằng bạn đã đánh dấu vào những quyền mà bạn muốn cấp rồi nhấp vào Cho phép để xác nhận.

  8. Bạn sẽ được chuyển hướng đến https://www.google.com. Mã uỷ quyền được trả về dưới dạng tham số code trong URL, phải có định dạng như sau:

    https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
  9. Sao chép mã uỷ quyền.

Lấy mã truy cập

Sử dụng mã uỷ quyền để truy xuất mã truy cập mà bạn có thể dùng để gọi SDM API.

  1. Mở một cửa sổ dòng lệnh rồi chạy lệnh curl sau đây, thay thế:

    1. oauth2-client-id và oauth2-client-secret cùng với Mã ứng dụng OAuth2 và Khoá bí mật của ứng dụng khách từ Thông tin đăng nhập trên Google Cloud
    2. authorization-code bằng mã bạn nhận được ở bước trước
    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 trả về 2 mã thông báo, đó là mã truy cập và mã làm mới.

    {
  "access_token": "access-token",
  "expires_in": 3599,
  "refresh_token": "refresh-token",
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}
     Sao chép cả hai giá trị này. Mã truy cập được dùng để gọi SDM API và mã làm mới được dùng để lấy mã truy cập mới.

Gọi điện bằng danh sách thiết bị

Bạn chỉ hoàn tất việc uỷ quyền khi thực hiện cuộc gọi devices.list đầu tiên bằng mã truy cập mới. Lệnh gọi ban đầu này sẽ hoàn tất quy trình uỷ quyền và cho phép các sự kiện nếu bạn đã thiết lập một gói thuê bao Pub/Sub.

Sử dụng curl để thực hiện lệnh gọi này cho điểm cuối devices:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

Một lệnh gọi thành công sẽ trả về danh sách các thiết bị được liên kết với dự án Device Accesscủa bạn. Mỗi thiết bị có danh sách riêng biệt gồm các đặc điểm có sẵn:

{
  "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"
        }
      ]
    }
  ]
}

Cách sử dụng mã làm mới

Mã truy cập cho SDM API chỉ có hiệu lực trong 1 giờ, như đã lưu ý trong tham số expires_in do Google OAuth trả về. Nếu mã truy cập của bạn hết hạn, hãy dùng mã làm mới để lấy mã truy cập mới.

Lệnh này tương tự như lệnh mã truy cập, ngoại trừ việc bạn sử dụng một grant_type khác.

  1. Mở một cửa sổ dòng lệnh rồi chạy lệnh curl sau đây, thay thế:

    1. oauth2-client-id và oauth2-client-secret cùng với Mã ứng dụng OAuth2 và Khoá bí mật của ứng dụng khách từ Thông tin đăng nhập trên Google Cloud
    2. refresh-token bằng mã bạn nhận được khi lấy mã thông báo truy cập lần đầu.
    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 trả về một mã truy cập mới.

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

Khắc phục sự cố

Để tìm hiểu thêm về Google OAuth, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập vào các API của Google.

Mã làm mới liên tục hết hạn

Mã làm mới có thể ngừng hoạt động sau 7 ngày nếu mã ứng dụng không được phê duyệt. Đây là một nguyên nhân có thể xảy ra. Thời hạn 7 ngày của mã thông báo không liên quan đến việc phê duyệt Thương mại hoặc Hộp cát. Tài khoản dịch vụ hoặc tài khoản người dùng cần được phê duyệt mã ứng dụng OAuth 2.0 và đưa vào sản xuất để có thời gian tồn tại mã thông báo dài hơn. Hãy xem phần Thời gian hết hạn của mã làm mới để biết thêm thông tin.

Truy cập bị từ chối

Nếu bạn đã thiết lập màn hình yêu cầu đồng ý OAuth trong Google Cloud và Loại người dùng là Bên ngoài, thì bạn sẽ gặp lỗi "Truy cập bị từ chối" nếu cố gắng liên kết tài khoản với một Tài khoản Google không có trong danh sách người dùng kiểm thử cho ứng dụng của bạn. Hãy nhớ thêm Tài khoản Google đó vào mục Người dùng kiểm thử trong màn hình yêu cầu đồng ý OAuth.

Lỗi Trình quản lý kết nối đối tác (PCM)

Để được trợ giúp về mọi lỗi gặp phải khi truy cập vào PCM, hãy xem Tài liệu tham khảo về lỗi của Trình quản lý mối kết nối với đối tác (PCM).

Google chưa xác minh ứng dụng này

SDM API sử dụng một phạm vi bị hạn chế, tức là mọi ứng dụng sử dụng phạm vi này trong quá trình uỷ quyền sẽ ở trạng thái "chưa được xác minh" trừ phi bạn hoàn tất quy trình Xác minh API OAuth. Khi sử dụng Device Access cho mục đích cá nhân, bạn không cần phải xác minh API OAuth.

Bạn có thể thấy màn hình "Google chưa xác minh ứng dụng này" trong quá trình uỷ quyền. Màn hình này xuất hiện nếu phạm vi sdm.service chưa được định cấu hình trên màn hình xin phép bằng OAuth trong Google Cloud. Bạn có thể bỏ qua màn hình này bằng cách nhấp vào lựa chọn Nâng cao, rồi nhấp vào Chuyển đến Tên dự án (không an toàn).

Hãy xem phần Màn hình ứng dụng chưa được xác minh để biết thêm thông tin.

Ứng dụng không hợp lệ

Khi cố gắng lấy mã truy cập hoặc mã làm mới, bạn sẽ gặp lỗi "Ứng dụng không hợp lệ" nếu cung cấp Khoá bí mật của ứng dụng OAuth 2.0 không chính xác. Đảm bảo rằng giá trị client_secret mà bạn đang sử dụng trong các lệnh gọi mã truy cập và mã làm mới là giá trị cho Mã ứng dụng OAuth 2.0 đang được sử dụng, như trên trang Thông tin xác thực của Google Cloud.

Yêu cầu không hợp lệ, thiếu phạm vi bắt buộc

Sau khi cấp quyền trong PCM, bạn có thể gặp phải lỗi "Yêu cầu không hợp lệ" "Thiếu tham số bắt buộc: phạm vi". Đảm bảo rằng giá trị scope mà bạn đang dùng trong các lệnh gọi uỷ quyền giống với giá trị mà bạn đặt cho OAuth 2.0 Client, như trong trang Thông tin đăng nhập trên Google Cloud.

URI chuyển hướng không khớp

Khi thực hiện uỷ quyền, bạn có thể gặp lỗi "Redirect uri mismatch" (URI chuyển hướng không khớp). Đảm bảo rằng giá trị redirect_uri mà bạn đang dùng trong các lệnh gọi uỷ quyền giống với giá trị mà bạn đã đặt cho Ứng dụng OAuth 2.0, như trên trang Thông tin xác thực của Google Cloud.

Sửa đổi quyền đối với tài khoản

Để sửa đổi các quyền được cấp cho một dự án Device Access hoặc ngắt kết nối hoàn toàn dự án đó, hãy chuyển đến PCM:

https://nestservices.google.com/partnerconnections

Trang này hiển thị tất cả các dịch vụ của nhà phát triển bên thứ ba (dự ánDevice Access ) được kết nối với tài khoản của bạn. Chọn Device Access dự án mà bạn muốn thay đổi. Sử dụng màn hình tiếp theo để sửa đổi quyền theo ý muốn.

Để chỉ thu hồi một số quyền cụ thể cho một dịch vụ được uỷ quyền, hãy bật/tắt các quyền mà bạn muốn thu hồi rồi nhấp vào mũi tên quay lại để lưu.

Để ngắt kết nối hoàn toàn một dịch vụ được uỷ quyền, hãy nhấp vào Huỷ liên kết Tài khoản Google để thu hồi tất cả các quyền và mã truy cập mà dự án đã được cấp cho tài khoản.

Nếu PCM không hiển thị dịch vụ mong muốn, trước tiên, bạn có thể cần phải gọi danh sách thiết bị.

Thông tin tham khảo nhanh

Hãy sử dụng tài liệu tham khảo này để nhanh chóng triển khai các bước uỷ quyền chouser và liên kết tài khoản Google của họ.

Để sử dụng thông tin tham khảo nhanh này, hãy chỉnh sửa từng biến phần giữ chỗ trong mã mẫu bằng các giá trị cho hoạt động tích hợp cụ thể của bạn, rồi sao chép và dán khi cần:

1 PCM

Mở đường liên kết sau đây trong trình duyệt web, thay thế:

  1. project-id bằng Device Access Project giấy tờ tuỳ thân
  2. oauth2-client-id bằng Mã ứng dụng OAuth2 trong Thông tin đăng nhập trên 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 mã xác thực

Bạn sẽ được chuyển hướng đến https://www.google.com. Mã uỷ quyền được trả về dưới dạng tham số code trong URL, phải có định dạng như sau:

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

3 Mã truy cập

Sử dụng mã uỷ quyền để truy xuất mã truy cập mà bạn có thể dùng để gọi SDM API.

Mở một cửa sổ dòng lệnh rồi chạy lệnh curl sau đây, thay thế:

  1. oauth2-client-id và oauth2-client-secret cùng với Mã ứng dụng OAuth2 và Khoá bí mật của ứng dụng khách từ Thông tin đăng nhập trên Google Cloud
  2. authorization-code bằng mã bạn nhận được ở bước trước

Google OAuth trả về 2 mã thông báo, đó là mã truy cập và mã làm mới.

Yêu cầu

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'

Phản hồi

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

4 Lệnh gọi API

Bạn chỉ hoàn tất việc uỷ quyền khi thực hiện cuộc gọi devices.list đầu tiên bằng mã truy cập mới. Lệnh gọi ban đầu này sẽ hoàn tất quy trình uỷ quyền và cho phép các sự kiện nếu bạn đã thiết lập một gói thuê bao Pub/Sub.

Bạn phải sử dụng một trong các lệnh gọi API được liệt kê cho phạm vi đã chỉ định để hoàn tất quá trình uỷ quyền.

sdm.service

thiết bị

Hãy xem tài liệu tham khảo về API devices.list để biết thêm thông tin.

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

5 Mã làm mới

Mã truy cập cho SDM API chỉ có hiệu lực trong 1 giờ, như đã lưu ý trong tham số expires_in do Google OAuth trả về. Nếu mã truy cập của bạn hết hạn, hãy dùng mã làm mới để lấy mã truy cập mới.

Mở một cửa sổ dòng lệnh rồi chạy lệnh curl sau đây, thay thế:

  1. oauth2-client-id và oauth2-client-secret cùng với Mã ứng dụng OAuth2 và Khoá bí mật của ứng dụng khách từ Thông tin đăng nhập trên Google Cloud
  2. refresh-token bằng mã bạn nhận được khi lấy mã thông báo truy cập lần đầu.

Google OAuth trả về một mã truy cập mới.

Yêu cầu

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'

Phản hồi

{
  "access_token": "new-access-token",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}
Trước
1. Bắt đầu
Tiếp
3. Sử dụng API