Status Laporan

Report State adalah fitur penting yang memungkinkan Action Google 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 tentang status perangkat saat ini, dapat mencari informasi status di Home Graph, bukan mengeluarkan intent QUERY ke berbagai cloud pihak ketiga sebelum mengeluarkan intent EXECUTE.

Tanpa Report State, jika ada lampu dari beberapa penyedia di ruang keluarga, perintah Ok Google, terangkan ruang keluarga saya memerlukan penyelesaian beberapa intent QUERY yang dikirim ke beberapa cloud, bukan sekadar mencari nilai kecerahan saat ini berdasarkan apa yang telah dilaporkan sebelumnya. Untuk memberikan pengalaman pengguna terbaik, Assistant harus memiliki status perangkat saat ini, tanpa memerlukan perjalanan bolak-balik ke perangkat.

Setelah SYNC awal untuk 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 karakteristik dan menimpa semua data untuk karakteristik tersebut saat panggilan Report State dilakukan. Misalnya, jika Anda melaporkan status untuk karakteristik StartStop, payload harus 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 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 berikut 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 Service Accounts.

2. Klik addCreate service account.

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 Role, pilih Service Accounts > Service Account OpenID Connect Identity Token Creator.

8. Klik Lanjutkan.

9. Klik Selesai.

10. Pilih akun layanan yang baru saja Anda buat dari daftar akun layanan, lalu pilih Manage keys dari menu more_vert Actions.

11. Pilih Add key > Create new key.

12. Untuk Key type, pilih opsi JSON.

13. Klik Buat. File JSON yang berisi kunci Anda akan didownload ke komputer.

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).execute();
}
    

Negara Bagian Laporan Pengujian

Agar integrasi Cloud-to-cloud Anda siap untuk disertifikasi, penting untuk menguji Report State.

Untuk melakukannya, sebaiknya gunakan alat Home Graph Viewer, 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 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 tindakan berikut:

• Pilih File Kunci Akun Anda
• Menambahkan agentUserId Anda

Kemudian, 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.

Perbedaan Status Laporan

Akurasi status laporan berbasis kueri mengukur seberapa baik status laporan terbaru untuk perangkat cocok dengan status perangkat saat pengguna mengkuerinya. Nilai ini diperkirakan sebesar 99,5%. Untuk mengetahui detail selengkapnya tentang status Akurasi Status Laporan project Anda saat ini, lihat Kesehatan Perangkat - Akurasi status. Anda juga dapat melihat detail Log Perbedaan Status Laporan dari Logs Explorer.

Berikut adalah contoh Log Perbedaan Status Laporan:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Definisi kolom Log Perbedaan Status Laporan

Respons Error

Anda mungkin menerima salah satu respons error berikut saat memanggil Report State. Respons ini diberikan dalam bentuk kode status HTTP.

400 Bad Request (400 Permintaan Tidak Valid)

Server tidak dapat memproses permintaan yang dikirim oleh klien karena sintaksis yang tidak valid. Penyebab umum mencakup JSON yang salah format atau penggunaan null, bukan "" untuk nilai string.

404 Tidak Ditemukan

Resource yang diminta tidak dapat ditemukan, tetapi mungkin tersedia pada masa mendatang. Biasanya, 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 agentUserId cocok dengan nilai yang diberikan dalam respons SYNC, dan Anda menangani intent DISCONNECT dengan benar.

Jika panggilan ReportState gagal dengan error 404 NOT_FOUND, hal ini menunjukkan ketidakcocokan sinkronisasi antara cloud Anda dan Home Graph. Hal ini dapat terjadi jika perangkat dihapus dari Home Graph, atau jika pengguna membatalkan tautan akunnya.

Untuk menangani error 404 dari Report State, gunakan prosedur berikut:

1. Periksa status akun pengguna: Panggil devices.sync untuk agentUserId yang menampilkan error 404. Tindakan ini membantu menentukan apakah error terjadi untuk seluruh akun pengguna atau perangkat tertentu.
   • Jika SYNC menampilkan error 404, akun pengguna tidak lagi ditautkan dengan Google. Berhenti mengirim Report State dan Request Sync untuk perangkat pengguna ini.
   • Jika SYNC menampilkan 200 OK, akun pengguna masih ditautkan, yang berarti error 404 bersifat spesifik per perangkat.
2. Rekonsiliasi daftar perangkat: Jika SYNC menampilkan 200 OK, Anda perlu mengidentifikasi perangkat mana yang tidak lagi dikenali oleh Google. Sebaiknya Anda membandingkan daftar perangkat yang dimiliki Google untuk pengguna dengan database perangkat Anda, dan mengidentifikasi perangkat di sistem Anda yang tidak ada dalam daftar Google. Jika perangkat harus disinkronkan ke Google, tetapi belum dibagikan ke Google, gunakan SYNC untuk memastikan perangkat disinkronkan dengan Google. Jika perangkat harus dibatalkan tautannya dari Google, hentikan pelaporan status untuk perangkat tertentu tersebut dan lanjutkan pelaporan untuk perangkat valid lainnya di bagian agentUserId tersebut.

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": {},
        }
      }
    }