Halaman ini diterjemahkan oleh Cloud Translation API.

Memberi Otorisasi pada Akun

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

Tautkan akun Anda

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

Dalam panduan ini, Anda berperan sebagai user dan developer.

Buka link berikut di browser web, dengan mengganti:

project-id dengan ID Device Access Project Anda
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

Jika Anda login ke Google dengan beberapa akun baru-baru ini, Anda mungkin melihat layar awal Choose an account yang berisi daftar Akun Google Anda. Jika demikian, pilih Akun Google yang terkait dengan perangkat yang ingin Anda beri otorisasi untuk Device Access.
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 Next.
Di layar Choose an account to continue to Project Name, dengan Project Name adalah nama project Google Cloud Anda, pilih Akun Google yang ingin Anda beri otorisasi untuk SDM API. Gunakan Akun Google yang sama seperti sebelumnya.
Setelah memilih akun, Anda mungkin mendapatkan layar peringatan yang menyatakan Google belum memverifikasi aplikasi ini. Jika ya, untuk melanjutkan, klik opsi Lanjutan, lalu klik Buka Nama Project (tidak aman). Lihat Google belum memverifikasi aplikasi ini untuk mengetahui informasi selengkapnya.
Di layar Berikan izin Project Name, klik Allow untuk memberi project izin mengakses Akun Google Anda.
Di layar Konfirmasi pilihan Anda, pastikan izin yang ingin diberikan dicentang dan klik Izinkan untuk mengonfirmasi.
Anda akan dialihkan ke https://www.google.com. Kode Otorisasi ditampilkan sebagai parameter code di URL, yang seharusnya dalam format berikut:
```
https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
```
Salin kode otorisasi.

Mendapatkan token akses

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

Buka terminal dan jalankan perintah curl berikut, dengan mengganti:
1. oauth2-client-id dan oauth2-client-secret dengan Client ID dan Rahasia Klien OAuth2 dari Kredensial Google Cloud
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'
```
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 selesai sebelum Anda melakukan panggilan devices.list pertama dengan token akses baru. Panggilan awal ini akan menyelesaikan proses otorisasi dan mengaktifkan peristiwa jika Anda sudah 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 project Device Access Anda. Setiap perangkat memiliki daftar unik karakteristik 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 valid selama 1 jam, seperti yang tercantum dalam parameter expires_in yang ditampilkan oleh Google OAuth. Jika masa berlaku token akses Anda berakhir, gunakan token refresh untuk mendapatkan token baru.

Perintahnya mirip dengan token akses, kecuali bahwa Anda menggunakan grant_type yang berbeda.

Buka terminal dan jalankan perintah curl berikut, dengan mengganti:
1. oauth2-client-id dan oauth2-client-secret dengan Client ID dan Rahasia Klien OAuth2 dari Kredensial Google Cloud
2. refresh-token dengan kode yang Anda terima saat pertama kali mendapatkan token akses.
```
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'
```

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 akan terus berakhir

Token refresh dapat berhenti berfungsi setelah 7 hari jika client ID tidak disetujui adalah salah satu kemungkinan penyebabnya. Akhir 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 mulai diproduksi untuk mendapatkan masa pakai token yang lebih lama. Lihat Akhir masa berlaku token refresh untuk mengetahui informasi selengkapnya.

Akses ditolak

Jika Anda 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 di Layar izin OAuth.

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 setiap aplikasi yang menggunakan cakupan ini selama otorisasi akan "belum diverifikasi" kecuali Verifikasi OAuth API diselesaikan. 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 pada layar izin OAuth Anda di Google Cloud. Layar ini dapat diabaikan dengan mengklik opsi Advanced, lalu mengklik Go to Project Name (unsafe).

Lihat Layar aplikasi yang belum diverifikasi untuk informasi selengkapnya.

Klien tidak valid

Ketika mencoba mendapatkan token akses atau 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 refresh adalah nilai untuk Client ID OAuth 2.0 yang digunakan, seperti yang ada di halaman Kredensial Google Cloud.

Permintaan tidak valid, cakupan yang diperlukan tidak ada

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

URI pengalihan tidak cocok

Saat melakukan otorisasi, Anda mungkin mengalami error "Ketidakcocokan URI pengalihan". 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.

Ubah izin akun

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

https://nestservices.google.com/partnerconnections

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

Untuk mencabut izin tertentu saja untuk layanan yang diberi otorisasi, alihkan izin yang ingin Anda cabut dan klik panah kembali untuk menyimpan.

Untuk memutuskan sambungan layanan yang diberi otorisasi 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 guna mengizinkan user dan menautkan Akun Google miliknya dengan cepat.

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

1 PCM

Buka link berikut di browser web, dengan mengganti:

project-id dengan ID Device Access Project Anda
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 Kode Autentikasi

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

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

3 Token Akses

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

Buka terminal dan jalankan perintah curl berikut, dengan mengganti:

oauth2-client-id dan oauth2-client-secret dengan Client ID dan Rahasia Klien OAuth2 dari Kredensial Google Cloud
authorization-code dengan kode yang Anda terima pada langkah sebelumnya

Google OAuth menampilkan dua token, yaitu token akses dan token refresh.

Permintaan

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'

Respons

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

Panggilan API 4

Anda harus menggunakan salah satu panggilan API yang tercantum untuk cakupan yang ditentukan guna menyelesaikan otorisasi.

sdm.service

perangkat

Lihat referensi API devices.list untuk informasi selengkapnya.

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

5 Token Penyegaran

Buka terminal dan jalankan perintah curl berikut, dengan mengganti:

oauth2-client-id dan oauth2-client-secret dengan Client ID dan Rahasia Klien OAuth2 dari Kredensial Google Cloud
refresh-token dengan kode yang Anda terima saat pertama kali mendapatkan token akses.

Google OAuth menampilkan token akses baru.

Permintaan

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'

Respons

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