Rapor Durumu

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

Report State, kullanıcı cihazlarının durumlarını, kendileriyle ilişkili belirtilen agentUserId ile (orijinal SYNC isteğinde gönderilir) Google'a bildirir. Google Assistant, bir cihazın mevcut durumunun anlaşılmasını gerektiren bir işlem yapmak istediğinde, EXECUTE intent'ini yayınlamadan önce çeşitli üçüncü taraf bulutlarına QUERY intent'i yayınlamak yerine Home Graph'deki durum bilgilerine bakabilir.

Report State olmadan, bir oturma odasında birden fazla sağlayıcıdan gelen ışıklar varsa 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'in çözümlenmesini 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 değerini 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 çağrılırken belirli bir özellik için eksiksiz durum verileri sağlanmalıdır. Home Graph, durumları her özellik için ayrı ayrı günceller ve bir Report State çağrısı yapıldığında ilgili özelliğin tüm verilerinin ü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 özelliğini uygulamak için aşağıdaki adımları izleyin:

• 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 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:

1. Google Cloud Console'nda 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. Service account name (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. Role (Rol) açılır menüsünden Service Accounts (Hizmet Hesapları) > Service Account OpenID Connect Identity Token Creator'ı (Hizmet Hesabı OpenID Connect Kimlik Jetonu Oluşturucu) 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ü için 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 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).execute();
}
    

Test Raporu Durumu

Cloud-to-cloud entegrasyonunuzu sertifikasyona hazır hale getirmek için Report State 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

Cloud-to-cloud entegrasyonunuzu test edebilmek için hizmet hesabı anahtarınız ve agentUserId gerekir. Hizmet hesabı anahtarınız ve agentUserId varsa Report State kontrol panelini dağıtma başlıklı makaleyi inceleyin.

Durum Bildirme 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 yeni sürümü indirip dağıtın. En yeni 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'yi kullanarak kontrol paneline erişin (your_project_id ifadesini 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 Listele'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.

Durum 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ı beklenir. Projenizin Durum Doğruluğunu Bildir özelliğinin mevcut durumu hakkında daha fazla bilgi için Cihaz Sağlığı - Durum doğruluğu başlıklı makaleyi inceleyin. Report State Tutarsızlık Günlüğü ile ilgili ayrıntıları Günlük Gezgini'nde de görebilirsiniz.

Aşağıda bir Report State tutarsızlık 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ık Günlüğü alan tanımları

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çiminde gelir.

400 Hatalı İstek

Sunucu, geçersiz söz dizimi nedeniyle istemci tarafından gönderilen isteği işleyemedi. Bunun sık karşılaşılan nedenleri 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 durum genellikle istenen cihazı bulamadığımız anlamına gelir. Bu hata, kullanıcı hesabının Google ile bağlantı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ı doğru şekilde işlediğinizden emin olun.

ReportState çağrısı 404 NOT_FOUND hatasıyla başarısız olduğunda bu, bulutunuz ile Home Graph arasında bir senkronizasyon uyuşmazlığı olduğunu gösterir. Bu durum, bir cihaz Home Graph uygulamasından kaldırıldığında veya bir kullanıcı hesabının bağlantısını kaldırdığında ortaya çıkabilir.

Report State'ten gelen 404 hatalarını işlemek için aşağıdaki prosedürü kullanın:

1. Kullanıcı hesabı durumunu kontrol etme: 404 hatası döndüren agentUserId için devices.sync yöntemini çağırın. Bu sayede, hatanın kullanıcı hesabının tamamı için mi yoksa belirli bir cihaz için mi geçerli olduğu belirlenebilir.
   • 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 Durum Bildirme 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 özeldir.
2. Cihaz listesini mutabık kılma: SYNC, 200 OK döndürürse artık Google tarafından bilinmeyen cihazları tanımlamanız gerekir. Google'ın kullanıcı için sahip olduğu cihaz listesini cihaz veritabanınızla karşılaştırmanızı ve sisteminizde olup 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 komutunu kullanın. Bir cihazın Google ile bağlantısının kaldırılması gerekiyorsa söz konusu cihaz için durum bildirmeyi durdurun ve ilgili agentUserId altındaki diğer geçerli cihazlar için durum bildirmeye devam edin.

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

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