Google Home Vitals (Cloud)

Bu kontrol paneli ve uyarı paketi, Google Home ekosistemiyle yüksek kaliteli bir entegrasyonu proaktif olarak sürdürmenize yardımcı olur. Google, tüm müşteriler için yüksek kaliteli bir ekosistem geliştirmede iş ortaklarını desteklemeye kararlıdır.

Gösterge tablosu üç bölümden oluşur. Bu bölümlerin her biri, genel entegrasyon kalitesine katkıda bulunan önemli bir parçayı kapsar.

1. Google'dan İş Ortağı Metriklerine: Google'dan bulut arka ucunuza yapılan çağrıların durumunu ölçer.

2. Sistem Sağlığı - İş Ortağından Google'a Yönelik Metrikler: Sisteminizden Google'a yapılan çağrıların sağlığını ölçer.

3. Cihaz Sağlığı - Durum Doğruluğu: Kullanıcı sorgularına yanıt vermek için kullanılan Google sistemlerinde depolanan durumların doğruluğunu ölçer.

Metrikler hedef değerlerini karşılamadığında, kullanıcı deneyimini etkileyebilecek bir sorunu belirtmek için kırmızı renkte vurgulanır. Aşağıdaki bilgilerde her hedef ve kullanıcılarınız için neden önemli olduğu hakkında ayrıntılar verilmektedir.

Aşağıdaki düğme sizi doğrudan kontrol paneline yönlendirmiyorsa Genel Bakış sayfasını seçip Gösterge Tabloları'nı tıklayarak ve ardından Gösterge Tablolarım listesinden Google Home Vitals Kontrol Paneli (Bulut)'nu seçerek kontrol panelinizi görüntüleyebilirsiniz.

Kontrol Paneli'ne git

Google'dan iş ortağına metrikler

Sorgu/Yürütme Başarı Oranı >=%99,5 metriği, kullanıcıların komutlarının ne sıklıkta doğru şekilde yerine getirildiğini ölçer.Bu metrik, "Cihaza erişemiyorum" gibi Asistan yanıtlarını veya henüz yerine getirilmemiş bir komutu yanlışlıkla onaylamayı önlemeye yardımcı olur.

"Başarı"yı ne tanımlar?

Google Home platformu, amaçlanan işlemin gerçekleştirildiğini veya istenen durumun alındığını belirten geçerli bir yanıt aldığında işlem başarılı olarak işaretlenir.

Engelleyici olmayan istisnalar içeren yanıtlar (ör. SUCCESS durumuyla birlikte lowBattery istisnası) başarılı işlemler olarak sayılır. Komut, uyarıya rağmen cihaza ulaştı ve amaç karşılandı.

"Başarısızlık" ne anlama gelir?

Sık karşılaşılan platform hata kodları sayfasında bulunan ve İş Ortağı Tarafından İşlem Yapılabilir olarak işaretlenen hatalar, SORGULAMA ve YÜRÜTME Başarı Oranları hesaplanırken "Başarısızlık" olarak kabul edilir. Ayrıca, Hatalar ve istisnalar bölümünde bulunan hatalar da aşağıdaki istisnalar dışında "Başarısızlık" olarak kabul edilir:

Sorgu/Yürütme Gecikmesi (p90) <= 1000 ms metriği, istenen işlemin bekleme süresini ölçer ve kullanıcıların çok uzun süre beklememesini sağlar. Örneğin, ışıklarının kapanması için birkaç saniye beklemeleri gibi.

Gecikme metrikleri

Gecikme, entegrasyonunuzun son kullanıcıya ne kadar hızlı yanıt verdiğinin önemli bir göstergesidir. Kontrol paneli, "en yavaş" kullanıcılarınızın deneyimini temsil eden 90. yüzdelik dilim (P90) gecikmesini izler (örneğin, 800 ms'lik bir P90, isteklerin% 90'ının 800 ms veya daha kısa sürede onaylandığı anlamına gelir).

Google, teknik doğruluğu sağlamak için durum kontrolleri ile cihaz komutlarındaki gecikmeyi farklı şekilde ölçer.

1. QUERY Latency (Interrogative)

Bu metrik, Google bir cihazın mevcut durumunu istediğinde Cloud-to-cloud gidiş dönüş süresini ölçer.

• Başlangıç: Google, karşılama URL'nize bir action.devices.QUERY isteği gönderir.
• Ölçüm Penceresi: Bulutunuzun tam HTTP yanıtını alması, işlemesi ve Google'a geri iletmesi için geçen süre.
• Son: Google, hizmetinizden gelen son yanıt yükünü alır ve onaylar.

2. EXECUTE Gecikmesi (İşlem)

Bu metrik, Google bir cihaza kontrol isteği gönderdiğinde komut onay süresini ölçer.

• Başlangıç: Google, karşılama URL'nize bir action.devices.EXECUTE isteği gönderir.
• Ölçüm Penceresi: Bulutunuzun komutu alması ve onay yanıtı döndürmesi için geçen süre.
• Bitiş: Google, SUCCESS, PENDING veya OFFLINE durum yanıtını alır.
• Teknik Kapsam: Bu metrik, Google'ın bulutu ile sizin bulutunuz arasındaki"Yanıt Onayı" süresini ölçer. Fiziksel donanımın (ör. ampul) fiziksel durum değişikliğini tamamlaması için geçen süreyi ölçmez. Bu süre genellikle buluttan buluta yolu dışındaki yerel bağlantılı ağ gecikmesini içerir.

Gecikmeyi azaltma seçenekleri

Coğrafi yönlendirme için mimari öneriler

Anycast IP uygulaması mümkün değilse kullanıcıların en yakın bölgesel veri merkezinden hizmet almasını sağlamak için aşağıdaki uygun maliyetli alternatifleri öneririz.

1. Global Load Balancing (GLB)

   Statik yönlendirme yerine Global Uygulama Yük Dengeleyicisi'nı kullanın (en büyük bulut sağlayıcıların çoğunda mevcuttur).

   • İşleyiş şekli: Ağın kenarında bulunan tek bir genel giriş noktası (URL) yapılandırırsınız. Yük dengeleyici, Google'ın karşılama kümelerinden gelen isteğin coğrafi kaynağını otomatik olarak algılar ve trafiği en yakın bölgesel sağlıklı arka uca yönlendirir.

   • Avantaj: Bu, Anycast'in performansını önemli ölçüde daha düşük yapılandırma karmaşıklığı ve maliyetle sağlar.

2. Coğrafi Konuma Duyarlı DNS (GeoDNS)

   • İşleyiş şekli: DNS sağlayıcınızı, DNS sorgusunun coğrafi konumuna göre karşılama URL'nizi farklı IP adreslerine çözümleyecek şekilde yapılandırın.

   • Uygulama: DNS sağlayıcınızın Google'ın çıkış noktaları için optimize edildiğinden emin olun. Google'ın bölgesel karşılama hizmetleri (ör. ABD, AB veya Asya'da) alan adınızı çözdüğünde, söz konusu bölgedeki veri merkezinin IP adresini alır.

Uygulama katmanındaki optimizasyon stratejileri

Altyapı düzeyinde yönlendirmenin ötesinde, istek işlemedeki gecikmeyi azaltmak için uygulama katmanında aşağıdaki stratejileri uygulayabilirsiniz.

1. "Trambolin" Proxy Yöntemi

   Birincil bir veri merkezi bulundurmanız gerekiyorsa ilk el sıkışmayı yönetmek için bölgesel hafif proxy sunucular (Trambolinler) kullanın.

   1. Google, global URL'nize erişir.

   2. İsteği bölgesel bir proxy (ör. basit bir Nginx veya Lambda işlevi) alır.

   3. Proxy, yükü dahili ve yüksek hızlı omurganız üzerinden birincil veritabanına yönlendirir.

   Avantaj: Bu, genellikle uzun mesafeli isteklerde gecikmeye en büyük katkıyı sağlayan "TCP el sıkışması" süresini kısaltır.

2. Erişim Jetonu Bölge İpuçları

   Hesap bağlama (OAuth) işlemi sırasında sisteminiz kullanıcının yaşadığı bölgeyi belirleyebilir.

   Uygulama: Google'a verilen access_token içine bir bölge tanımlayıcısı kodlayın. Google bir karşılama isteği gönderdiğinde ağ geçidiniz, veritabanı araması yapmaya gerek kalmadan jetonu anında inceleyebilir ve isteği doğru bölgesel kümeye yönlendirebilir.

Sistem Sağlığı - İş Ortağından Google'a Metrikler

Başarı oranının >=%99,5 olması, cihaz durumlarının Google Home'da doğru olmasını, cihazların eklenip kaldırılmasını, otomasyonların tetiklenmesini ve geçmiş etkinliklerinin Google Home app (GHA)'ın Etkinlik sekmesinde görünmesini sağlar.

Başarı oranı, bulutunuz durum güncellemelerini gönderdiğinde Google tarafından döndürülen HTTP yanıt kodlarına göre hesaplanır. İş ortaklarının Google tarafındaki altyapı sorunları nedeniyle cezalandırılmaması için metrik, Google'ın dahili hatalarını başarısızlık sayısından çıkarır. Hesaplamaya dahil edilen API çağrıları HomeGraph API referansında yer alır.

"Başarı"yı ne tanımlar?

2xx (Başarılı): Durum güncellemesi, Home Graph tarafından başarıyla alınmış ve işlenmiştir.

"Başarısızlık" ne anlama gelir?

4xx (İş Ortağı Hatası), hataları gösterir ve bulutunuzdan gönderilen istekte bir sorun olduğunu belirtir. Sık karşılaşılan kodlar şunlardır:

400 Hatalı İstek

Neden: Sunucu, geçersiz söz dizimi nedeniyle isteği işleyemedi. Yaygın nedenler arasında hatalı biçimlendirilmiş JSON veya dize değeri için "" yerine null kullanılması yer alır.

Çözüm: İstek gövdesinin geçerli bir JSON olduğundan (bozuk yapı veya dize alanları için boş değerler yok) emin olun ve agentUserId değerinin SYNC yanıtındaki değerle eşleştiğini doğrulayın.

404 Bulunamadı

Neden: deviceId veya agentUserId, HomeGraph'ta bulunamadı (henüz senkronize edilmedi, bağlantısı zaten kaldırıldı veya kimlik eşleşmiyor).

Çözüm:

1. agentUserId değerinin, SYNC yanıtınızda sağlanan değerle eşleştiğinden emin olun.
2. 404 Not Found hatasının Home Graph'te eksik bir cihazdan mı yoksa kullanıcıdan mı kaynaklandığını belirlemek için Home Graph SYNC API'yi kullanın.
3. Durumun güncel kalması için cihaz veya hesap ekleme, kaldırma, yeniden adlandırma ya da güncelleme işlemlerinden sonra requestSync tetiklendiğinden emin olun.
4. Eski cihazların raporlanmasını durdurmak için DISCONNECT amaçlarını uygun şekilde işleyin. DISCONNECT amacını aldıktan sonra, bulut hizmetiniz Request Sync ve Report State ile Google'da değişiklik yayınlamayı durdurmalıdır.

429 Kaynak Tükendi

Neden: Entegrasyonunuz, ayrılan kotayı aştı.

Çözüm: Kota yönetimi için kontrol panelindeki "2a. Adım: Kota Sorunlarını Ayıklama" bölümündeki talimatları inceleyin. Daha fazla bilgi için Akıllı Ev kotaları ve sınırları başlıklı makaleyi de inceleyebilirsiniz.

Cihaz durumu - Durum doğruluğu

Durum Doğruluğu >=%99,5 ölçütünü karşılamak, kullanıcıların cihaz durumlarını görüntülerken veya Home'a Sor gibi yapay zeka özelliklerini kullanırken doğru sonuçları görmesini sağlar. Durum doğruluğu düşükse otomasyonlar tetiklenmeyebilir ve geçmiş girişleri GHA'ın Etkinlik sekmesinde doğru zamanda görünmeyebilir. Daha fazla bilgi için Durum Bildirme başlıklı makaleyi inceleyin. Lütfen unutmayın: Durum Doğruluğu hedefi, DESTEKLENEN TÜM özelliklerde karşılanmalıdır.

1. Doğruluk Bileşenleri

Metrik, Google'ın bildirilen durumu bilinen bir amaç sonucuyla karşılaştırarak doğrulayabildiği "örneklerden" elde edilir. Teknik doğruluk açısından, doğruluk iki farklı yolda değerlendirilir:

• SORGULAMAYA dayalı Doğruluk: Bir kullanıcı veya sistem, cihazın mevcut durumunu aktif olarak sorguladığında doğrulanır.
• EXECUTE tabanlı doğruluk: Kontrol isteğinin ardından bildirilen komut sonrası cihaz durumu değerlendirilerek doğrulanır.

2. Kontrol Paneli Metrikleri (Saatlik Hesaplama)

Kontrol paneli, doğruluğu 1 saatlik aralığa göre hesaplar. İstatistiksel güveni sağlamak ve düşük sinyal gürültüsüne sahip entegrasyonları cezalandırmamak için Google, minimum trafik hacmi eşiği uygular. Belirli bir özellik ve cihaz kombinasyonu, 5 günlük hareketli bir dönemde toplam 100'den az örnek toplarsa doğruluğu istatistiksel olarak önemsiz kabul edilir ve Geçersiz olarak ayarlanır.

Bir saatte her iki yolda da yeterli örnek hacmi olduğunda, belirli bir eyaletin saatlik temel doğruluk oranı, iki bağımsız yüzdenin ortalaması olarak hesaplanır:

Saatlik Durum Doğruluğu = (Sorgu Doğruluğu % + Yürütme Doğruluğu %) / 2

Burada her bir yol şu şekilde tanımlanır:

• Sorgu Doğruluğu % = (Saatlik Doğru Sorgu Örnekleri) / (Saatlik Toplam Sorgu Örnekleri)
• Yürütme Doğruluğu % = (Saatlik Yürütme Doğru Örnekleri) / (Saatlik Yürütme Toplam Örnekleri)

Özellik Doğruluk Puanı (özellik başına hesaplanır) = TOP(Sorgu Doğru Örnekleri + Yürütme Doğru Örnekleri) / TOP(Sorgu Toplam Örnekleri + Yürütme Toplam Örnekleri)

Kalite puanı, ekosisteminizdeki kesin minimum performansı değerlendirdiğinden desteklenen ve uygun olan her bir özellik, ayrı ayrı >=% 99,5 Eyalet Doğruluğu hedefini karşılamalıdır (bu, özellikler genelindeki ortalama değildir).

Bu görünüm, mükemmel doğruluk oranına sahip yüksek hacimli cihazların, daha düşük hacimli cihazlardaki doğruluk sorunlarını maskelemesini önler. Yeterince kullanılmayan özelliklerin puanlarını düşürmesinden endişe eden iş ortakları, nadiren kullanılan bir özelliğin minimum trafik hacmi kontrolüyle otomatik olarak korunduğundan ve gerekli örnek eşiğini karşılamadığı sürece En Düşük Tür ve Özellik puanına dahil edilmeyeceğinden emin olabilir.

3. Cihaz sağlığını ve durum doğruluğunu iyileştirme

Ev Grafiği'nde depolanan durum, anlık bir SORGUNUN sonuçlarıyla eşleşmediğinde tutarsızlıklar oluşur.

"Eksik Alan" hataları

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

Neden: DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD veya DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD hatasında, aynı cihaz için QUERY yanıtınız ile Report State isteğiniz arasındaki yük alanları grubu farklıdır.

Çözüm: Veri yapısının her iki yolda da aynı olduğundan emin olun. SYNC'ye bir özellik dahil edildiyse ilgili alanlar hem proaktif raporlarda hem de reaktif sorgularda mevcut ve tutarlı olmalıdır.

"Hatalı" hataları

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

Neden: DETAILED_ACCURACY_RESULT_INACCURATE hatası için QUERY yanıtında döndürülen değer ile son Rapor Durumu değeri arasında bir tutarsızlık vardır.

Çözüm: Cihaz durumu her değiştiğinde Report State'in tetiklendiğinden ve veri tutarlılığını korumak için hem Report State hem de QUERY'nin her zaman tam olarak aynı ve güncel değerleri sağladığından ve tüm gerekli alanları içerdiğinden emin olun.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

Neden: DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE hatasında, iş ortağı komutu başarıyla yürütmüş ancak güncellenen cihaz durumunu Google'a geri bildirmemiştir.

Çözüm: Home Graph'ın yeni cihaz durumunu alması için komut yürütme işleminden sonra her zaman bir durum raporu güncellemesi gönderin.

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

Neden: DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED hatası için, QUERY sonuçları mevcut durumu sağlasa da bu cihaz için ReportState alınmadı (durum boş ve bildirilen zaman damgası dönemde). Bu, durum güncellemelerinin tetiklenmediğini, HomeGraph'a ulaşamadığını veya cihazın bağlantı ya da operasyonel durumundaki geçişleri başarıyla bildirmediğini gösterir.

Çözüm: Rapor Durumu'nun tüm durum değişiklikleri için tetiklendiğinden ve başarıyla gönderildiğinden emin olun. Arka uç mantığının durum güncellemelerini doğru şekilde işlediğini, Google HomeGraph'a teslimatın başarılı olduğunu doğruladığını ve cihazın durumunu tutarlı bir şekilde senkronize ederek kullanıcı arayüzünün ve otomasyon motorunun doğru kalmasını sağladığını doğrulayın.