Memberi Otorisasi pada Akun

Setelah project Google Cloud dan Akses Perangkat dibuat, Anda dapat mengotorisasi Akun Google dengan perangkat Google Nest yang didukung untuk SDM API.

Menautkan akun

Untuk melihat struktur dan perangkat, Anda harus menautkan Akun Google ke Device Access project menggunakan PCM. PCM memungkinkan user untuk memberikan izin kepada memungkinkan developers untuk mengakses data struktur dan perangkatnya.

Dalam panduan ini, Anda berperan sebagai user dan developer.

1. Buka link berikut di web browser, dengan mengganti:

   1. project-id dengan Device Access Project ID
   2. oauth2-client-id dengan Client ID OAuth2 dari Kredensial Google Cloud Anda

   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. Jika baru-baru ini Anda login ke Google dengan beberapa akun, Anda mungkin akan melihat layar Pilih akun awal yang berisi daftar Akun Google Anda. Jika demikian, pilih Akun Google yang terhubung ke perangkat yang ingin Anda otorisasi Device Access.
3. Layar Izin Google Nest adalah PCM itu sendiri. Di sini, Anda dapat memberikan izin struktur dan perangkat. Aktifkan izin untuk rumah Anda (Langkah 1) dan perangkat apa pun di rumah tersebut yang didukung oleh SDM API (Langkah 2), lalu klik Berikutnya.
4. Di layar Pilih akun untuk melanjutkan ke Nama Project, dengan Nama Project adalah nama project Google Cloud Anda, pilih Akun Google yang ingin Anda otorisasi untuk SDM API. Gunakan Akun Google yang sama seperti sebelumnya.
5. Setelah memilih akun, Anda mungkin akan mendapatkan layar peringatan yang menyatakan Google belum memverifikasi aplikasi ini. Jika demikian, untuk melanjutkan, klik opsi Lanjutan , lalu klik Buka Nama Project (tidak aman). Lihat Google belum memverifikasi aplikasi ini untuk mengetahui informasi selengkapnya.
6. Di layar Berikan izin Nama Project, klik Izinkan untuk memberikan izin project mengakses Akun Google Anda.
7. Di layar Konfirmasi pilihan Anda , pastikan izin yang ingin Anda berikan dicentang, lalu klik Izinkan untuk mengonfirmasi.

8. Anda akan dialihkan ke https://www.google.com. Kode Otorisasi ditampilkan sebagai parameter code di URL, yang harus dalam format ini:

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

9. Salin kode otorisasi.

Mendapatkan token akses

Gunakan kode otorisasi untuk mengambil token akses, yang dapat Anda gunakan untuk memanggil SDM API.

1. Buka terminal dan jalankan perintah curl berikut, dengan mengganti:

   1. oauth2-client-id dan oauth2-client-secret dengan Client ID OAuth2 dan Client Secret dari Kredensial Google Cloud Anda
   2. authorization-code dengan kode yang Anda terima pada langkah sebelumnya

   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 menampilkan dua token, yaitu token akses dan token refresh.

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

   Salin kedua nilai ini. Token akses digunakan untuk memanggil SDM API dan token refresh digunakan untuk mendapatkan token akses baru.

Melakukan panggilan daftar perangkat

Otorisasi tidak akan selesai hingga Anda melakukan panggilan pertama devices.list dengan token akses baru. Panggilan awal ini menyelesaikan proses otorisasi dan mengaktifkan peristiwa jika Anda telah menyiapkan langganan Pub/Sub.

Gunakan curl untuk melakukan panggilan ini untuk endpoint devices:

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

Panggilan yang berhasil akan menampilkan daftar perangkat yang ditautkan ke Device Access project Anda. Setiap perangkat memiliki daftar karakteristik uniknya sendiri yang tersedia:

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

Cara menggunakan token refresh

Token akses untuk SDM API hanya berlaku selama 1 jam, seperti yang tercantum dalam parameter expires_in yang ditampilkan oleh Google OAuth. Jika masa berlaku token akses Anda habis, gunakan token refresh untuk mendapatkan token baru.

Perintah ini mirip dengan perintah token akses, kecuali bahwa Anda menggunakan grant_type yang berbeda.

1. Buka terminal dan jalankan perintah berikut curl, dengan mengganti:

   1. oauth2-client-id dan oauth2-client-secret dengan Client ID OAuth2 dan Client Secret dari Kredensial Google Cloud Anda
   2. refresh-token dengan kode yang Anda terima saat pertama kali mendapatkan akses 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'

2. Google OAuth menampilkan token akses baru.

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

Pemecahan masalah

Untuk mempelajari Google OAuth lebih lanjut, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Masa berlaku token refresh terus habis

Token refresh dapat berhenti berfungsi setelah 7 hari jika Client ID tidak disetujui adalah salah satu kemungkinan penyebabnya. Masa berlaku token 7 hari tidak terkait dengan persetujuan Komersial atau Sandbox. Akun layanan atau pengguna harus mendapatkan persetujuan Client ID OAuth 2.0 dan dimasukkan ke dalam produksi untuk mendapatkan masa berlaku token yang lebih lama. Lihat Masa berlaku token refresh untuk mengetahui informasi selengkapnya.

Akses ditolak

Jika Anda telah menyiapkan layar izin OAuth di Google Cloud dan Jenis pengguna adalah Eksternal, Anda akan mendapatkan error "Akses ditolak" jika mencoba menautkan akun dengan Akun Google yang tidak tercantum sebagai pengguna uji coba untuk aplikasi Anda. Pastikan untuk menambahkan Akun Google ke bagian Pengguna uji coba di layar izin OAuth Anda.

Error Partner Connections Manager (PCM)

Untuk mendapatkan bantuan terkait error yang terjadi saat mengakses PCM, lihat Referensi Error Partner Connections Manager (PCM).

Google belum memverifikasi aplikasi ini

SDM API menggunakan cakupan yang dibatasi, yang berarti bahwa aplikasi apa pun yang menggunakan cakupan ini selama otorisasi akan "belum diverifikasi" kecuali jika Verifikasi OAuth API selesai. Saat menggunakan Device Access untuk penggunaan pribadi, Verifikasi OAuth API tidak diperlukan.

Anda mungkin melihat layar "Google belum memverifikasi aplikasi ini" selama proses otorisasi, yang muncul jika cakupan sdm.service tidak dikonfigurasi di layar izin OAuth Anda di Google Cloud. Layar ini dapat dilewati dengan mengklik opsi Lanjutan , lalu mengklik Buka Nama Project (tidak aman).

Lihat Layar aplikasi belum diverifikasi untuk mengetahui informasi selengkapnya.

Klien tidak valid

Saat mencoba mendapatkan token akses atau token refresh, Anda akan mendapatkan error "Klien tidak valid" jika memberikan Rahasia Klien OAuth 2.0 yang salah. Pastikan nilai client_secret yang Anda gunakan dalam panggilan token akses dan token refresh adalah nilai untuk client ID OAuth 2.0 yang digunakan, seperti yang ditemukan di halaman Google Cloud Kredensial Anda.

Permintaan tidak valid, cakupan yang diperlukan tidak ada

Setelah memberikan izin di PCM, Anda mungkin mengalami error "Permintaan tidak valid" dengan pesan "Parameter yang diperlukan tidak ada: cakupan". Pastikan nilai scope yang Anda gunakan dalam panggilan otorisasi sama dengan nilai yang Anda tetapkan untuk Klien OAuth 2.0, seperti yang ditemukan di halaman Google Cloud Kredensial Anda.

URI pengalihan tidak cocok

Saat melakukan otorisasi, Anda mungkin mengalami error "URI pengalihan tidak cocok". Pastikan nilai redirect_uri yang Anda gunakan dalam panggilan otorisasi sama dengan nilai yang Anda tetapkan untuk Klien OAuth 2.0, seperti yang ditemukan di halaman Kredensial Google Cloud Anda.

Mengubah izin akun

Untuk mengubah izin yang diberikan ke a Device Access project, atau memutuskan koneksinya sepenuhnya, buka PCM:

https://nestservices.google.com/partnerconnections

Halaman ini menampilkan semua layanan developer pihak ketiga (Device Access project) yang terhubung ke akun Anda. Pilih Device Access project yang ingin Anda ubah. Gunakan layar berikutnya untuk mengubah izin sesuai keinginan.

Untuk mencabut izin tertentu saja untuk layanan yang diotorisasi, aktifkan izin yang ingin Anda cabut dan klik panah kembali untuk menyimpan.

Untuk memutuskan koneksi layanan yang diotorisasi sepenuhnya, klik Batalkan tautan Akun Google Anda untuk mencabut semua izin dan token akses yang telah diberikan project untuk akun tersebut.

Jika PCM tidak menampilkan layanan yang diinginkan, Anda mungkin perlu melakukan panggilan daftar perangkat terlebih dahulu.

Referensi cepat

Gunakan referensi ini untuk menerapkan langkah-langkah dengan cepat guna mengotorisasi user dan menautkan Akun Google mereka .

Untuk menggunakan referensi cepat ini, edit setiap variabel placeholder dalam contoh kode dengan nilai untuk integrasi spesifik Anda, lalu salin dan tempel sesuai kebutuhan:

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