Matter entegrasyon sorunlarını giderme

yenileme_tarihi: 06.01.2023

Google Cloud, Google Cloud Monitoring ile projelerinizin güvenilirliğini izleyebileceğiniz ve Google Cloud Logging hata günlükleri ile sorunları ayıklayabileceğiniz araçlar sunar. Kullanıcıların amaçları yerine getirilirken bir hata oluştuğunda Google Home Analytics ardışık düzeni, metriklerinizde bu hatayı kaydeder ve proje günlüklerinizde bir hata günlüğü yayınlar.

Hatalarınızı iki adımda giderebilirsiniz:

  1. Akıllı ev metrikleriyle projelerinizin durumunu izleyin.
  2. Hata günlüklerindeki ayrıntılı hata açıklamalarını kontrol ederek sorunları araştırın.

İzleme hataları

Proje metriklerinize erişmek için Google Cloud Monitoring dashboard kullanabilirsiniz. Özellikle kaliteyi izlemek ve hata ayıklamak için kullanışlı olan bazı temel grafikler vardır:

  • Başarı Oranı grafiği, projelerinizin güvenilirliğini izlediğinizden başlayabileceğiniz ilk grafiktir. Bu grafikteki düşüşler, kullanıcı tabanınızın bir kısmında veya tamamında kesinti olduğunu gösterebilir. Projenizde yaptığınız her değişiklik veya güncellemeden sonra düzensizlikler olup olmadığını görmek için bu grafiği yakından izlemenizi öneririz.
  • Hata Dökümü grafikleri, en çok entegrasyonlarınızdaki sorunları gidermek için yararlıdır. Başarı yüzdesi grafiğinizde vurgulanan her hata için hata dökümünüzde bir hata kodu görüntülenir. Google Home platform tarafından işaretlenen hataları ve bunları nasıl gidereceğinizi aşağıdaki tabloda görebilirsiniz.

Platform Hata Kodları

Google Home platform tarafından yakalanan sorunları tanımlamak için proje günlüklerinizde görebileceğiniz yaygın hata kodlarından bazılarını burada bulabilirsiniz. Sorun giderme bilgileri için lütfen aşağıdaki tabloya göz atın.

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

Akıllı ev hizmeti günlüklerinizi kontrol etmek için GCP Logging'de requestId kullanın.
BACKEND_FAILURE_URL_TIMEOUT Hizmetinize ulaşmaya çalışırken Google'ın isteği zaman aşımına uğradı.

Hizmetinizin internete bağlı olduğunu, bağlantı kabul ettiğini ve kapasitenin üzerinde olmadığını doğrulayın. Ayrıca, hedef cihazın açık, çevrimiçi ve senkronize olduğundan emin olun.
BACKEND_FAILURE_URL_UNREACHABLE Google, hizmetinizden bir HTTP 5xx hata kodu aldı.

Akıllı ev hizmeti günlüklerinizi kontrol etmek için GCP Logging'de requestId kullanın.
DEVICE_NOT_FOUND Cihaz, iş ortağı hizmeti tarafında mevcut değil.

Bu, normalde veri senkronizasyonunda bir hata veya yarış koşulunun bulunduğunu gösterir.
GAL_BAD_3P_RESPONSE Google, geçersiz biçim veya yükteki değerler nedeniyle hesap bağlama hizmetinizden gelen yanıtı ayrıştıramıyor.

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

GCP Logging'de bu hatada artışla karşılaşırsanız daha fazla bilgi için bizimle iletişime geçin.
GAL_INVALID_ARGUMENT Google, erişim jetonu almaya çalışırken Google dahili bir hatası oluştu.

GCP Logging'de bu hatada artışla karşılaşırsanız daha fazla bilgi için bizimle iletişime geçin.
GAL_NOT_FOUND Kullanıcının Google'da depolanan erişim jetonları ve yenileme jetonları geçersiz kılınır ve artık yenilenemez. Hizmetinizi kullanmaya devam edebilmek için kullanıcının hesabını yeniden bağlaması gerekir.

GCP Logging'de bu hatada artışla karşılaşırsanız daha fazla bilgi için bizimle iletişime geçin.
GAL_PERMISSION_DENIED Jeton paylaşımı yetkilendirilmediğinde Google dahili bir hata oluştu.

GCP Logging'de bu hatada artışla karşılaşırsanız daha fazla bilgi için bizimle iletişime geçin.
GAL_REFRESH_IN_PROGRESS Kullanıcının erişim jetonunun süresi doldu ve jetonu yenilemek için eş zamanlı başka bir deneme devam ediyor.

Bu bir sorun değildir ve herhangi bir işlem yapmanız gerekmez.
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ındı. GCP Logging'de requestId kullanarak akıllı ev hizmeti günlüklerinizi kontrol edin.
INVALID_JSON JSON yanıtı ayrıştırılamıyor veya anlaşılamıyor.

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 jetonu yenileyemiyor veya Google, hizmetinizden HTTP 401 hata kodu aldı.

Bu kodun oranı artarsa akıllı ev amaçları veya yenileme jetonu istekleriyle ilgili hata oranında da artış görüp görmediğinizi kontrol edin.
PARTNER_RESPONSE_INVALID_ERROR_CODE Yanıt tanınmayan bir hata kodu gösteriyor.

İstek yanıtınızda bir hata varsa desteklenen hata kodlarımızda sağlanan bir yanıtı kullandığınızdan emin olun.
PARTNER_RESPONSE_INVALID_PAYLOAD Yanıt payload alanı JSON Nesnesi olarak ayrıştırılamıyor.

İstek yanıtınızdaki yük alanının eşleşen parantezlere sahip olup olmadığını ve JSON alanı olarak doğru bir şekilde yapılandırılıp yapılandırılmadığını kontrol edin.
PARTNER_RESPONSE_INVALID_STATUS Yanıt bir durum göstermiyor veya yanlış bir durumu gösteriyor.

Amaç yerine getirme isteklerine verilen yanıtlar SUCCESS, OFFLINE, ERROR, EXCEPTIONS ile birlikte bir durum göstermelidir. Hataları ve istisnaları işleme hakkında daha fazla bilgi edinebilirsiniz.
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES İstekteki bir veya daha fazla amaç yanıtta eksik.

Yürütme yanıtınızın doğru şekilde yapılandırıldığından ve istekteki tüm amaçlara ait sonuçların yanıtınızda yer aldığını doğrulayın.
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ğunu doğrulayın.
PARTNER_RESPONSE_MISSING_PAYLOAD Yanıt bir payload alanı içermiyor.

İstek yanıtınıza 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ılamıyor.

İstek yanıtınızdaki tüm alanlarda istenmeyen karakterler, eşleşmeyen parantezler veya biçimlendirme hataları olup olmadığını kontrol edin. Bazı Unicode karakterleri desteklenmeyebilir. Yanıtınızın doğru bir JSON nesnesi olarak yapılandırıldığından da emin olun.
PROTOCOL_ERROR İstek yerine getirilemedi.

Akıllı ev hizmeti günlüklerinizi kontrol etmek için Google Cloud Logging'de 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, isteğin gönderildiği andan itibaren 9 saniyedir. Bu süre içinde yanıt gönderdiğinizden emin olun.
RESPONSE_UNAVAILABLE Yanıt alınmıyor veya yanıtta durum belirtilmiyor.

Amacı yerine getirme isteklerine verilen yanıtlar akıllı ev belgelerine göre yapılandırılmalı ve durumu belirtmelidir.
TRANSIENT_ERROR Geçici hata, kendi kendine çözülecek bir hatadır.

Bu hatalar genellikle bağlantısı kesilen bir cihaz veya hizmetle ilgili olarak ortaya çıkar. Ayrıca, bir sunucuya yönelik yeni bağlantılar açılamıyorsa.

Arama Günlükleri

Metrikleri kullanarak entegrasyonlarınızı izlemeye alıştıktan sonra Cloud Logging kullanarak belirli hataları gidermeniz gerekir. Hata günlüğü; zaman, hata kodu ve kaynak akıllı ev amacıyla ilgili ayrıntılar gibi yararlı bilgiler içeren alanlar içeren JSON benzeri bir giriştir.

Google Cloud içinde, günlükleri her zaman projenize 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şleri temel alabilir.

Bulut Günlüklerini Sorgula

Ö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 sunulan seçeneklerden birini belirleyin. Bu işlem, günlükleri filtreler ve seçilen zaman aralığında olan günlükleri gösterir.

Kaynak belirtmek için Kaynak açılır listesini tıklayın ve Google Asistan İşlem Projesi'ni seçin. Böylece, sorgunuza projenizden kaynaklanan günlükleri gösteren bir filtre eklenir.

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

Özel girişler girmek için Logs Explorer içindeki 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) dahil olmak üzere daha gelişmiş sorgu türlerini destekler.

Örneğin, aşağıdaki özel giriş LIGHT cihaz türünden gelen 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 şekilde sorgulamayla ilgili daha fazla örnek için Sorgu Kitaplığı'nı ziyaret edin.

Test Düzeltmeleri

Hataları tanımladıktan ve düzeltmek için güncellemeleri uyguladıktan sonra, düzeltmelerinizi Google Home Test Suite ile kapsamlı bir şekilde test etmenizi öneririz. Değişikliklerinizi etkili bir şekilde test etme konusunda size yol gösteren bir Test Suite kullanıcı rehberi sağlıyoruz.

Eğitici Kaynaklar

Bu belgede, Akıllı Ev İşleminizdeki hataları giderme adımları açıklanmaktadır. Hata ayıklama hakkında daha fazla bilgi edinmek için codelab'lerimizi de inceleyebilirsiniz:

Önceki
Matter ile Cloud Storage