Permissions API

Trước khi sử dụng bất kỳ API Home nào, ứng dụng phải có quyền truy cập vào các thiết bị trong nhà của người dùng, được gọi trong API là cấu trúc.

API Home sử dụng OAuth 2.0 để cấp quyền truy cập vào các thiết bị trong cấu trúc. OAuth cho phép người dùng cấp quyền cho một ứng dụng hoặc dịch vụ mà không cần tiết lộ thông tin đăng nhập của họ. Với API Quyền, người dùng có thể sử dụng Tài khoản Google của mình để cấp cho các ứng dụng API Home quyền truy cập vào các thiết bị trong nhà.

Việc sử dụng API Quyền bao gồm một số bước trong ứng dụng, Google Cloud và Google Home Developer Console:

1. Thiết lập OAuth trong Google Cloud
   1. Ký ứng dụng
   2. Thiết lập màn hình xin phép bằng OAuth
   3. Đăng ký ứng dụng và tạo thông tin xác thực
2. Tích hợp API Quyền
   1. Kiểm tra quyền
   2. Yêu cầu cấp quyền
3. Cấp quyền
   1. Thay đổi quyền
   2. Thu hồi quyền

Thiết lập OAuth trong Google Cloud

Nếu đã có ứng dụng khách OAuth đã xác minh, bạn có thể sử dụng ứng dụng đó mà không cần thiết lập ứng dụng mới. Để biết thêm thông tin, hãy tham khảo phần Nếu bạn đã có ứng dụng OAuth.

Ký ứng dụng

1. Tạo khoá OAuth bằng cách chạy ứng dụng trong Android Studio. Khi bạn chạy hoặc gỡ lỗi một ứng dụng trong Android Studio, ứng dụng đó sẽ tự động tạo một khoá OAuth dùng cho việc phát triển và gỡ lỗi. Hãy xem bài viết Android Studio: Ký bản gỡ lỗi để biết nội dung giải thích đầy đủ.

   Kết nối thiết bị di động với máy tính cục bộ. Android Studio sẽ liệt kê các thiết bị đã kết nối theo số hiệu. Chọn thiết bị của bạn trong danh sách rồi nhấp vào Run project (Chạy dự án). Thao tác này sẽ tạo và cài đặt ứng dụng mẫu trên thiết bị di động.

   Để biết hướng dẫn chi tiết hơn, hãy xem phần Chạy ứng dụng trên thiết bị phần cứng trên trang web dành cho nhà phát triển Android.

   Bây giờ, hãy dừng ứng dụng đang chạy.

2. Nhận vân tay số SHA-1 của chứng chỉ OAuth bằng cách làm theo hướng dẫn chi tiết trong phần Thiết lập OAuth 2.0 / Ứng dụng gốc/Android trên trang trợ giúp của Google Cloud Console.

Thiết lập màn hình xin phép bằng OAuth

1. Trong Google Cloud Console, hãy chuyển đến trang tổng quan về bộ chọn dự án rồi chọn dự án mà bạn muốn sử dụng để tạo thông tin xác thực OAuth.
2. Chuyển đến trang API và dịch vụ rồi nhấp vào Thông tin xác thực trong trình đơn điều hướng.

3. Nếu bạn chưa định cấu hình màn hình xin phép cho dự án Google Cloud này, thì nút Định cấu hình màn hình xin phép sẽ xuất hiện. Trong trường hợp đó, hãy định cấu hình màn hình xin phép bằng cách làm theo quy trình sau. Nếu không, hãy chuyển sang phần tiếp theo.

   1. Nhấp vào Định cấu hình màn hình đồng ý. Trang Màn hình xin phép bằng OAuth sẽ xuất hiện.
   2. Tuỳ thuộc vào trường hợp sử dụng, hãy chọn Nội bộ hoặc Ngoại bộ, sau đó nhấp vào Tạo. Ngăn Màn hình xin phép bằng OAuth sẽ xuất hiện.
   3. Nhập thông tin trên Trang thông tin ứng dụng theo hướng dẫn trên màn hình, sau đó nhấp vào Lưu và tiếp tục. Ngăn Phạm vi sẽ hiển thị.
   4. Bạn không cần thêm phạm vi nào, vì vậy, hãy nhấp vào Lưu và tiếp tục. Ngăn Người dùng thử nghiệm sẽ hiển thị.
   5. Nếu bạn muốn thêm người dùng để kiểm thử quyền truy cập vào ứng dụng, hãy nhấp vào Thêm người dùng. Ngăn Thêm người dùng sẽ hiển thị. Người dùng thử nghiệm có đặc quyền cấp quyền trong ứng dụng của bạn.
   6. Trong trường trống, hãy thêm một hoặc nhiều địa chỉ email của Tài khoản Google, sau đó nhấp vào Thêm.
   7. Nhấp vào Lưu và tiếp tục. Ngăn Summary (Tóm tắt) sẽ hiển thị.
   8. Xem lại thông tin trên màn hình xin phép bằng OAuth, sau đó nhấp vào Quay lại trang tổng quan.

Hãy xem bài viết Thiết lập màn hình đồng ý bằng OAuth trên trang web Trợ giúp của Google Cloud Console để biết toàn bộ thông tin chi tiết.

Đăng ký ứng dụng và tạo thông tin xác thực

Để đăng ký ứng dụng cho OAuth 2.0 và tạo thông tin xác thực OAuth, hãy làm theo hướng dẫn trong phần Thiết lập OAuth 2.0. Bạn cần chỉ định loại ứng dụng là ứng dụng gốc/ứng dụng Android.

Thêm vân tay SHA-1 mà bạn nhận được từ việc ký ứng dụng vào ứng dụng OAuth mà bạn thiết lập trên Google Cloud Console bằng cách làm theo hướng dẫn trong phần Thiết lập ứng dụng OAuth 2.0 / ứng dụng gốc trên trang trợ giúp của Google Cloud Console.

Khi thiết bị di động của bạn đã kết nối với máy cục bộ, hãy chọn thiết bị của bạn trong danh sách, sau đó nhấp lại vào Run project (Chạy dự án) để chạy dự án. Để biết hướng dẫn chi tiết hơn, hãy xem phần Chạy ứng dụng trên thiết bị phần cứng trên trang web dành cho nhà phát triển Android.

Tích hợp Permissions API

Người dùng phải cấp quyền cho ứng dụng của bạn để truy cập vào các thiết bị trong một cấu trúc nhất định. Để bắt đầu, hãy đảm bảo bạn đã khởi chạy API Trang chủ. Phiên bản homeManager từ bước đó được sử dụng trong tất cả các ví dụ về Quyền ở đây.

Trước tiên, hãy đăng ký một ActivityResultCaller với SDK. Ví dụ: đây là cách ứng dụng mẫu xử lý vấn đề này:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

Kiểm tra quyền

Trước khi yêu cầu cấp quyền, bạn nên kiểm tra xem người dùng ứng dụng đã đồng ý hay chưa. Để làm việc này, hãy gọi phương thức hasPermissions() của thực thể Home để lấy Flow của các giá trị PermissionsState:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

Nếu việc kiểm tra trả về PermissionsState của NOT_GRANTED hoặc PERMISSIONS_STATE_UNAVAILABLE, bạn nên yêu cầu cấp quyền. Nếu quy trình kiểm tra trả về PermissionsState của GRANTED nhưng lệnh gọi tiếp theo đến structures() không trả về cấu trúc nào, thì tức là người dùng đã thu hồi quyền truy cập vào ứng dụng thông qua trang cài đặt Google Home app (GHA) và bạn nên yêu cầu quyền. Nếu không, người dùng phải có quyền truy cập.

Yêu cầu cấp quyền

Bạn phải cấp quyền cho ứng dụng để truy cập vào các cấu trúc và thiết bị trong một cấu trúc nhất định.

Nếu người dùng chưa cấp quyền, hãy sử dụng phương thức requestPermissions() của thực thể Home để chạy giao diện người dùng Quyền và xử lý kết quả:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

Để giao diện người dùng Quyền chạy đúng cách, bạn phải thiết lập OAuth cho ứng dụng của mình.

Cấp quyền

Giờ đây, bạn có thể chạy ứng dụng và yêu cầu người dùng cấp quyền. Loại người dùng có thể cấp quyền và loại thiết bị có thể cấp quyền sẽ khác nhau tuỳ thuộc vào việc bạn đã đăng ký ứng dụng của mình trong Developer Console hay chưa.

Bạn cần đăng ký Developer Console để phát hành ứng dụng bằng API Home. Bạn không bắt buộc phải kiểm thử và sử dụng API Home. Để có quyền sử dụng tính năng đăng ký bảng điều khiển, hãy liên hệ với Technical Account Manager (TAM) của Google.

Nếu không được đăng ký trong Developer Console, ứng dụng sẽ ở trạng thái chưa được xác minh. Bạn nên làm như sau để kiểm thử việc sử dụng API Trang chủ:

• Chỉ những người dùng đã đăng ký làm người dùng thử nghiệm trong bảng điều khiển OAuth mới có thể cấp quyền cho ứng dụng. Một ứng dụng chưa được xác minh có giới hạn 100 người dùng thử nghiệm.

• Ứng dụng chưa được xác minh sẽ có quyền truy cập vào các thiết bị thuộc bất kỳ loại thiết bị nào được OAuth hỗ trợ cho API Home (danh sách các loại thiết bị trong Developer Console). Tất cả thiết bị trong một cấu trúc sẽ được cấp quyền.

Nếu một ứng dụng được đăng ký trong Developer Console và đã được phê duyệt quyền truy cập vào một hoặc nhiều loại thiết bị, đồng thời quy trình xác minh thương hiệu đã hoàn tất cho OAuth, thì ứng dụng đó sẽ ở trạng thái đã xác minh. Bạn phải có trạng thái này để phát hành ứng dụng lên phiên bản chính thức:

• Hạn mức người dùng thử nghiệm không còn áp dụng nữa. Mọi người dùng đều có thể cấp quyền cho ứng dụng.
• Người dùng chỉ có thể cấp quyền cho các loại thiết bị đã được phê duyệt trong Developer Console.

Giờ đây, khi OAuth đã được thiết lập, lệnh gọi của ứng dụng đến requestPermissions() sẽ kích hoạt các hộp thoại sau:

1. Người dùng sẽ được nhắc chọn Tài khoản Google mà họ muốn sử dụng.
2. Người dùng sẽ được nhắc chọn cấu trúc mà họ muốn cấp quyền truy cập cho ứng dụng.
   1. Đối với ứng dụng chưa được xác minh, ứng dụng có thể sử dụng tất cả các loại thiết bị mà API Home hỗ trợ.
   2. Đối với ứng dụng đã được xác minh, người dùng chỉ có thể cấp quyền cho các loại thiết bị đã được phê duyệt trong Developer Console.
   3. Đối với các loại thiết bị nhạy cảm mà ứng dụng có quyền quản lý, người dùng có thể hạn chế quyền truy cập trên mỗi thiết bị. Ví dụ: nếu người dùng có ba khoá, họ chỉ có thể cấp quyền truy cập vào một trong các khoá đó.

Sau khi được cấp quyền, ứng dụng có thể sử dụng API Home để đọc trạng thái và điều khiển các thiết bị trong cấu trúc. Nếu người dùng không cấp quyền cho ứng dụng đối với một loại thiết bị cụ thể hoặc thiết bị nhạy cảm, thì ứng dụng sẽ không thể sử dụng API Home để truy cập, kiểm soát hoặc tự động hoá thiết bị đó.

Thay đổi quyền

Để cấp quyền truy cập vào các thiết bị trong một cấu trúc khác, bạn có thể chạy bộ chọn tài khoản để cho phép người dùng chọn Tài khoản Google và cấu trúc để chuyển sang. Trong quá trình này, người dùng sẽ thấy lại màn hình yêu cầu đồng ý, ngay cả khi đã đồng ý trước đó.

Bạn có thể thực hiện việc này bằng cách gọi lại requestPermissions() với cờ forceLaunch được đặt thành true:

homeManager.requestPermissions(forceLaunch=true)

Thu hồi quyền

Người dùng có thể thu hồi quyền truy cập đã cấp trước đó:

1. Thông qua trang Tài khoản của tôi trên Google > Dữ liệu và quyền riêng tư > Ứng dụng và dịch vụ của bên thứ ba. Thao tác này sẽ thu hồi mã thông báo OAuth được cấp khi người dùng đồng ý ban đầu và sẽ thu hồi quyền truy cập vào mọi phiên bản của ứng dụng mà người dùng đang sử dụng trên tất cả các nền tảng (điện thoại) và cấu trúc.

2. Thông qua trang GHA > Cài đặt > Ứng dụng được liên kết. Khi nhấp vào settings trong GHA, bạn sẽ được chuyển đến trang Cài đặt. Tại đó, hãy nhấp vào thẻ thông tin Ứng dụng được liên kết để chuyển đến một trang tương tự như màn hình yêu cầu đồng ý. Trên trang này, người dùng có thể xoá quyền truy cập vào ứng dụng. Người dùng có thể sử dụng chính trang này để thay đổi loại thiết bị hoặc thiết bị nhạy cảm cụ thể mà ứng dụng có thể truy cập.

3. Thông qua trang Ứng dụng được liên kết ngay trên web.

Nếu bạn đã có ứng dụng khách OAuth

Nếu đã có ứng dụng khách OAuth đã xác minh cho một ứng dụng đã phát hành, bạn có thể sử dụng ứng dụng khách OAuth hiện có để kiểm thử API Home.

Bạn không cần đăng ký Developer Console để kiểm thử và sử dụng các API Home. Tuy nhiên, bạn vẫn cần có một lượt đăng ký Developer Console đã được phê duyệt để phát hành ứng dụng, ngay cả khi bạn có một ứng dụng khách OAuth đã xác minh từ một công cụ tích hợp khác.

Bạn cần cân nhắc những điều sau:

• Có giới hạn 100 người dùng khi sử dụng ứng dụng OAuth hiện có. Để biết thông tin về cách thêm người dùng thử nghiệm, hãy tham khảo phần Thiết lập màn hình đồng ý OAuth. Ngoài quy trình xác minh OAuth, API Home còn áp dụng giới hạn là 100 người dùng có thể cấp quyền cho ứng dụng của bạn. Hạn chế này sẽ được gỡ bỏ sau khi bạn hoàn tất việc đăng ký Developer Console.

• Bạn nên gửiDeveloper Console đăng ký để được phê duyệt khi bạn đã sẵn sàng hạn chế các khoản cấp theo loại thiết bị thông qua OAuth để chuẩn bị cập nhật ứng dụng bằng API Home.

Đối với các ứng dụng Google Cloud vẫn đang chờ xác minh OAuth, người dùng không thể hoàn tất luồng OAuth cho đến khi quá trình xác minh hoàn tất. Bạn sẽ không cấp được quyền với lỗi sau:

Access blocked: <Project Name> has not completed the Google verification process.

Quyền cho OkGoogle

Lệnh okGoogle là lệnh cấp cấu trúc và có thể được dùng để tự động hoá mọi thiết bị trong cấu trúc. Tuy nhiên, ứng dụng Home API có thể không có quyền truy cập vào mọi thiết bị. Bảng sau đây mô tả cách thực thi quyền trong những trường hợp như vậy.