Rapor Durumu

Report State, Google Home Graph niyetini beklemek yerine Google Home İşlemi'nin kullanıcının cihazının en son durumunu Google Home Graph'e proaktif olarak bildirmesini sağlayan önemli bir özelliktir.QUERY

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 durumunun anlaşılmasını gerektiren bir işlem yapmak istediğinde EXECUTE amacını yayınlamadan önce çeşitli üçüncü taraf bulutlarına QUERY amacı yayınlamak yerine Home Graph'deki durum bilgilerini arayabilir.

Report State olmadan, oturma odasında birden fazla sağlayıcının ışıkları varken Ok Google, oturma odamı aydınlat komutu, daha önce bildirilenlere göre mevcut parlaklık değerlerini basitçe aramak yerine birden fazla buluta gönderilen birden fazla QUERY amacının çözülmesini gerektirir. En iyi kullanıcı deneyimi için Assistant, cihaza gidiş-dönüş gerektirmeden cihazın mevcut durumuna sahip olmalıdır.

Bir cihaz için ilk SYNC işleminden sonra platform, Home Graph öğesini doldurmak üzere cihazın durumunu toplayan bir QUERY amaç 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 söz konusu özelliğin tüm verilerinin ü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ş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 bölümünde 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'dan hizmet hesabı anahtarı oluşturmak için aşağıdaki talimatları uygulayın:

1. Google Cloud Console bölümünde Hizmet hesapları sayfasına gidin.

   Hizmet hesapları sayfasına gidin.

   Hizmet Hesapları sayfasına yönlendirilmeden önce bir proje seçmeniz gerekebilir.

2. addHizmet hesabı oluştur'u tıklayın.

3. Hizmet hesabı adı alanına bir ad girin.

4. Hizmet hesabı kimliği alanına bir kimlik girin.

5. Hizmet hesabı açıklaması alanına bir açıklama girin.

6. Oluştur ve devam et'i tıklayın.

7. Rol açılır listesinden Hizmet Hesapları > Hizmet Hesabı OpenID Connect Kimlik Jetonu Oluşturucu'yu seçin.

8. Devam'ı tıklayın.

9. Bitti'yi tıklayın.

10. Hizmet hesapları listesinden yeni oluşturduğunuz hizmet hesabını seçin ve more_vert İşlemler menüsünden Anahtarları yönet'i seçin.

11. Anahtar ekle > Yeni anahtar oluştur'u seçin.

12. Anahtar türü olarak JSON seçeneğini belirleyin.

13. 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 birini seçin:

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).execute();
}
    

Test Raporu Durumu

Cloud-to-cloud entegrasyonunuzun sertifikalandırmaya hazır olması için Report State testini yapmanız önemlidir.

Bunu yapmak için Home Graph Görüntüleyici aracını kullanmanızı öneririz. Bu araç, indirme veya dağıtım gerektirmeyen bağımsız bir web uygulamasıdır.

Report State Kontrol Paneli hâlâ kullanılabilir ancak kullanımdan kaldırıldı ve artık desteklenmiyor.

Rapor Durumu Kontrol Paneli

Ön koşullar

Cloud-to-cloud entegrasyonunuzu test edebilmek için hizmet hesabı anahtarınız ve Cloud-to-cloud gereklidir.agentUserId Hizmet Hesabı Anahtarınız zaten varsa ve agentUserId görüyorsanız Report State Hesap Özetini Dağıtma başlıklı makaleyi inceleyin.

Durum Raporu kontrol panelini dağıtma

Projeniz için hizmet hesabı anahtarı ve aracı kullanıcı kimliğine sahip olduğunuzda, Report State 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 (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 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.

Eyalet Tutarsızlığını Bildirme

Sorguya dayalı rapor durumu doğruluğu, bir cihazın en son rapor durumunun, kullanıcı sorguladığında cihazın durumuyla ne kadar iyi eşleştiğini ölçer. Bu değerin %99,5 olması bekleniyor. Projenizin Durum Doğruluğu Raporu'nun mevcut durumu hakkında daha fazla bilgi için Cihaz Sağlığı - Durum doğruluğu başlıklı makaleyi inceleyin. Rapor Durumu Uyuşmazlığı Günlüğü'nün ayrıntılarını Günlük Gezgini'nden de görebilirsiniz.

Aşağıda bir Rapor Durumu Uyuşmazlığı Günlüğü örneği verilmiştir:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Rapor durumu tutarsızlığı günlük alanı tanımları

Hata Yanıtları

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

400 Hatalı İstek

Sunucu, istemci tarafından gönderilen isteği geçersiz söz dizimi nedeniyle 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 Bulunamadı

İstenen kaynak bulunamadı ancak gelecekte kullanılabilir. Bu genellikle istenen cihazın bulunamadığı 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 şekilde işlediğinizden emin olun.

Bir ReportState çağrısı 404 NOT_FOUND hatasıyla başarısız olduğunda, bulutunuz ile Home Graph arasında senkronizasyon uyuşmazlığı olduğu anlaşılır. Bu durum, bir cihaz Home Graph'dan kaldırılırsa veya kullanıcı hesabının bağlantısını kaldırırsa ortaya çıkabilir.

Durum Bildir raporundaki 404 hatalarını işlemek için aşağıdaki prosedürü kullanın:

1. Kullanıcı hesabı durumunu kontrol edin: 404 hatası döndüren agentUserId için devices.sync işlevini çağırın. Bu, hatanın tüm kullanıcı hesabı için mi yoksa belirli bir cihaz için mi olduğunu belirlemeye yardımcı olur.
   • SYNC 404 hatası döndürürse kullanıcı hesabı artık Google'a bağlı değildir. Bu kullanıcının cihazları için Durumu Bildir ve Senkronizasyon İsteği göndermeyi durdurun.
   • SYNC 200 OK döndürürse kullanıcı hesabı hâlâ bağlıdır. Bu durumda 404 hatası cihaza özgüdür.
2. Cihaz listesini mutabakat edin: SYNC 200 OK döndürürse Google'ın artık tanımadığı cihazları belirlemeniz gerekir. Google'ın kullanıcı için sahip olduğu cihaz listesini cihaz veritabanınızla karşılaştırmanızı ve sisteminizde Google'ın listesinde bulunmayan cihazları belirlemenizi öneririz. Google ile senkronize edilmesi gereken ancak henüz Google ile paylaşılmamış bir cihaz varsa cihazın Google ile senkronize edildiğinden emin olmak için SYNC kullanın. Bir cihazın Google ile bağlantısı kaldırılacaksa söz konusu cihaza ait durumu bildirmeyi durdurun ve bu agentUserId altındaki diğer geçerli cihazlar için bildirmeye devam edin.

Çevrimiçi ve çevrimdışı durum raporlama

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }