Rapor Durumu

Report State, Google Home işleminin QUERY intent'i beklemek yerine kullanıcının cihazının son durumunu proaktif olarak Google Home Graph'ye bildirmesini sağlayan önemli bir özelliktir.

Report State, kullanıcı cihazlarının durumlarını Google'a bildirir. Bu cihazlarla ilişkili belirtilen agentUserId (orijinal SYNC isteğinde gönderilir) de bildirilir. Google Assistant, bir cihazın mevcut durumunu anlama gerektiren bir işlem yapmak istediğinde EXECUTE intent'ini göndermeden önce çeşitli üçüncü taraf bulutlarına QUERY intent göndermek yerine Home Graph'te durum bilgilerini arayabilir.

Report State olmadan, bir oturma odasında birden fazla sağlayıcıdan ışık verildiğinde Ok Google, oturma odamın ışığını aç komutu, daha önce bildirilenlere göre mevcut parlaklık değerlerini aramak yerine birden fazla buluta gönderilen birden fazla QUERY intent'inin çözülmesini gerektirir. En iyi kullanıcı deneyimi için Assistant'ün, cihaza gidip gelme gerektirmeden cihazın mevcut durumunu bilmesi gerekir.

Bir cihaz için ilk SYNC'ten sonra platform, Home Graph'yi doldurmak üzere cihazın durumunu toplayan bir QUERY intent'i gönderir. Bu noktadan sonra Home Graph yalnızca Report State ile gönderilen durumu depolar.

Report State işlevini çağırırken belirli bir özellik için eksiksiz durum verileri sağladığınızdan emin olun. Home Graph, durumları özellik bazında günceller ve Report State çağrısı yapıldığında ilgili özelliğin tüm verilerinin üzerine yazar. Örneğin, StartStop özelliğinin durumunu bildiriyorsanız yükün hem isRunning hem de isPaused değerlerini içermesi gerekir.

Başlayın

Report State özelliğini uygulamak için aşağıdaki adımları uygulayın:

• Google HomeGraph API'yi etkinleştirme
• Hizmet Hesabı Anahtarı Oluşturma
• API'yi çağırma

Google HomeGraph API'yi etkinleştirme

1. Google Cloud Console sayfasında HomeGraph API sayfasına gidin.

   HomeGraph API sayfasına gidin.
2. smart home proje kimliğinizle eşleşen projeyi seçin.
3. ETKİNLEŞTİR'i tıklayın.

Hizmet Hesabı Anahtarı Oluşturma

Google Cloud Console'ten hizmet hesabı anahtarı oluşturmak için aşağıdaki talimatları uygulayın:

1. Google Cloud Console'te Hizmet hesabı anahtarı oluştur sayfasına gidin.

   Hizmet Hesabı Anahtarı Oluştur sayfasına gidin.
2. Hizmet hesabı listesinden Yeni hizmet hesabı'nı seçin.
3. Hizmet hesabı adı alanına bir ad girin.
4. Hizmet hesabı kimliği alanına bir kimlik girin.

5. Rol listesinde Hizmet Hesapları > Hizmet Hesabı Jetonu Oluşturucusu'nu seçin.

6. Anahtar türü için JSON seçeneğini belirleyin.

7. Oluştur'u tıklayın. Anahtarınızı içeren bir JSON dosyası bilgisayarınıza indirilir.

API'yi çağırma

Aşağıdaki sekmelerden bir seçenek belirleyin:

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

Test raporu durumu

Cloud-to-cloud entegrasyonunuzu sertifika almaya hazır hale getirmek için Report State'yi test etmeniz önemlidir.

Bunu yapmak için indirme veya dağıtma gerektirmeyen bağımsız bir web uygulaması olan Home Graph Görüntüleyici aracını kullanmanızı öneririz.

Report State kontrol paneli hâlâ kullanılabilir ancak kullanımdan kaldırıldığı için artık desteklenmemektedir.

Rapor Durumu Kontrol Paneli

Ön koşullar

Cloud-to-cloud entegrasyonunuzu test edebilmek için Hizmet Hesabı Anahtarınız ve agentUserId'ınız olmalıdır. Hizmet Hesabı Anahtarınız ve agentUserId varsa Report State Kontrol Paneli'ni dağıtma başlıklı makaleyi inceleyin.

Rapor Durumu kontrol panelini dağıtma

Projeniz için hizmet hesabı anahtarını ve temsilci kullanıcı kimliğini aldıktan sonra Report State Kontrol panelinden en son sürümü indirip dağıtın. En son sürümü indirdikten sonra, ekteki README.MD dosyasında yer alan talimatları uygulayın.

Report State kontrol panelini dağıttıktan sonra aşağıdaki URL'den kontrol paneline erişin (your_project_id yerine proje kimliğinizi yazın):

http://<your-project-id>.appspot.com

Kontrol panelinde aşağıdakileri yapın:

• Hesap Anahtarı Dosyanızı Seçin
• agentUserId değerinizi ekleyin

Ardından Liste'yi tıklayın.

Tüm cihazlarınız listelenir. Liste doldurulduktan sonra cihaz durumlarını güncellemek için Yenile düğmesini kullanabilirsiniz. Cihaz durumunda değişiklik varsa satır yeşil renkle vurgulanır.

Hata Yanıtları

Report State çağrısı yaparken aşağıdaki hata yanıtlarından birini alabilirsiniz. Bu yanıtlar HTTP durum kodları biçimindedir.

• 400 Bad Request: Sunucu, geçersiz söz dizimi nedeniyle istemci tarafından gönderilen isteği işleyemedi. Yaygın nedenler arasında hatalı biçimlendirilmiş JSON veya dize değeri için "" yerine null kullanılması yer alır.
• 404 Not Found: İstenen kaynak bulunamadı ancak gelecekte kullanılabilir. Bu genellikle istenen cihazı bulamadığımız anlamına gelir. Bu durum, kullanıcı hesabının Google'a bağlı olmadığı veya geçersiz bir agentUserId aldığımız anlamına da gelebilir. agentUserId değerinin, SYNC yanıtınızda sağlanan değerle eşleştiğinden ve DISCONNECT intent'lerini doğru şekilde işlediğinizden emin olun.