Status Laporan

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

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

Tanpa Report State, mengingat lampu dari beberapa penyedia di ruang keluarga, perintah Ok Google, cerahkan ruang keluarga saya memerlukan penyelesaian beberapa maksud 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 memerlukan perjalanan pulang-pergi ke perangkat.

Setelah SYNC awal untuk perangkat, platform 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 yang lengkap untuk sifat tertentu. Home Graph memperbarui status berdasarkan per-trait dan menggantikan semua data untuk trait tersebut saat panggilan Report State dilakukan. Misalnya, jika Anda melaporkan status untuk trait StartStop, payload harus menyertakan nilai untuk isRunning dan isPaused.

Mulai

Untuk menerapkan Report State, ikuti langkah-langkah berikut:

• Aktifkan Google HomeGraph API
• Membuat Kunci Akun Layanan
• Panggil API

Aktifkan Google HomeGraph API

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

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

Membuat Kunci Akun Layanan

Ikuti petunjuk ini untuk membuat kunci akun layanan dari Google Cloud Console:

1. Di Google Cloud Console, buka halaman Service accounts.

   Buka halaman Service Accounts.

   Anda mungkin perlu memilih project sebelum diarahkan ke halaman Akun Layanan.

2. Klik addBuat akun layanan.

3. Di kolom Nama akun layanan, masukkan nama.

4. Di kolom Service account ID, masukkan ID.

5. Di kolom Deskripsi akun layanan, masukkan sebuah deskripsi.

6. Klik Buat dan lanjutkan.

7. Dari dropdown Peran, pilih Akun Layanan > Pembuat Token OpenID Connect Identity pada Akun Layanan.

8. Klik Lanjutkan.

9. Klik Selesai.

10. Pilih akun layanan yang baru saja Anda buat dari daftar akun layanan dan pilih Kelola kunci dari menu more_vert Tindakan.

11. Pilih Tambahkan kunci > Buat kunci baru.

12. Untuk Jenis kunci, pilih opsi JSON.

13. Klik Buat. File JSON yang berisi kunci Anda akan 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);
}
    

Menguji Status Laporan

Agar integrasi Cloud-to-cloud 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 sudah tidak digunakan lagi dan tidak didukung lagi.

Dasbor Status Laporan

Prasyarat

Sebelum dapat menguji integrasi Cloud-to-cloud, 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 Report State

Setelah Anda memiliki Kunci Akun Layanan dan ID Pengguna Agen untuk project Anda, download dan deploy versi terbaru dari Dasbor Report State. Setelah mendownload versi terbaru, ikuti petunjuk dari file README.MD yang disertakan.

Setelah 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 hal berikut:

• Pilih File Kunci Akun Anda
• Tambahkan agentUserId Anda

Kemudian, klik Daftar.

Semua perangkat Anda dicantumkan. Setelah daftar diisi, Anda dapat menggunakan tombol Muat Ulang untuk memperbarui status perangkat. Jika ada perubahan status perangkat, baris akan ditandai dengan warna hijau.

Perbedaan Status Laporan

Akurasi status laporan berbasis kueri mengukur seberapa baik status laporan terbaru untuk perangkat cocok dengan status perangkat saat pengguna membuat kueri untuknya. Nilai ini diharapkan berada pada 99,5%.

Respons Error

Anda mungkin menerima salah satu respons error berikut saat memanggil Report State. 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 menggunakan null, bukan "" untuk nilai string.
• 404 Not Found - Resource yang diminta tidak dapat ditemukan, tetapi mungkin tersedia pada masa mendatang. Biasanya, hal ini berarti 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 bahwa agentUserId cocok dengan nilai yang diberikan dalam respons SYNC, dan Anda menangani intent DISCONNECT dengan benar.

Pelaporan status online dan offline

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }