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 sorunların hata ayıklamasını yapmanıza olanak tanıyan araçlar sunar. Kullanıcı amaçları yerine getirilirken bir hata oluştuğunda Google Home Analytics ardışık düzeni, bu hatayı metriklerinize kaydeder ve proje günlüklerinize 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.

Hataları izleme

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

  • Başarı oranı grafiği, projelerinizin güvenilirliğini izlerken başlangıç noktası olarak kullanacağınız ilk grafiktir. Bu grafikteki düşüşler, kullanıcı tabanınızın bir bölümünde veya tamamında kesinti olduğunu gösterebilir. Projenizde yapılan her değişiklik veya güncellemeden sonra bu grafikteki düzensizlikleri yakından izlemenizi öneririz.
  • Hata Dökümü 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 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ı

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 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 Yapılacaklar Listesi
AGENT_ISSUE İş ortağının bulut aracısında genel bir sorun oluştu.

Karşılanmayan istisnalar veya kilitlenmeler için karşılama günlüklerinizi kontrol edin. 		Evet
AGENT_UNAVAILABLE_ERROR Google, iş ortağının istek karşılama URL'sine ulaşamadı.

Sunucunuzun çevrimiçi olduğundan, güvenlik duvarının Google'ı engellemediğinden ve URL'nin doğru olduğundan emin olun. 		Evet
BACKEND_FAILURE_URL_TIMEOUT Google'ın hizmetinize ulaşmaya çalışırken yaptığı istek zaman aşımına uğradı.

Hizmetinizin çevrimiçi olduğunu, bağlantı kabul ettiğini ve kapasiteyi aşmadığını doğrulayın. Ayrıca, hedef cihazın açık, internete bağlı ve senkronize edilmiş olduğunu doğrulayın.
BACKEND_FAILURE_URL_UNREACHABLE Google, hizmetinizden bir HTTP 5xx hata kodu aldı.

Akıllı ev hizmeti günlüklerinizi kontrol etmek için Google Cloud Logging'de requestId simgesini kullanın. Sunucu kilitlenmelerini, zaman aşımlarını veya 502/503 ağ geçidi hatalarını araştırın.
COMMAND_FAILED Bir komutun yürütülmesi sırasında genel bir hata oluştu.

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

403, 404 veya 400 yanıtları için web sunucusu günlüklerinizi kontrol edin. 		Evet
EXECUTION_BACKEND_FAILURE_URL_ROBOTED Karşılama URL'si, robots.txt veya güvenlik filtreleri tarafından engelleniyor.

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 olarak erişilebilir olduğundan ve hizmetin çalıştığından emin olun. Durum denetimleri ve yeniden deneme işleme özelliği ekleyin. Sunucu kilitlenmelerini, zaman aşımlarını veya 502/503 ağ geçidi hatalarını araştırın. 		Evet
EXECUTION_BAILOUT_INVALID_RESPONSE JSON yanıtı o kadar hatalıydı ki işleme sonlandırıldı.

Yanıtınızın, Amaç şemalarına tamamen uygun olduğ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ıyla eşleştiğini doğrulayın. 		Evet
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES Kullanıcının hesabında bu işlem için gerekli izinler yok.

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 Google'da depolanan kullanıcının erişim ve yenileme jetonları geçersiz veya yenilenemiyor. Bu durum, kimlik doğrulama ve iş ortağı hizmetine erişimi engelliyor.

Jetonların geçerli ve senkronize kalmasını sağlayın, hesap durumu değişikliklerini uygun şekilde ele alın ve jetonların iptal edildiği doğrulanırsa kullanıcıların hesabı yeniden bağlamasını zorunlu kılın. 		Evet
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ınmış veya "yalnızca 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ılmıştır.

Kullanıcının bağlantısının neden kesildiğini araştırın (örneğin, güvenlik sıfırlaması). İş ortağının OAuth sunucusunun, Google'ın yeni erişim jetonları verme 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 hatası, eksik parantez veya geçersiz karakter olup olmadığını kontrol edin. 		Evet
INVALID_AUTH_TOKEN Google, hizmetinizden bir HTTP 401 hata kodu aldı.

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

Yanıtınızı Amaç JSON Şemaları ile doğrulayın. 		Evet
MALFORMED_JSON JSON yapısı bozuk (örneğin, kapatılmamış dizeler veya nesneler).

Yanıtları serileştirmek için istek karşılama işleminizde standart bir JSON kitaplığı kullanıldığından emin olun. 		Evet
NOT_IMPLEMENTED İstenen amaç 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 dolmuş ve Google bunu yenileyemiyor ya da Google, hizmetinizden bir HTTP 401 hata kodu almış.

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 desteklenen listesinde yer almıyor.

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

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çermiyordu.

Yanıt yapınızı Google Home geliştirici dokümanlarına göre doğrulayın. Yanıtın kesilmediğinden veya dahili 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[] öğesinin kimlikler, durum ve isteğe bağlı durumlar içeren uygun bir JSON nesnesi olduğundan emin olun. 		Evet
REQUEST_ID_NOT_FOUND Google, istek iç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 İstek karşılama hizmeti 9 saniye içinde yanıt vermedi.

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

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.

Bulutunuz ile cihaz hub'larınız arasındaki dahili hizmet zaman aşımlarıyla ilgili günlükleri kontrol edin. 		Evet

Arama Günlükleri

Metrikleri kullanarak entegrasyonlarınızı izleme konusunda rahat hissetmeye başladığınızda bir sonraki adım, Cloud Logging kullanarak belirli hataları gidermektir. Hata günlüğü, JSON benzeri bir giriş olup zaman, hata kodu ve kaynak akıllı ev niyetiyle ilgili ayrıntılar gibi faydalı bilgiler içeren alanlara sahiptir.

Google Cloud içinde, günlükleri projenize her zaman gönderen birden fazla sistem vardır. Günlüklerinizi filtrelemek için sorgular yazmanız ve ihtiyacınız olanları bulmanız gerekir. Sorgular Zaman Aralığı, Kaynak, günlük Önem Derecesi veya özel girişlere göre yapılabilir.

Cloud günlüklerini sorgulama

Özel filtrelerinizi oluşturmanıza yardımcı olması 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 sağlanan seçeneklerden birini belirleyin. Bu işlem, günlükleri filtreleyerek seçilen zaman aralığında oluşturulanları gösterir.

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

Önem derecesi düğmesini kullanarak Acil, Bilgi, Hata ayıklama ve diğer önem derecesi günlük düzeylerine göre filtreleme yapın.

Ayrıca, Logs Explorer bölümündeki Sorgu alanını kullanarak özel girişler de girebilirsiniz. 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) dahil olmak üzere 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üklere etkili bir şekilde sorgu göndermeyle ilgili daha fazla örnek bulmak için Sorgu Kitaplığı'nı ziyaret edin.

Düzeltmeleri Test Etme

Hataları belirleyip düzeltmek için güncellemeleri uyguladıktan sonra düzeltmelerinizi Google Home Test Suite ile kapsamlı bir şekilde test etmenizi öneririz. Test Suite'ı kullanma konusunda, değişikliklerinizi etkili bir şekilde test etme sürecinde size yol gösterecek bir kullanıcı kılavuzu sunuyoruz.

Eğitici Kaynaklar

Bu belgede, akıllı ev işleminizdeki hataları giderme adımları açıklanmaktadır. Hata ayıklama hakkında daha fazla bilgi edinmek için codelab'lerimize de göz atabilirsiniz:

Önceki
Matter ile Cloud Storage