Matter entegrasyon sorunlarını giderme

refresh_date: 2023-01-06

Google Cloud, Google Cloud Monitoring ile projelerinizin güvenilirliğini izlemenizi ve Google Cloud Logging hata günlükleriyle sorunları gidermenizi sağlayan araçlar sunar. Kullanıcı niyetleri karşılanırken her hata oluştuğunda Google Home Analytics ardışık düzeni bu hatayı metriklerinize kaydeder ve proje günlüklerinizde bir hata günlüğü yayınlar.

Hatalarınızı gidermek için iki adım vardır:

  1. Akıllı ev metriklerini kullanarak projelerinizin durumunu izleyin.
  2. Hata günlüklerindeki ayrıntılı hata açıklamalarını kontrol ederek sorunları inceleyin.

Hataları izleme

Proje metriklerinize erişmek için Google Cloud Monitoring dashboard'ları kullanabilirsiniz. Özellikle kaliteyi izlemek ve hata ayıklama için yararlı olan bazı önemli grafikler vardır:

  • Projelerinizin güvenilirliğini izlerken ilk bakacağınız grafik Başarı Oranı grafiğidir. Bu grafikteki düşüşler, kullanıcı tabanınızın bir kısmında veya tamamında kesinti olduğunu gösterebilir. Projenizde her değişiklik veya güncellemeden sonra bu grafiği anormallikler açısından yakından izlemenizi öneririz.
  • Hata Ayrıştırması grafikleri, entegrasyonlarınızdaki sorunları giderme konusunda en yararlı olanlardır. Başarı yüzdesi grafiğinizde vurgulanan her hata için hata dökümünüzde bir hata kodu gösterilir. Google Home platform ile işaretlenen hataları ve bunların nasıl giderileceğini aşağıdaki tabloda görebilirsiniz.

Platform Hata Kodları

Google Home platform tarafından yakalanan sorunları belirlemek için proje günlüklerinizde görebileceğiniz bazı yaygın hata kodları aşağıda verilmiştir. Sorun giderme bilgileri için lütfen aşağıdaki tabloya bakın.

Hata Kodu Açıklama
BACKEND_FAILURE_URL_ERROR Google, hizmetinizden 401 dışında bir HTTP 4xx hata kodu aldı.

Akıllı ev hizmet günlüklerinizi kontrol etmek için GCP GünlükrequestId
BACKEND_FAILURE_URL_TIMEOUT Google, hizmetinize ulaşmaya çalışırken isteği zaman aşımına uğradı.

Hizmetinizin internete bağlı, bağlantı kabul ettiği ve kapasitesinin dolmadığından emin olun. Ayrıca, hedef cihazın açık, internete bağlı ve senkronize olduğundan emin olun.
BACKEND_FAILURE_URL_UNREACHABLE Google, hizmetinizden bir HTTP 5xx hata kodu aldı.

Akıllı ev hizmet günlüklerinizi kontrol etmek için GCP GünlükrequestId
DEVICE_NOT_FOUND Cihaz, iş ortağı hizmetinde mevcut değil.

Bu durum genellikle veri senkronizasyonunda bir hataya veya yarış durumuna işaret eder.
GAL_BAD_3P_RESPONSE Google, yükte geçersiz biçim veya değerler bulunduğu için hesap bağlama hizmetinizden gelen yanıtı ayrıştıramıyor.

Hesap bağlama hizmetinizdeki hata günlüklerini kontrol etmek için GCP Günlük'teki requestId'ı kullanın.
GAL_INTERNAL Google, erişim jetonu almaya çalışırken Google dahili bir hata oluştu.

GCP Günlük Kayıtları'nda bu hatanın oranının arttığını görürseniz daha fazla bilgi için bizimle iletişime geçin.
GAL_INVALID_ARGUMENT Google, erişim jetonu almaya çalışırken Google dahili bir hata oluştu.

GCP Günlük Kayıtları'nda bu hatanın oranının arttığını görürseniz daha fazla bilgi için bizimle iletişime geçin.
GAL_NOT_FOUND Kullanıcının Google'da depolanan erişim ve yenileme jetonları geçersiz kılınarak artık yenilenemez. Kullanıcının, hizmetinizi kullanmaya devam etmek için hesabını yeniden bağlaması gerekir.

GCP Günlük Kayıtları'nda bu hatanın oranının arttığını görürseniz daha fazla bilgi için bizimle iletişime geçin.
GAL_PERMISSION_DENIED Jeton paylaşımı yetkilendirilmediğinde Google'da dahili bir hata oluştu.

GCP Günlük Kayıtları'nda bu hatanın oranının arttığını görürseniz daha fazla bilgi için bizimle iletişime geçin.
GAL_REFRESH_IN_PROGRESS Kullanıcının erişim jetonunun süresi dolmuş ve jetonu yenilemeye yönelik başka bir eşzamanlı girişim devam ediyor.

Bu bir sorun değildir ve herhangi bir işlem yapmanız gerekmez.
INVALID_AUTH_TOKEN Google, hizmetinizden HTTP 401 hata kodu aldı.

Erişim jetonunun süresi dolmamış ancak hizmetiniz jetonu geçersiz kılmış. Akıllı ev hizmet günlüklerinizi kontrol etmek için GCP Günlük'teki requestId'ü kullanın.
INVALID_JSON JSON yanıtı ayrıştırılamaz veya anlaşılamaz.

JSON yanıtınızın yapısında eşleşmeyen parantezler, eksik virgüller, geçersiz karakterler gibi geçersiz söz dizimi olup olmadığını kontrol edin.
OPEN_AUTH_FAILURE Kullanıcının erişim jetonunun süresi dolmuş ve Google bu jetonu yenileyemiyordur veya Google, hizmetinizden HTTP 401 hata kodu almıştır.

Bu kodun oranında artış görürseniz akıllı ev intent'leri veya yenileme jetonu istekleriyle ilgili hata oranında da artış olup olmadığını kontrol edin.
PARTNER_RESPONSE_INVALID_ERROR_CODE Yanıt, tanınmayan bir hata kodunu gösteriyor.

İsteğinizin yanıtında hata varsa desteklenen hata kodlarımızdan birini kullandığınızdan emin olun.
PARTNER_RESPONSE_INVALID_PAYLOAD Yanıt payload alanı JSON nesnesi olarak ayrıştırılamadı.

İstek yanıtınızdaki yük alanı çiftlerinin eşleşip eşleşmediğini ve JSON alanı olarak doğru şekilde yapılandırılıp yapılandırılmadığını kontrol edin.
PARTNER_RESPONSE_INVALID_STATUS Yanıt, bir durum belirtmiyor veya yanlış bir durum belirtiyor.

Intent fulfillment isteklerine verilen yanıtlar, SUCCESS, OFFLINE, ERROR, EXCEPTIONS ile bir durum belirtmelidir. Hata ve istisnaları ele alma hakkında daha fazla bilgi edinebilirsiniz.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES İstekte bulunan bir veya daha fazla intent yanıtta eksik.

yürütme yanıtınızın doğru şekilde yapılandırıldığından ve istekteki tüm intent'lerin sonuçlarının yanıtınızda bulunduğundan emin olun.
PARTNER_RESPONSE_MISSING_DEVICE İstekte bulunan bir veya daha fazla cihaz yanıtta eksik.

yürütme yanıtınızın doğru şekilde yapılandırıldığından ve istekteki tüm cihaz kimliklerinin yanıtınızda bulunduğundan emin olun.
PARTNER_RESPONSE_MISSING_PAYLOAD Yanıt bir payload alanı içermiyor.

İstek yanıtınıza bir yük alanı eklediğinizden emin olun. Yürütme yanıtını doğru şekilde oluşturma hakkında daha fazla bilgi edinebilirsiniz.
PARTNER_RESPONSE_NOT_OBJECT Yanıt, JSON nesnesi olarak ayrıştırılamaz.

İsteğinizin yanıtındaki tüm alanları istenmeyen karakterler, eşleşmeyen parantezler veya biçimlendirme hataları açısından kontrol edin. Bazı Unicode karakterleri desteklenmeyebilir. Ayrıca yanıtınızın JSON nesnesi olarak doğru şekilde yapılandırıldığından emin olun.
PROTOCOL_ERROR İstek işlenemedi.

Akıllı ev hizmet günlüklerinizi kontrol etmek için Google Cloud Logging'daki requestId'ı kullanın.
RESPONSE_TIMEOUT Yanıt beklenirken istek zaman aşımına uğradı.

Yanıt gönderme için zaman aşımı süresi, istek gönderildikten 9 saniye sonradır. Bu süre içinde yanıt verdiğinizden emin olun.
RESPONSE_UNAVAILABLE Yanıt alınmıyor veya yanıtta durum belirtilmiyor.

Intent fulfillment isteklerine verilen yanıtlar, akıllı ev dokümanlarına göre yapılandırılmalıdır ve durumu belirtmelidir.
TRANSIENT_ERROR Geçici hatalar kendiliğinden çözülür.

Bu hatalar genellikle bir cihaza veya hizmete bağlantının kopması şeklinde kendini gösterir. Ayrıca, bir sunucuya yeni bağlantılar açılamıyorsa

Arama Günlükleri

Entegrasyonlarınızı metrikleri kullanarak izleme konusunda rahat hissettikten sonra, Cloud Logging'i kullanarak belirli hataları giderebilirsiniz. Hata günlüğü, zaman, hata kodu ve kaynak akıllı ev amacıyla ilgili ayrıntılar gibi yararlı bilgiler içeren JSON benzeri bir giriştir.

Google Cloud'te, projenize her zaman günlük gönderen birden fazla sistem vardır. Günlüklerinizi filtrelemek için sorgu yazmanız ve ihtiyacınız olanları bulmanız gerekir. Sorgular zaman aralığına, kaynak, günlük önemine veya özel girişlere dayalı olabilir.

Cloud Günlüklerini sorgulama

Özel filtrelerinizi oluşturmanıza yardımcı olması için sorgu düğmelerini kullanabilirsiniz.

Cloud Günlük Sorguları Oluşturma

Zaman aralığı belirtmek için zaman aralığı seçim düğmesini tıklayın ve sunulan seçeneklerden birini belirleyin. Bu işlem, günlükleri filtreler ve seçilen zaman aralığındaki günlükleri gösterir.

Kaynak belirtmek için Kaynak açılır menüsünü tıklayın, ardından Google Asistan İşlem Projesi'ni seçin. Bu işlem, sorgunuza projenizden gelen günlükleri gösterecek bir filtre ekler.

Acil durum, Bilgi, Hata ayıklama ve diğer önem derecesi günlük düzeylerine göre filtrelemek için Önem derecesi düğmesini kullanın.

Özel girişler girmek için Logs Explorer bölümündeki Sorgu alanını da kullanabilirsiniz. Bu alan tarafından kullanılan sorgu motoru hem dize eşleştirme gibi temel sorguları hem de karşılaştırıcılar (<, >=, !=) ve Boole operatörleri (AND, OR, NOT) gibi daha gelişmiş sorgu türlerini destekler.

Örneğin, aşağıdaki özel giriş LIGHT cihaz türünden kaynaklanan hataları döndürür:

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

Günlükleri etkili bir şekilde sorgulamaya yönelik daha fazla örnek bulmak için Sorgu Kitaplığı'nı ziyaret edin.

Düzeltmeleri test etme

Hataları tespit edip düzeltmek için güncellemeler uyguladıktan sonra, düzeltmelerinizi Google Home Test Suite ile ayrıntılı olarak test etmenizi öneririz. Değişikliklerinizi etkili bir şekilde test etmenize rehberlik edecek Test Suite kullanım kılavuzu sunuyoruz.

Eğitici Kaynaklar

Bu dokümanda, Smart Home Action'ınızdaki hataları giderme adımları sağlanmaktadır. Hata ayıklama hakkında daha fazla bilgi edinmek için codelab'lerimizi de inceleyebilirsiniz:

Önceki
Matter ile Cloud Storage