Rapor Durumu

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

Report State, kullanıcı cihazlarıyla ilişkilendirilmiş ve belirtilen agentUserId olduğu sürece bu cihazları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 amacını yayınlamadan önce çeşitli üçüncü taraf bulutlara QUERY niyeti göndermek yerine Home Graph içinde durum bilgisini arayabilir.

Report State kullanılmadığında, bir oturma odasındaki birden fazla sağlayıcıdan gelen ışıklar göz önünde bulundurulduğunda Ok Google, salonumun parlaklığını artır komutu, daha önce bildirilenlere göre mevcut parlaklık değerlerini aramak yerine, birden çok buluta gönderilen birden çok QUERY amacını çözmeyi gerektirir. En iyi kullanıcı deneyimi için Assistant uygulamasının mevcut durumda olması gerekir. Bu durumda cihaza gidiş geliş gerekmez.

Bir cihaz için ilk SYNC değerinin ardından platform, Home Graph alanını doldurmak için cihazın durumunu toplayan bir QUERY amacı 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 tam durum verileri sağladığınızdan emin olun. Home Graph, durumları özellik başına günceller ve bir Report State çağrısı yapıldığında bu özellik için tüm verilerin üzerine yazar. Örneğin, StartStop özelliği için durum raporluyorsanı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 Home Graph API'yi etkinleştirin

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

    Home Graph 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 uygulamasından bir hizmet hesabı anahtarı oluşturmak için şu talimatları uygulayın:

Not: Bu adımları uygularken doğru GCP projesini kullandığınızdan emin olun. Bu, smart home proje kimliğinizle eşleşen projedir.
  1. Google Cloud Console sayfasında Hizmet hesabı anahtarı oluştur sayfasına gidin.

    Hizmet Hesabı Anahtarı Oluşturun 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 listesinden Hizmet Hesapları > Hizmet Hesabı Jetonu Oluşturucu'yu seçin.

  6. Anahtar türü olarak 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:

HTTP

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

  1. İndirilen hizmet hesabı JSON dosyasını kullanarak JSON Web Token (JWT) oluşturun. Daha fazla bilgi için bkz. Hizmet Hesabı Kullanarak Kimlik Doğrulama.
  2. oauth2l kullanarak https://www.googleapis.com/auth/homegraph kapsamında bir OAuth 2.0 erişim jetonu alın:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. JSON isteğini agentUserId ile 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 dosyasını ve HTTP POST isteğinizdeki jetonu Google Home Graph uç noktasıyla birleştirin. Aşağıda, test olarak curl 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 hizmeti tanımını öğrenin.
  2. Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici dokümanlarındaki talimatları uygulayın.
  3. ReportStateAndNotification yöntemini çağırın.

Node.js

Google API'leri Node.js İstemcisi, Home Graph API'sı için bağlantılar sağlar.

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

HomeGraph API Client Library for Java, Home Graph API için bağlantılar sağlar.

  1. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak HomeGraphApiService hizmetini 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 Raporu Durumu

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

İşleminizi sertifika almaya hazırlamak için Report State testini yapmanız ö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 olsa da kullanımdan kaldırıldı ve artık desteklenmiyor.

Rapor Durumu Kontrol Paneli

Ön koşullar

İşleminizi test edebilmeniz için Hizmet Hesabı Anahtarınıza ve agentUserId hizmetinize ihtiyacınız vardır. Hizmet hesabı anahtarınız zaten varsa veagentUserId Report StateKontrol Paneli'ni dağıtma başlıklı makaleyi inceleyin.

Rapor Durumu kontrol panelini dağıtma

Projeniz için Hizmet Hesabı Anahtarını ve Aracı User-ID'sini edindikten sonra 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 (your_project_id kısmını 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
  • AgentUserId'nizi 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ın durumunda bir değişiklik olursa satır yeşil renkle vurgulanır.

Hata Yanıtları

Report State numaralı telefonu aradığınızda aşağıdaki hata yanıtlarından birini alabilirsiniz. Bu yanıtlar HTTP durum kodları biçiminde gelir.

  • 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ımı yer alır.
  • 404 Not Found: İstenen kaynak bulunamadı ancak ileride kullanıma sunulabilir. Bu durum 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 amaçlarını düzgün bir şekilde işlediğinizden emin olun.