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.

Minta Sinkronisasi

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

Permintaan Sinkronisasi memicu permintaan SYNC ke fulfillment Anda untuk setiap pengguna Google dengan perangkat yang memiliki agentUserId yang ditentukan yang terkait dengannya (yang Anda kirim dalam permintaan SINKRONISASI asli). Dengan begitu, Anda dapat mengupdate perangkat pengguna tanpa membatalkan tautan dan menautkan ulang akun mereka. Semua pengguna yang tertaut ke ID ini akan menerima permintaan SYNC.

Anda harus memicu permintaan SYNC:

  • Jika pengguna menambahkan perangkat baru.
  • Jika pengguna menghapus perangkat yang ada.
  • Jika pengguna mengganti nama perangkat yang ada.
  • Jika Anda mengimplementasikan jenis perangkat baru, fitur, atau menambahkan fitur perangkat baru.

Mulai

Untuk menerapkan Request Sync, 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

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 Request Sync:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Gabungkan Request Sync JSON dan token dalam permintaan HTTP POST 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:requestSync"
    

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

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 requestSync dengan RequestSyncDevicesRequest. Metode ini akan menampilkan Promise dengan RequestSyncDevicesResponse kosong.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.requestSync({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    async: false
  }
});
    

Java

Library Klien HomeGraph API untuk Java menyediakan binding untuk Home Graph API.

  1. Lakukan inisialisasi HomeGraphApiService menggunakan Kredensial Default Aplikasi.
  2. Panggil metode requestSync dengan RequestSyncDevicesRequest. Tindakan ini akan menampilkan ReportStateAndNotificationResponse kosong.
// 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();

// Request sync.
RequestSyncDevicesRequest request =
    new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false);
homegraphService.devices().requestSync(request);
    

Respons error

Anda mungkin menerima salah satu respons error berikut saat memanggil Request Sync. 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.
  • 403 Forbidden - Server tidak dapat memproses permintaan untuk agentUserId yang diberikan karena terjadi error saat memperbarui token. Pastikan endpoint OAuth Anda merespons dengan benar untuk memperbarui permintaan token dan memeriksa status penautan akun pengguna.
  • 404 Not Found - Resource yang diminta tidak dapat ditemukan, tetapi mungkin tersedia di masa mendatang. Biasanya, ini berarti 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.
  • 429 Too Many Requests - Jumlah maksimum permintaan sinkronisasi serentak telah terlampaui untuk agentUserId tertentu. Pemanggil hanya dapat mengeluarkan satu permintaan sinkronisasi serentak kecuali jika flag async ditetapkan ke true.