Report State adalah fitur penting yang memungkinkan
Tindakan Home secara proaktif melaporkan status terbaru
perangkat pengguna kembali ke
Google Home Graph
rather than waiting for a
QUERY
intent.
Report State melaporkan status perangkat pengguna ke Google
dengan agentUserId
yang ditentukan yang terkait dengannya (dikirim dalam permintaan
SYNC
asli). Kapan
Google Assistant
wants to take an action
that requires understanding the current state of a device, it can simply look
up the state information in the
Home Graph instead
of issuing a QUERY
intent to various third-party clouds prior to issuing the
EXECUTE
intent.
Tanpa
Report State, dengan lampu dari beberapa penyedia di
ruang keluarga, perintah Ok Google, cerahkan ruang keluarga saya memerlukan
penyelesaian beberapa intent QUERY
yang dikirim ke beberapa cloud, bukan
hanya mencari nilai kecerahan saat ini berdasarkan apa yang
telah dilaporkan sebelumnya. Untuk pengalaman pengguna terbaik,
Assistant harus memiliki status perangkat saat ini,
tanpa perlu bolak-balik ke perangkat.
Setelah SYNC
awal untuk suatu perangkat, platform akan mengirimkan 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 untuk memberikan data status
lengkap untuk karakteristik tertentu.
Home Graph memperbarui status per
fitur dan menimpa semua data untuk karakteristik tersebut saat
panggilan Report State dilakukan. Misalnya, jika Anda melaporkan
status untuk fitur StartStop, payload
perlu menyertakan nilai untuk isRunning
dan isPaused
.
Memulai
Untuk menerapkan Report State, ikuti langkah-langkah berikut:
Mengaktifkan Google HomeGraph API
-
Di Google Cloud Console , go to the HomeGraph API page.
Buka halaman HomeGraph API - Pilih project yang cocok dengan smart home project ID.
- Klik AKTIFKAN.
Membuat Kunci Akun Layanan
Ikuti petunjuk berikut untuk membuat kunci akun layanan dari Google Cloud Console:
-
Di halaman Google Cloud Console, buka halaman Create service account key.
Buka halaman Create Service Account Key - Dari daftar Akun layanan, 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.
Untuk Key type, pilih opsi JSON.
- Klik Create. File JSON yang berisi kunci yang didownload ke komputer Anda.
Memanggil API
Pilih opsi dari tab di bawah:
HTTP
Home Graph menyediakan endpoint HTTP
- Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk 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 Status Laporan dan Notifikasi: - Menggabungkan Status Laporan dan JSON Notifikasi serta token dalam permintaan POST HTTP 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
{ "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 untuk 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 Kredensial Default Aplikasi. - 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
Library Klien HomeGraph API untuk Java menyediakan binding untuk Home Graph API.
- Lakukan inisialisasi
HomeGraphApiService
menggunakan Kredensial Default Aplikasi. - Panggil metode
reportStateAndNotification
denganReportStateAndNotificationRequest
. Tindakan 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 menguji Report State.
Untuk melakukannya, sebaiknya gunakan alat Penampil 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
Sebelum dapat menguji tindakan, Anda memerlukan Kunci Akun
Layanan dan agentUserId
. Jika Anda sudah memiliki Kunci Akun Layanan dan agentUserId
lihat Men-deploy Dasbor Report State.
Men-deploy dasbor Status Laporan
Setelah Anda memiliki Kunci Akun Layanan dan ID Pengguna Agen untuk project Anda,
download dan deploy versi terbaru dari
Report State
Dasbor.
Setelah Anda mendownload versi terbaru, ikuti petunjuk dari
file README.MD
yang disertakan.
Setelah Anda men-deploy dasbor Report State, akses dasbor dari URL berikut (ganti your_project_id dengan project ID Anda):
http://<your-project-id>.appspot.com
Di dasbor, lakukan tindakan berikut:
- Pilih File Kunci Akun Anda
- Menambahkan agentUserId
Lalu, klik List.
Semua perangkat Anda tercantum. Setelah daftar diisi, Anda dapat menggunakan tombol Refresh untuk memperbarui status perangkat. Jika ada perubahan status perangkat, baris akan ditandai dengan warna hijau.
Respons Error
Anda mungkin menerima salah satu respons error berikut saat memanggil Report State. Respons ini tersedia dalam bentuk kode status HTTP.
400 Bad Request
- Server tidak dapat memproses permintaan yang dikirim oleh klien karena sintaksis tidak valid. Penyebab umum meliputi format JSON yang salah atau menggunakannull
, bukan "" untuk nilai string.404 Not Found
- Resource yang diminta tidak dapat ditemukan, tetapi mungkin tersedia di masa mendatang. Biasanya, ini berarti bahwa kami tidak dapat menemukan perangkat yang diminta. Hal ini juga dapat berarti bahwa akun pengguna tidak ditautkan dengan Google atau kami menerimaagentUserId
yang tidak valid. PastikanagentUserId
cocok dengan nilai yang diberikan dalam respons SYNC, dan Anda menangani intent DISCONNECT dengan benar.