Selamat datang di Pusat Developer Google Home, tujuan baru untuk mempelajari cara mengembangkan tindakan smart home. Catatan: Anda akan terus membuat tindakan di konsol Actions.

Laporkan State

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.
atau

Status Laporan adalah fitur penting yang memungkinkan Action smart home secara proaktif melaporkan status terbaru perangkat pengguna kembali ke Home Graph Google, bukan menunggu intent QUERY.

Melaporkan laporan Status ke Google tentang status perangkat pengguna dengan agentUserId yang ditentukan yang terkait dengannya (dikirim dalam permintaan SYNC asli). Saat ingin melakukan tindakan yang memerlukan pemahaman status perangkat saat ini, Asisten Google dapat langsung mencari informasi status di Grafik Beranda, bukan mengeluarkan intent QUERY ke berbagai cloud pihak ketiga sebelum mengeluarkan intent EXECUTE.

Tanpa Status Laporan, dengan mempertimbangkan terang dari beberapa penyedia di ruang keluarga, perintah Ok Google, mencerahkan 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, Asisten Google harus memiliki status perangkat saat ini, tanpa memerlukan perjalanan pulang pergi ke perangkat.

Setelah SYNC awal untuk perangkat, platform akan mengirimkan intent QUERY yang mengumpulkan status perangkat untuk mengisi Home Graph. Setelah itu, Grafik Rumah hanya menyimpan status yang dikirim dengan Status Laporan.

Saat memanggil Status Laporan, pastikan Anda memberikan data status lengkap untuk karakteristik tertentu. Update Home Graph menampilkan status per sifat dan menimpa semua data untuk karakteristik tersebut saat panggilan Status Laporan dilakukan. Misalnya, jika Anda melaporkan status untuk fitur StartStop, payload harus menyertakan nilai untuk isRunning dan isPaused.

Mulai

Untuk menerapkan Status Laporan, ikuti langkah-langkah berikut:

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:

Catatan: Pastikan Anda menggunakan project GCP yang benar saat melakukan langkah-langkah ini. Ini adalah project yang cocok dengan project ID smart home Anda.
  1. Di GCP Console, buka halaman Buat kunci akun layanan.

    Buka halaman Buat Kunci Akun Layanan
  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 Buat. File JSON yang berisi download kunci Anda ke komputer.

Memanggil API

Pilih salah satu opsi dari tab di bawah:

HTTP

Home Graph API menyediakan endpoint HTTP

  1. Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
  2. Dapatkan token akses OAuth 2.0 dengan cakupan https://www.googleapis.com/auth/homegraph menggunakan oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Buat permintaan JSON dengan agentUserId. Berikut adalah contoh permintaan JSON untuk Status Laporan dan Notifikasi:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Gabungkan 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:
  7. 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 API menyediakan endpoint gRPC

  1. Dapatkan definisi layanan buffering protokol untuk Home Graph API.
  2. Ikuti dokumentasi developer gRPC untuk membuat stub klien untuk salah satu bahasa yang didukung.
  3. Panggil metode ReportStateAndNotification.

Node.js

Klien Node.js Google API menyediakan binding untuk Home Graph API.

  1. Inisialisasi layanan google.homegraph menggunakan Kredensial Default Aplikasi.
  2. Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Metode ini akan menampilkan Promise 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.

  1. Lakukan inisialisasi HomeGraphApiService menggunakan Kredensial Default Aplikasi.
  2. Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Tindakan ini akan menampilkan ReportStateAndNotificationResponse.
  // 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 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 Status Laporan.

Men-deploy dasbor Status Laporan

Setelah Anda memiliki Service Account Key dan agentUserId untuk project, 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 Status Laporan, 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 agenUserId

Lalu, klik Daftar.

Semua perangkat Anda tercantum. Setelah daftar terisi, 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 ditampilkan dalam bentuk kode status HTTP.

  • 400 Bad Request - Server tidak dapat memproses permintaan yang dikirim oleh klien karena sintaksis tidak valid. Penyebab umum termasuk 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 kita tidak dapat menemukan perangkat yang diminta. Hal ini juga dapat berarti bahwa akun pengguna tidak tertaut 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.