Permintaan Sinkronisasi memicu permintaan SYNC
ke pemenuhan Anda untuk setiap pengguna Google dengan perangkat yang memiliki agentUserId
tertentu yang terkait dengannya (yang Anda kirim dalam permintaan SYNC asli). Hal ini memungkinkan Anda mengupdate perangkat pengguna tanpa membatalkan tautan dan menautkan ulang akun mereka. Semua pengguna yang ditautkan ke ID ini akan menerima permintaan SYNC
.
Anda harus memicu permintaan SYNC
:
- Jika pengguna menambahkan perangkat baru.
- Jika pengguna menghapus perangkat yang ada.
- Jika pengguna mengganti nama perangkat yang ada.
- Jika Anda menerapkan jenis perangkat, fitur, atau menambahkan fitur perangkat baru.
Mulai
Untuk menerapkan Sinkronisasi Permintaan, ikuti langkah-langkah berikut:
Aktifkan Google HomeGraph API
-
Di Google Cloud Console, buka halaman HomeGraph API.
Buka halaman HomeGraph API - Pilih project yang cocok dengan project ID smart home Anda.
- Klik ENABLE.
Membuat Kunci Akun Layanan
Ikuti petunjuk ini untuk membuat kunci akun layanan dari Google Cloud Console:
-
Di Google Cloud Console, buka halaman Service accounts.
Buka halaman Service Accounts.Anda mungkin perlu memilih project sebelum diarahkan ke halaman Akun Layanan.
Klik
Buat akun layanan.Di kolom Nama akun layanan, masukkan nama.
Di kolom Service account ID, masukkan ID.
Di kolom Deskripsi akun layanan, masukkan sebuah deskripsi.
Klik Buat dan lanjutkan.
Dari dropdown Peran, pilih Akun Layanan > Pembuat Token OpenID Connect Identity pada Akun Layanan.
Klik Lanjutkan.
Klik Selesai.
Pilih akun layanan yang baru saja Anda buat dari daftar akun layanan dan pilih Kelola kunci dari menu
Tindakan.Pilih Tambahkan kunci > Buat kunci baru.
Untuk Jenis kunci, pilih opsi JSON.
Klik Buat. File JSON yang berisi kunci Anda akan didownload ke komputer Anda.
Memanggil API
HTTP
Home Graph API menyediakan endpoint HTTP
- Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
- Dapatkan token akses OAuth 2.0 dengan cakupan
https://www.googleapis.com/auth/homegraph
menggunakan oauth2l: - Buat permintaan JSON dengan
agentUserId
. Berikut adalah contoh permintaan JSON untuk Sinkronisasi Permintaan: - Gabungkan JSON Permintaan Sinkronisasi dan token dalam permintaan HTTP POST
Anda ke endpoint Google Home Graph. Berikut adalah contoh cara
membuat permintaan di command line menggunakan
curl
, sebagai pengujian:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "user-123" }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:requestSync"
gRPC
Home Graph API menyediakan endpoint gRPC
- Dapatkan definisi layanan buffer protokol untuk Home Graph API.
- Ikuti dokumentasi developer gRPC untuk membuat stub klien bagi salah satu bahasa yang didukung.
- Panggil metode RequestSync.
Node.js
Klien Node.js Google API menyediakan binding untuk Home Graph API.
- Lakukan inisialisasi layanan
google.homegraph
menggunakan Kredensial Default Aplikasi. - Panggil metode
requestSync
dengan RequestSyncDevicesRequest. Tindakan ini akan menampilkanPromise
dengan RequestSyncDevicesResponse kosong.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.requestSync({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', async: false } });
Java
Library Klien HomeGraph API untuk Java menyediakan binding untuk Home Graph API.
- Lakukan inisialisasi
HomeGraphApiService
menggunakan Kredensial Default Aplikasi. - Panggil metode
requestSync
denganRequestSyncDevicesRequest
. Tindakan ini akan menampilkanReportStateAndNotificationResponse
kosong.
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Request sync. RequestSyncDevicesRequest request = new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false); homegraphService.devices().requestSync(request);
Respons error
Anda mungkin menerima salah satu respons error berikut saat memanggil Sinkronisasi Permintaan. Respons ini berupa kode status HTTP.
400 Bad Request
- Server tidak dapat memproses permintaan yang dikirim oleh klien karena sintaksis tidak valid. Penyebab umum mencakup JSON yang salah format atau menggunakannull
, bukan "" untuk nilai string.403 Forbidden
- Server tidak dapat memproses permintaan untukagentUserId
tertentu karena terjadi error saat memperbarui token. Pastikan endpoint OAuth Anda merespons dengan benar permintaan token refresh dan periksa status penautan akun pengguna.404 Not Found
- Resource yang diminta tidak dapat ditemukan, tetapi mungkin tersedia pada masa mendatang. Biasanya, hal ini berarti akun pengguna tidak ditautkan dengan Google atau kami menerimaagentUserId
yang tidak valid. PastikanagentUserId
cocok dengan nilai yang diberikan dalam respons SYNC Anda, dan Anda menangani intent DISCONNECT dengan benar.429 Too Many Requests
- Jumlah maksimum permintaan sinkronisasi serentak telah terlampaui untukagentUserId
tertentu. Pemanggil hanya dapat mengeluarkan satu permintaan sinkronisasi serentak, kecuali jika tandaasync
ditetapkan ke benar (true).