Laporkan State

Report State adalah fitur penting yang memungkinkan Tindakan Home secara proaktif melaporkan status terbaru perangkat pengguna kembali ke Google Home Graph, bukan menunggu intent QUERY.

Report State melaporkan status perangkat pengguna ke Google dengan agentUserId yang ditentukan yang terkait dengannya (dikirim dalam permintaan SYNC asli). Saat Google Assistant ingin melakukan tindakan yang memerlukan pemahaman status perangkat saat ini, pengguna hanya dapat mencari informasi status di Home Graph, bukan mengirimkan intent QUERY ke berbagai cloud pihak ketiga sebelum mengeluarkan intent EXECUTE.

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 dibuat. Misalnya, jika Anda melaporkan status untuk fitur StartStop, payload perlu menyertakan nilai untuk isRunning dan isPaused.

Mulai

Untuk menerapkan Report State, ikuti langkah-langkah berikut:

• Mengaktifkan Google HomeGraph API
• Membuat Kunci Akun Layanan
• Memanggil API

Mengaktifkan Google HomeGraph API

1. Di Google Cloud Platform Console, buka halaman HomeGraph API.

   Buka halaman HomeGraph API
2. Pilih project yang cocok dengan project ID smart home Anda.
3. Klik AKTIFKAN.

Membuat Kunci Akun Layanan

Ikuti petunjuk berikut untuk membuat kunci akun layanan dari GCP Console:

1. Di GCP Console, buka halaman Create service account key.

   Buka halaman Create Service Account Key
2. Dari daftar Akun layanan, pilih Akun layanan baru.
3. Di kolom Nama akun layanan, masukkan nama.
4. Di kolom ID akun layanan, masukkan ID.

5. Dari daftar Role, pilih Service Accounts > Service Account Token Creator.

6. Untuk Key type, pilih opsi JSON.

7. Klik Create. File JSON yang berisi kunci yang didownload ke komputer Anda.

Memanggil API

Pilih opsi dari tab di bawah:

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
          }
        }
      }
    }
  }
});
    

  // 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.

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 Service Account Key dan Agent User ID untuk project Anda, download dan deploy versi terbaru dari Report State Dashboard. 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 menggunakan null, 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 menerima agentUserId yang tidak valid. Pastikan agentUserId cocok dengan nilai yang diberikan dalam respons SYNC, dan Anda menangani intent DISCONNECT dengan benar.