Uỷ quyền tài khoản

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

Liên kết tài khoản của bạn

Để 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ới Device Access dự án của mình bằng Trình quản lý kết nối đối tác (PCM). PCM cho phép user cấp quyền cho cho phép developertruy cập vào dữ liệu 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 ID
   2. oauth2-client-id bằng Mã ứng dụng khách OAuth2 trong Thông tin đăng nhập 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ì bạn có thể thấy màn hình Chọn một tài khoản ban đầu có danh sách Tài khoản Google của bạn. Nếu vậy, 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 Device Access.
3. Màn hình Quyền của 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 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. Hãy sử dụng cùng một Tài khoản Google như trước.
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 có nội dung 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 cho Tên dự án, hãy nhấp vào 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 đảm bảo rằng các quyền mà bạn muốn cấp đã được đánh dấu 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 ở định dạng 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 đây, thay thế:

   1. oauth2-client-id và oauth2-client-secret bằng Mã ứng dụng khách OAuth2 và Khoá bí mật của ứng dụng khách trong Thông tin đăng nhập Google Cloud
   2. authorization-code bằng mã 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.

Tạo lệnh gọi danh sách thiết bị

Quá trình uỷ quyền sẽ chỉ hoàn tất 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 quá 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'

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 của bạn. Device AccessMỗ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 API SDM 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 sử dụng mã làm mới để lấy mã 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 grant_type khác.

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

   1. oauth2-client-id và oauth2-client-secret bằng Mã ứng dụng khách OAuth2 và Khoá bí mật của ứng dụng khách trong Thông tin đăng nhập Google Cloud
   2. refresh-token bằng mã mà bạn đã nhận được khi lấy 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 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ách không được phê duyệt là một nguyên nhân có thể xảy ra. Thời gian hết hạn của mã thông báo trong 7 ngày không liên quan đến việc phê duyệt cho Môi trường thương mại hoặc Môi trường thử nghiệm. 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 khách OAuth 2.0 và đưa vào môi trường thực tế để có thời gian tồn tại mã thông báo lâu hơn. Hãy xem bài viết 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 xin phép bằ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 thử nghiệm cho ứng dụng của bạn. Hãy nhớ thêm Tài khoản Google vào phần Người dùng thử nghiệm trong màn hình xin phép bằ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 Trình quản lý kết nối đối tác (PCM).

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

API SDM sử dụng 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ẽ là "chưa 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 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 bạn chưa đị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 Nâng cao rồi nhấp vào Chuyển đến Tên dự án (không an toàn).

Hãy xem màn hình Ứng dụng chưa 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ách không hợp lệ" nếu cung cấp Khoá bí mật của ứng dụng khách OAuth 2.0 không chính xác. Hãy đả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 khách OAuth 2.0 đang được sử dụng, như trong trang Thông tin đăng nhập 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ệ" của "Thiếu tham số bắt buộc: phạm vi". Hãy đảm bảo rằng giá trị scope mà bạn đang sử 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 khách OAuth 2.0, như trong trang Thông tin đăng nhập Google Cloud.

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

Khi thực hiện quá trình uỷ quyền, bạn có thể gặp lỗi "URI chuyển hướng không khớp". Hãy đả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ị mà bạn đã đặt cho Ứng dụng khách OAuth 2.0, như trong trang Thông tin đăng nhập 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 Device Access dự án hoặc ngắt kết nối nó hoàn toà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 (Device Access dự án) được kết nối với tài khoản của bạn. Chọn dự án mà bạn muốn thay đổi. Device Access 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 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 của bạn để 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ụ bạn muốn, thì trước tiên, bạn có thể cần thực hiện lệnh gọi danh sách thiết bị.

Tham khảo nhanh

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 user 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 giữ chỗ trong các mẫu mã 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:

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

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

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

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-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'

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