Akıllı ev işlemlerinin nasıl geliştirileceğini öğrenebileceğiniz yeni adres olan Google Home Geliştirici Merkezi'ne hoş geldiniz. Not: Actions Console'da işlem derlemeye devam edersiniz.

Rapor Durumu

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

Report State, belirtilen agentUserId öğesini içeren kullanıcı cihazlarının durumunu Google'a bildirir (orijinal SYNC isteğinde gönderilir). Google Assistant, bir cihazın mevcut durumunu anlamayı gerektiren bir işlem yapmak istediğinde EXECUTE niyetini yayınlamadan önce çeşitli üçüncü taraf bulutlarına QUERY niyeti vermek yerine Home Graph içindeki durum bilgilerini arar.

Oturma odasında birden fazla sağlayıcının ışıkları Report State olmadan Ok Google, oturma odamın parlaklığını artır komutu, daha önce bildirilenlere göre mevcut parlaklık değerlerini aramak yerine, birden çok buluta gönderilen birden fazla QUERY amacını çözümlemeyi gerektirir. En iyi kullanıcı deneyimi için Assistant uygulamasına geri dönmeden cihazın mevcut durumunu belirtmelidir.

Platform, bir cihazın ilk SYNC izlerinden sonra, Home Graph alanlarını doldurmak için cihazın durumunu toplayan bir QUERY niyeti gönderir. Bu noktadan sonra Home Graph yalnızca Report State ile gönderilen durumu depolar.

Report State çağırırken belirli bir özellik için eksiksiz durum verileri sağladığınızdan emin olun. Home Graph, özellikleri özellik bazında günceller ve Report State çağrıldığında bu özelliğe ait tüm verilerin üzerine yazar. Örneğin, StartStop özelliği için durum bildiriyorsanız yükün hem isRunning hem de isPaused değerlerini içermesi gerekir.

Başlayın

Report State uygulamak için aşağıdaki adımları izleyin:

Google HomeGraph API'yi etkinleştirme

  1. Google Cloud Console içinde 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 üzerinden hizmet hesabı anahtarı oluşturmak için aşağıdaki talimatları uygulayın:

Not: Bu adımları gerçekleştirirken doğru GCP projesini kullandığınızdan emin olun. Bu proje, smart home proje kimliğinizle eşleşiyor.
  1. Google Cloud Console bölümünde Hizmet hesabı anahtarı oluştur sayfasına gidin.

    Hizmet Hesabı Anahtarı Oluştur sayfasına git
  2. Hizmet hesabı listesinden Yeni hizmet hesabı'nı seçin.
  3. Service account name (Hizmet hesabı adı) alanına bir ad girin.
  4. Service account ID (Hizmet hesabı kimliği) alanına bir kimlik girin.
  5. Rol listesinden Hizmet Hesapları > Hizmet Hesabı Jeton Oluşturucu'yu seçin.

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

  7. Create'i (Oluştur) tıklayın. Anahtar indirmelerinizi içeren bir JSON dosyası bilgisayarınıza indirilir.

API'yi çağırma

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

HTTP

Home Graph, bir HTTP uç noktası sağlar

  1. İndirilen hizmet hesabı JSON dosyasını kullanarak bir JSON Web Token (JWT) oluşturun. Daha fazla bilgi için Hizmet Hesabı Kullanarak Kimlik Doğrulama bölümüne bakın.
  2. oauth2l kullanarak https://www.googleapis.com/auth/homegraph kapsamıyla bir OAuth 2.0 erişim jetonu edinin:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId ile JSON isteği oluşturun. Rapor Durumu ve Bildirim için örnek bir JSON isteğini burada bulabilirsiniz:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Rapor Durumu, Bildirim JSON ve jetonu, HTTP POST isteğinizdeki Google Home Graph uç noktasıyla birleştirin. Aşağıda, test olarak curl öğesini kullanarak komut satırında nasıl istekte bulunulacağına dair bir örnek verilmiştir:
  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, bir gRPC uç noktası sağlar

  1. Home Graph API için protokol arabellek hizmet tanımını alın.
  2. Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici belgelerini uygulayın.
  3. ReportStateAndNotification yöntemini çağırın.

Node.js

Google API'leri Node.js İstemcisi, Home Graph API'si için bağlamalar sağlar.

  1. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak google.homegraph hizmetini başlatın.
  2. ReportStateAndNotificationRequest ile reportStateAndNotification yöntemini çağırın. ReportStateAndNotificationResponse ile bir Promise döndürür.
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

Java için HomeGraph API İstemci Kitaplığı, Home Graph API için bağlamalar sağlar.

  1. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak HomeGraphApiService'i başlatın.
  2. ReportStateAndNotificationRequest ile reportStateAndNotification yöntemini çağırın. ReportStateAndNotificationResponse değerini döndürür.
  // 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 Durumunu Test Et

Bu görev için önerilen araçlar

İşleminizi sertifika almaya hazır hale getirmek için Report State hizmetini test etmeniz önemlidir.

Bunun için indirme veya dağıtım 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ılmıştır ve artık desteklenmemektedir.

Rapor Durumu Kontrol Paneli

Ön koşullar

İşleminizi test edebilmek için Hizmet Hesabı Anahtarınıza ve agentUserId anahtarınıza ihtiyacınız vardır. Zaten Hizmet Hesabı Anahtarınız varsa agentUserId ve Report State Kontrol Panelini Dağıtma bölümüne bakın.

Rapor Durumu kontrol panelini dağıtma

Projeniz için Hizmet Hesabı Anahtarı ve Aracı Kullanıcı Kimliği olduğunda Report State Kontrol Paneli'nden en son sürümü indirip dağıtın. En son sürümü indirdikten sonra, eklenen README.MD dosyasındaki talimatları uygulayın.

Report State kontrol panelini dağıttıktan sonra, aşağıdaki URL'den kontrol paneline erişin (proje_kimliğinizi proje kimliğinizle değiştirin):

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

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

  • Hesap Anahtarı Dosyanızı Seçin
  • TemsilciUserId'nizi ekleyin

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

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

Hata Yanıtları

Report State yöntemini çağırırken 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, bozuk JSON veya bir dize değeri için "" yerine null kullanılması sayılabilir.
  • 404 Not Found: İstenen kaynak bulunamadı ancak ileride kullanılabilir. Genellikle bu, istenen cihazı bulamadığımız anlamına gelir. Bu, kullanıcı hesabının Google'a bağlı olmadığı veya geçersiz bir agentUserId aldığımız da anlamına gelebilir. agentUserId öğesinin SYNC yanıtınızda sağlanan değerle eşleştiğinden ve DISCONNECT niyetlerini doğru şekilde işlediğinizden emin olun.