Report State adalah fitur penting yang memungkinkan
Tindakan Home secara proaktif melaporkan status terbaru
perangkat pengguna kembali ke Google Home Graph, bukan menunggu
QUERY
.
Report State melaporkan status perangkat pengguna kepada Google
dengan agentUserId
yang ditentukan yang terkait dengannya (dikirim dalam
SYNC
). Saat Google Assistant ingin mengambil tindakan
yang membutuhkan pemahaman tentang keadaan
perangkat saat ini, aplikasi dapat langsung terlihat
informasi negara bagian di Home Graph sebagai gantinya
penerbitan intent QUERY
ke berbagai cloud pihak ketiga sebelum mengeluarkan
EXECUTE
.
Tanpa Report State, mengingat cahaya dari beberapa penyedia di
ruang keluarga, perintah Ok Google, cerahkan ruang tamu saya memerlukan
menyelesaikan beberapa intent QUERY
yang dikirim ke beberapa cloud, bukan
hanya mencari nilai kecerahan saat ini
berdasarkan apa yang telah
dilaporkan sebelumnya. Untuk memberikan
pengalaman pengguna terbaik,
Assistant harus memiliki status perangkat saat ini,
tanpa perlu bolak-balik ke perangkat.
Setelah SYNC
awal untuk perangkat, platform akan mengirim intent QUERY
yang mengumpulkan status perangkat untuk mengisi Home Graph.
Setelah itu, Home Graph hanya menyimpan status yang
dikirim dengan Report State.
Saat memanggil Report State, pastikan Anda memberikannya dengan lengkap
status data untuk sifat tertentu. Home Graph memperbarui status di
dan menimpa semua data untuk fitur tersebut.
Panggilan Report State dilakukan. Misalnya, jika Anda melaporkan
status untuk fitur StartStop, payload
harus menyertakan nilai untuk isRunning
dan isPaused
.
Mulai
Untuk menerapkan Report State, ikuti langkah-langkah berikut:
Mengaktifkan 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 berikut untuk membuat kunci akun layanan dari Google Cloud Console:
-
Di Google Cloud Console, buka halaman Create service account key.
Buka halaman Create Service Account Key - Dari daftar Service account, pilih Akun layanan baru.
- Di kolom Nama akun layanan, masukkan nama.
- Di kolom ID akun layanan, masukkan ID.
Dari daftar Role, pilih Service Accounts > Service Account Token Creator Google.
Untuk Jenis kunci, pilih opsi JSON.
- Klik Buat. File JSON yang berisi kunci Anda {i>download<i} ke komputer Anda.
Memanggil API
Pilih opsi dari tab di bawah:
HTTP
Home Graph menyediakan endpoint HTTP
- Menggunakan file JSON akun layanan yang didownload untuk membuat Web JSON Token (JWT). Untuk informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
- Dapatkan token akses OAuth 2.0 dengan
https://www.googleapis.com/auth/homegraph
cakupan menggunakan oauth2l: - Buat permintaan JSON dengan
agentUserId
. Berikut adalah contoh permintaan JSON untuk Status Laporan dan Notifikasi: - Gabungkan Status Laporan dan JSON Notifikasi serta token di HTTP POST Anda
ke endpoint Google Home Graph. Berikut adalah contoh
untuk membuat permintaan di command line menggunakan
curl
, seperti pengujian:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
Home Graph menyediakan endpoint gRPC
- Dapatkan definisi layanan buffering protokol untuk Home Graph API.
- Ikuti dokumentasi developer gRPC guna membuat stub klien untuk salah satu bahasa yang didukung.
- Panggil metode ReportStateAndNotification.
Node.js
Klien Node.js Google API menyediakan binding untuk Home Graph API.
- Lakukan inisialisasi layanan
google.homegraph
menggunakan Application Default Credentials. - Panggil metode
reportStateAndNotification
dengan ReportStateAndNotificationRequest. Metode ini menampilkanPromise
dengan ReportStateAndNotificationResponse.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.reportStateAndNotification({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
Java
HomeGraph API Client Library for Java menyediakan binding untuk Home Graph API.
- Lakukan inisialisasi
HomeGraphApiService
menggunakan Application Default Credentials. - Panggil metode
reportStateAndNotification
denganReportStateAndNotificationRequest
. Metode ini akan menampilkanReportStateAndNotificationResponse
.
// 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(); // Build device state payload. Map<?, ?> states = Map.of("on", true); // Report device state. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states)))); homegraphService.devices().reportStateAndNotification(request); }
Status Laporan Pengujian
Agar tindakan Anda siap untuk sertifikasi, penting untuk melakukan pengujian Report State.
Untuk melakukannya, sebaiknya gunakan alat Viewer Home Graph, yang merupakan aplikasi web mandiri yang tidak memerlukan download atau deployment.
Dasbor Report State masih tersedia, tetapi tidak digunakan lagi dan tidak didukung lagi.
Dasbor Status Laporan
Prasyarat
Agar dapat menguji tindakan, Anda memerlukan Akun Layanan
Key dan agentUserId
Anda. Jika Anda sudah memiliki Kunci Akun Layanan dan
agentUserId
lihat Men-deploy Report State
Dasbor.
Men-deploy dasbor Status Laporan
Setelah memiliki Kunci Akun Layanan dan ID Pengguna Agen untuk project Anda,
download dan deploy versi terbaru dari
Report State
Dasbor.
Setelah mengunduh versi terbaru, ikuti petunjuk dari
file README.MD
disertakan.
Setelah Anda men-deploy dasbor Report State, akses dasbor dari URL berikut (ganti your_project_id dengan ID project):
http://<your-project-id>.appspot.com
Di dasbor, lakukan hal berikut:
- Pilih File Kunci Akun Anda
- Menambahkan agentUserId Anda
Lalu klik Daftar.
Semua perangkat Anda tercantum. Setelah daftar diisi, Anda dapat menggunakan Tombol Refresh untuk memperbarui status perangkat. Jika ada perubahan status perangkat, baris akan disorot dengan warna hijau.
Respons Error
Anda mungkin menerima salah satu respons error berikut saat menelepon Report State. Respons ini tersedia dalam bentuk status HTTP kode program.
400 Bad Request
- Server tidak dapat memproses permintaan yang dikirim oleh klien karena sintaksis tidak valid. Penyebab umum sertakan format JSON yang salah atau gunakannull
dan bukan "" untuk nilai {i>string<i}.404 Not Found
- Resource yang diminta tidak mungkin ditemukan, tetapi mungkin tersedia di masa mendatang. Biasanya, ini berarti bahwa kita tidak bisa menemukan perangkat yang diminta. Ini juga bisa berarti bahwa akun pengguna tidak ditautkan dengan Google atau kami menerimaagentUserId
yang tidak valid. Pastikan bahwaagentUserId
cocok dengan nilai yang diberikan di SYNC respons, dan Anda sudah menangani intent DISCONNECT.