Matter entegrasyon sorunlarını giderme

refresh_date: 2023-01-06

Google Cloud, Google Cloud Monitoring ile projelerinizin güvenilirliğini izlemenize ve Google Cloud Logging hata günlükleriyle ilgili sorunları gidermenize olanak tanıyan araçlar sunar. Kullanıcı niyetleri yerine getirilirken bir 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 metrikleriyle projelerinizin durumunu izleyin.
  2. Hata günlüklerindeki ayrıntılı hata açıklamalarını kontrol ederek sorunları inceleyin.

İzleme hataları

Proje metriklerinize erişmek için Google Cloud Monitoring dashboards tuşunu kullanabilirsiniz. Kaliteyi izlemek ve hata ayıklamak için özellikle yararlı olan bazı önemli grafikler vardır:

  • Başarı Oranı grafiği, projelerinizin güvenilirliğini izlerken bakmanız gereken ilk grafiktir. Bu grafikteki düşüşler, kullanıcı tabanınızın bir kısmı veya tamamı için kesinti olduğunu gösterebilir. Projenizde yapılan her değişiklik veya güncellemeden sonra herhangi bir düzensizlik olup olmadığını görmek için bu grafiği yakından izlemenizi öneririz.
  • Hata Dağılımı grafikleri, entegrasyonlarınızdaki sorunları giderme konusunda en faydalı grafiklerdir. 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 (GHP) tarafından işaretlenen hataları ve bu hataları nasıl gidereceğinizi aşağıdaki tabloda görebilirsiniz.

Sık karşılaşılan platform hata kodları

GHP 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 aşağıdaki tabloya bakın. Hata kodlarının tam listesi için Hatalar ve istisnalar bölümüne bakın.

Hata Kodu Açıklama İş Ortağının Yapabileceği İşlemler
AGENT_ISSUE İş ortağının bulut aracısıyla ilgili genel bir sorun oluştu.

Yerine getirme günlüklerinizde işlenmeyen istisnalar veya kilitlenmeler olup olmadığını kontrol edin. 		Evet
AGENT_UNAVAILABLE_ERROR Google, iş ortağının sipariş karşılama URL'sine ulaşamadı.

Sunucunuzun internete bağlı olduğundan, güvenlik duvarının Google'ı engellemediğinden ve URL'nin doğru olduğundan emin olun. 		Evet
COMMAND_FAILED Bir komutun yürütülmesi sırasında genel bir hata oluştu.

Temel nedeni bulmak için belirli bir requestId ile ilgili karşılama günlüklerinizi kontrol edin. 		Evet
EXECUTION_BACKEND_FAILURE_URL_ERROR Google, karşılamanızdan bir HTTP 4xx hatası (401 dışında) aldı.

Web sunucusu günlüklerinizde 403, 404 veya 400 yanıtları olup olmadığını kontrol edin. 		Evet
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT Google'ın isteği, hizmetinize ulaşmaya çalışırken zaman aşımına uğradı.

Hizmetinizin online olduğunu, bağlantıları kabul ettiğini ve kapasitesini aşmadığını doğrulayın. Ayrıca, hedef cihazın açık, internete bağlı ve senkronize edilmiş olduğunu doğrulayın. 		Evet
EXECUTION_BACKEND_FAILURE_URL_ROBOTED Sipariş karşılama URL'si, robots.txt veya güvenlik filtreleri tarafından engelleniyor.

Sipariş karşılama uç noktanızın Google'ın tarayıcıları/hizmetleri tarafından erişilebilir olduğundan emin olun. 		Evet
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google, karşılama hizmetinizden bir HTTP 5xx hatası aldı.

Uç nokta URL hizmetinin kararlı, doğru ve herkese açık bir şekilde erişilebilir olduğundan ve hizmetin çalıştığından emin olun. Akıllı ev hizmet günlüklerinizi kontrol etmek için Google Cloud Logging'deki requestId kullanın. Durum denetimleri ve yeniden deneme işlemleri ekleyin. Sunucu kilitlenmelerini, zaman aşımlarını veya 502/503 ağ geçidi hatalarını inceleyin. 		Evet
EXECUTION_BAILOUT_INVALID_RESPONSE JSON yanıtının yapısı çok bozuk olduğundan işlem iptal edildi.

Yanıtınızın Intent şemalarına tam olarak uyduğundan emin olmak için bir JSON doğrulayıcı kullanın. 		Evet
EXECUTION_GAL_BAD_3P_RESPONSE Jeton yanıtındaki geçersiz biçim nedeniyle hesap bağlama işlemi başarısız oldu.

OAuth sunucunuzun yanıt biçiminin Google'ın koşullarına uyduğundan emin olun. 		Evet
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES Kullanıcının hesabı bu işlem için gerekli izinlere sahip değil.

OAuth sırasında istenen kapsamları kontrol edin ve gerekli özelliklerle eşleştiğinden emin olun. 		Evet
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P İş ortağı bulutu, kullanıcının hesabının bağlantısını kaldırdığını belirtir.

agentUserId eşlemenizin kararlı olduğundan ve temizlenmediğinden emin olun. 		Evet
EXECUTION_GAL_NOT_FOUND Kullanıcının Google'da depolanan erişim ve yenileme jetonları geçersiz veya yenilenemiyor. Bu durum, kimlik doğrulamasını ve iş ortağı hizmetine erişimi engelliyor.

Jetonların geçerli ve senkronize olduğundan emin olun, hesap durumu değişikliklerini uygun şekilde yönetin ve jetonların iptal edildiği onaylanırsa kullanıcıların hesabı yeniden bağlamasını zorunlu kılın.
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P Entegrasyon, iş ortağı tarafında salt okunur durumdadır.

Kullanıcının hesabının askıya alınıp alınmadığını veya "salt görüntüleme" bakım modunda olup olmadığını kontrol edin. 		Evet
EXECUTION_GAL_UNLINKED_BY_3P Hesabın bağlantısı, üçüncü taraf hizmeti tarafından proaktif olarak kaldırıldı.

Kullanıcının bağlantısının neden kesildiğini araştırın (ör. güvenlik sıfırlaması). İş ortağının OAuth sunucusunun, Google'ın yeni erişim jetonları yayınlama yönündeki refresh_token isteklerine sorunsuz bir şekilde doğru yanıt verdiğinden emin olun. 		Evet
EXECUTION_INVALID_JSON JSON yanıt yükü Google tarafından ayrıştırılamadı.

Yanıtınızda söz dizimi hataları, eksik parantezler veya geçersiz karakterler olup olmadığını kontrol edin. 		Evet
INVALID_AUTH_TOKEN Google, hizmetinizden bir HTTP 401 hata kodu aldı.

Erişim jetonunun süresi dolmamış ancak hizmetiniz tarafından geçersiz kılınmış. Akıllı ev hizmeti günlüklerinizi kontrol etmek için Google Cloud Logging'deki requestId kullanın.
INVALID_JSON Yanıt yapısı geçersiz (örneğin, zorunlu alanlar eksik).

Yanıtınızı Intent JSON Şemaları'na göre doğrulayın. 		Evet
MALFORMED_JSON JSON yapısı bozuktur (örneğin, kapatılmamış dizeler veya nesneler).

Sipariş karşılama sisteminizin, yanıtları serileştirmek için standart bir JSON kitaplığı kullandığından emin olun. 		Evet
NOT_IMPLEMENTED İstenen intent veya özellik, iş ortağı tarafından uygulanmamıştır.

SYNC yanıtınıza yalnızca tam olarak uyguladığınız özellikleri ekleyin. 		Evet
OPEN_AUTH_FAILURE Kullanıcının erişim jetonunun süresi doldu ve Google bu jetonu yenileyemiyor veya Google, hizmetinizden HTTP 401 hata kodu aldı.

Bu kodun oranında artış görürseniz akıllı ev amaçları veya yenileme jetonu istekleriyle ilgili hataların oranında da artış olup olmadığını kontrol edin.
PARTNER_RESPONSE_INVALID_ERROR_CODE Döndürülen errorCode dizesi Google'ın desteklenenler listesinde yok.

Dahili hatalarınızı Resmi Hata Listesi ile eşleyin. 		Evet
PARTNER_RESPONSE_INVALID_PAYLOAD Yanıttaki payload alanı geçerli bir JSON nesnesi değil.

Sipariş karşılama yanıtınızın kök yapısını doğrulayın. 		Evet
PARTNER_RESPONSE_INVALID_STATUS Yanıt status; SUCCESS, ERROR veya OFFLINE değildi.

Yanıtınızdaki her cihaz sonucunun geçerli bir durum dizesi içerdiğinden emin olun. 		Evet
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Yanıt, istenen tüm komutlar/cihazlar için sonuç içermiyor.

Yanıt yapınızı Google Home geliştirici belgelerine göre doğrulayın. Yanıtın kesilmediğinden veya dahili bir sunucu hatası nedeniyle boş bir gövde döndürmediğinden emin olun. İsteğin commands dizisindeki her öğenin karşılık gelen bir yanıt girişi olmalıdır. 		Evet
PARTNER_RESPONSE_MISSING_DEVICE Google tarafından istenen belirli bir cihaz yanıttan çıkarıldı.

Yanıtınızın, istek yükünde sağlanan her ID öğesini içerdiğinden emin olun. 		Evet
PARTNER_RESPONSE_MISSING_PAYLOAD Yanıtta zorunlu payload alanı eksik.

Üst düzey JSON nesnenizin bir payload anahtarı içerdiğinden emin olun. 		Evet
PARTNER_RESPONSE_NOT_OBJECT Yanıtın tamamı JSON nesnesi olarak ayrıştırılamadı.

HTTP yanıt gövdenizde sondaki karakterleri veya JSON olmayan içeriği kontrol edin. payload.commands[] değerinin kimlikler, durum ve isteğe bağlı durumlar içeren uygun bir JSON nesnesi olduğundan emin olun. 		Evet
REQUEST_ID_NOT_FOUND Google, isteğin dahili izleme kimliğini bulamadı.

Genellikle dahili bir platform hatasıdır. Ani artışları izleyin ve destek ekibiyle iletişime geçin. 		Evet
RESOURCE_UNAVAILABLE İstenen kaynak (cihaz veya özellik) kullanılamıyor.

Cihazın "Meşgul" olup olmadığını veya geçici olarak devre dışı bırakılıp bırakılmadığını kontrol edin. 		Evet
RESPONSE_TIMEOUT Karşılama hizmeti 9 saniye içinde yanıt vermedi.

Arka uç gecikmesini optimize edin; yavaş veritabanı sorguları veya bölgesel ağ gecikmesi olup olmadığını kontrol edin. 		Evet
RESPONSE_UNAVAILABLE İş ortağı karşılama URL'sinden yanıt alınamadı.

Hizmetinizin çalıştığını ve uç noktanın kilitlenmediğini doğrulayın. 		Evet
TIMEOUT Amaç işlenirken genel bir zaman aşımı oluştu.

Bulut ve cihaz merkezleriniz arasındaki dahili hizmet zaman aşımları için günlükleri kontrol edin. 		Evet

Arama Günlükleri

Metrikleri kullanarak entegrasyonlarınızı izleme konusunda deneyim kazandıktan sonraki adım, Cloud Logging kullanarak belirli hataları gidermektir. Hata günlüğü, zaman, hata kodu ve kaynak akıllı ev intent'iyle ilgili ayrıntılar gibi faydalı bilgiler içeren alanlara sahip JSON benzeri bir giriştir.

Google Cloud içinde, projenize her zaman günlük gönderen birden fazla sistem vardır. Günlüklerinizi filtrelemek ve ihtiyacınız olanları bulmak için sorgu yazmanız gerekir. Sorgular Zaman Aralığı, Kaynak, günlük Önem Derecesi veya özel girişleri temel alabilir.

Cloud günlüklerini sorgulama

Özel filtrelerinizi oluşturmak için sorgu düğmelerini kullanabilirsiniz.

Cloud Log 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ığında oluşturulan günlükleri gösterir.

Kaynak belirtmek için Kaynak açılır listesini tıklayın, ardından Google Asistan İşlem Projesi'ni seçin. Bu işlem, projenizden kaynaklanan günlükleri göstermek için sorgunuza 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 yapmak için Logs Explorer bölümündeki Sorgu alanını da kullanabilirsiniz. Bu alan tarafından kullanılan sorgu motoru, dize eşleştirme gibi temel sorguların yanı sıra karşılaştırıcılar (<, >=, !=) ve Boole operatörleri (AND, OR, NOT) gibi daha gelişmiş sorgu türlerini de 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 sorgulamayla ilgili daha fazla örnek için Sorgu Kitaplığı'nı ziyaret edin.

Düzeltmeleri test etme

Hataları tespit edip düzeltmek için güncellemeleri uyguladıktan sonra, düzeltmelerinizi Google Home Test Suite ile kapsamlı bir şekilde test etmenizi öneririz. Test Suite aracının nasıl kullanılacağına dair bir kullanıcı rehberi sunuyoruz. Bu rehber, değişikliklerinizi etkili bir şekilde test etmenize yardımcı olur.

Eğitici Kaynaklar

Bu dokümanda, Akıllı Ev İşleminizdeki hataları giderme adımları yer almaktadır. Hata ayıklama hakkında daha fazla bilgi edinmek için codelab'lerimize de göz atabilirsiniz:

Önceki
Matter ile Cloud Storage