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

Rapor Durumu

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Rapor Durumu, akıllı ev işleminin, QUERY niyetini beklemek yerine kullanıcının cihazının son durumunu proaktif olarak Google'ın Ana Sayfasına bildirmesini sağlayan önemli bir özelliktir.

Durum Raporu, Google'ın ilişkilendirilmiş agentUserId cihazıyla ilişkili durumlarını (orijinal SYNC isteğinde gönderilir) Google'a bildirir. Google Asistan, bir cihazın geçerli durumunu anlamayı gerektiren bir işlem yapmak istediğinde, EXECUTE amacını göndermeden önce çeşitli üçüncü taraf bulutlara QUERY niyetini iletmek yerine Ana Grafik'teki durum bilgilerine bakabilir.

Rapor Durumu olmadan, bir oturma odasında birden fazla sağlayıcının ışığını gösterdiğinde Ok Google, oturma odamın parlaklığını artır komutu, daha önce bildirilen içeriklere 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 Google Asistan'ın, cihazı yuvarlamadan cihazın mevcut durumuna sahip olması gerekir.

Platform, bir cihazın ilk SYNC durumunu takiben Home Graph'i doldurmak için cihazın durumunu toplayan bir QUERY amacı gönderir. Bu noktadan sonra Home Graph yalnızca Rapor Durumu ile gönderilen durumu depolar.

Rapor Durumunu çağırırken belirli bir özellik için tam durum verilerini sağladığınızdan emin olun. Home Graph, durumları özellik bazında günceller ve Rapor Durumu çağrısı yapıldığında bu özellik için tüm verilerin üzerine yazar. Örneğin, StartStop özelliği için durumu bildiriyorsanız yükün hem isRunning hem de isPaused değerlerini içermesi gerekir.

Başlarken

Rapor Durumunu uygulamak için şu adımları izleyin:

Google HomeGraph API'yi etkinleştirme

  1. Google Cloud Platform Console'da HomeGraph API sayfasına gidin.

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

Hizmet Hesabı Anahtarı Oluşturma

GCP Console'dan 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, akıllı ev proje kimliğinizle eşleşen projedir.
  1. GCP Console'da Hizmet hesabı anahtarı oluşturma sayfasına gidin.

    Hizmet Hesabı Anahtarı Oluşturma sayfasına git
  2. Service account (Hizmet hesabı) listesinden New service account'u (Yeni hizmet hesabı) seçin.
  3. 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ü olarak JSON seçeneğini belirleyin.

  7. Oluştur'u tıklayın. Bilgisayarınıza indirilen anahtarlarınızı içeren bir JSON dosyası.

API'ye çağrıda bulunun

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

HTTP

Home Graph API'si 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 alın:
  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ği aşağıda verilmiştir:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Rapor Durumu ve Bildirim JSON ile HTTP POST isteğinizdeki jetonu Google Home Graph uç noktasına birleştirin. Test olarak curl kullanarak komut satırında nasıl istekte bulunulacağına dair bir örneği aşağıda bulabilirsiniz:
  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'si bir gTB uç noktası sağlar

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

Node.js

Google API'leri Node.js İstemcisi, Home Graph API 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 Bilgilerini kullanarak HomeGraphApiService'i başlatın.
  2. ReportStateAndNotificationRequest ile reportStateAndNotification yöntemini çağırın. Bir ReportStateAndNotificationResponse 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 Durumu Durumu

İşleminizi sertifikasyona hazır hale getirmek için rapor durumunu test etmeniz önemlidir.

Ön koşullar

İşleminizi test edebilmek için Hizmet Hesabı Anahtarınıza ve agentUserId cihazınıza ihtiyacınız vardır. Hizmet Hesap Anahtarınız zaten varsa ve agentUserId Rapor Durumu Kontrol Panelini Dağıtma bölümüne bakın.

Rapor Durumu kontrol panelini dağıtma

Projeniz için Hizmet Hesabı Anahtarı ve aracıUserId'yi edindikten sonra, Rapor Durumu Kontrol Paneli'nden en son sürümü indirip dağıtın. En son sürümü indirdikten sonra, dahil edilen 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.
  • Aracı kullanıcı kimliğinizi 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 olursa satır yeşil renkte vurgulanır.

Hata Yanıtları

Rapor Durumu'nu ç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ıdır.
  • 404 Not Found: İstenen kaynak bulunamadı, ancak ileride kullanıma sunulabilir. Genellikle bu, 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 e-posta adresi aldığımız anlamına da gelebilir. agentUserId ile SYNC yanıtınızda sağlanan değerin eşleştiğinden ve DISBA intent'lerini doğru şekilde işlediğinizden emin olun.