Uỷ quyền tài khoản

Sau khi tạo dự án Google Cloud và dự án Quyền truy cập thiết bị, 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 API SDM.

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

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 mã nhận dạng
    2. oauth2-client-id với Mã ứng dụng khách OAuth2 trong Thông tin xác thực 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 đã đăng nhập vào Google bằng nhiều tài khoản, bạn có thể thấy màn hình Chọn tài khoản ban đầu có danh sách các tài khoản Google của bạn. Nếu có, hãy chọn Tài khoản Google 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 cho cấu trúc và thiết bị. Bật các quyền cho nhà của bạn (Bước 1) và mọi thiết bị trong nhà đó được API SDM 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 API SDM. 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ột màn hình cảnh báo cho biết rằng 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 tuỳ 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 bài viết 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 Project Name (Cấp quyền cho Project Name), hãy nhấp vào Allow (Cho phép) để cấp quyền truy cập vào Tài khoản Google của bạn cho dự án.
  7. Trên màn hình Xác nhận lựa chọn của bạn, hãy nhớ đánh dấu vào các quyền 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, 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 API SDM.

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

    1. oauth2-client-id và oauth2-client-secret bằng Mã ứng dụng OAuth2 và Mật khẩu ứng dụng trong Thông tin đăng nhập 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ề hai mã thông báo, một mã truy cập và một 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 API SDM và mã làm mới được dùng để lấy mã truy cập mới.

Thực hiện lệnh gọi danh sách thiết bị

Quá trình uỷ quyền sẽ chưa hoàn tất cho đến khi bạn thực hiện lệnh 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à bật các sự kiện nếu bạn đã thiết lập 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 các đặc điểm riêng:

{
  "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ã thông báo làm mới

Mã truy cập cho API SDM chỉ có hiệu lực trong 1 giờ, như được ghi chú 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 sử 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ã thông báo 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 và chạy lệnh curl sau, thay thế:

    1. oauth2-client-id và oauth2-client-secret bằng Mã ứng dụng OAuth2 và Mật khẩu ứng dụng trong Thông tin đăng nhập Google Cloud
    2. refresh-token bằng mã bạn nhận được khi nhận được mã truy cập ban đầ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 API của Google.

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

Mã thông báo 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. Thời gian hết hạn của mã thông báo 7 ngày không liên quan đến việc phê duyệt cho mục đích thương mại hoặc trong 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ã thông báo làm mới để biết thêm thông tin.

Truy cập bị từ chối

Nếu đã 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, bạn sẽ gặp lỗi "Từ chối quyền truy cập" 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 liệt kê là người dùng thử nghiệm 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 thử nghiệm 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 quan hệ đối tác (PCM).

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

API SDM sử dụng một phạm vi bị hạn chế, nghĩa là mọi ứng dụng sử dụng phạm vi này trong quá trình uỷ quyền sẽ "chưa được xác minh" trừ khi quá trình Xác minh API OAuth đã hoàn tất. 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 sẽ xuất hiện nếu bạn không định cấu hình phạm vi sdm.service 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 tuỳ chọn Advanced (Nâng cao), sau đó nhấp vào Go to Project Name (unsafe) (Chuyển đến Project Name (Tên dự án) (không an toàn)).

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

Ứng dụng khách 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 sai Khoá ứng dụng OAuth 2.0. Đảm bảo rằng giá trị client_secret bạn đang sử dụng trong các lệnh gọi mã truy cập và làm mới là giá trị cho Mã ứng dụng OAuth 2.0 đang được sử dụng, như trong trang Thông tin xác thực trên 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 lỗi "Yêu cầu không hợp lệ" với thông báo "Thiếu tham số bắt buộc: phạm vi". Đảm bảo rằng giá trị scope bạn đang sử dụng trong các lệnh gọi uỷ quyền giống với giá trị bạn đã đặt cho Ứng dụng OAuth 2.0, như trong trang Thông tin xác thực Google Cloud.

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

Khi thực hiện quy trình 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 sử dụng trong các lệnh gọi uỷ quyền giống với giá trị bạn đã đặt cho Ứng dụng OAuth 2.0, như trong trang Thông tin xác thực trên 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 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ả dịch vụ dành cho 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 dự án Device Access 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 với 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 của bạn để thu hồi tất 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ể phải thực hiện lệnh gọi danh sách thiết bị.

Tài liệu 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 cho mộtuser và liên kết Tài khoản Google của họ.

Để sử dụng tài liệu 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 quá trình tích hợp cụ thể của bạn, rồi sao chép và dán nếu 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 mã nhận dạng
  2. oauth2-client-id với Mã ứng dụng khách OAuth2 trong Thông tin xác thực 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, 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 API SDM.

Mở một cửa sổ dòng lệnh và chạy lệnh curl sau, thay thế:

  1. oauth2-client-id và oauth2-client-secret bằng Mã ứng dụng OAuth2 và Mật khẩu ứng dụng trong Thông tin đăng nhập Google Cloud
  2. authorization-code bằng mã bạn nhận được ở bước trước

Google OAuth trả về hai mã thông báo, một mã truy cập và một 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

Quá trình uỷ quyền sẽ chưa hoàn tất cho đến khi bạn thực hiện lệnh 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à bật các sự kiện nếu bạn đã thiết lập 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 API SDM chỉ có hiệu lực trong 1 giờ, như được ghi chú 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 sử dụng mã làm mới để lấy mã mới.

Mở một cửa sổ dòng lệnh và chạy lệnh curl sau, thay thế:

  1. oauth2-client-id và oauth2-client-secret bằng Mã ứng dụng OAuth2 và Mật khẩu ứng dụng trong Thông tin đăng nhập Google Cloud
  2. refresh-token bằng mã bạn nhận được khi nhận được mã truy cập ban đầ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