İyi bir kullanıcı deneyimi sağlamak için kodunuzun hataları doğru şekilde işlemesi gerekir. Kullanıcılara, sorunu çözmek için gereken düzeltici adımları özetleyen, işlem yapılabilir hata mesajları sunun.
Bu dokümanda, bağlayıcılarda oluşabilecek hatalar, hata mesajlarının nasıl çalıştığı ve bağlayıcı hatalarının nasıl doğru şekilde ele alınabileceği açıklanmaktadır.
Bilgi: JavaScript'te istisnaları işleme hakkında daha fazla bilgi için try...catch ifadesi bölümüne bakın.
Hata türleri
Bağlayıcınızı kullanırken kullanıcıların karşılaşabileceği hataların türleri ve nedenleri genellikle aşağıdaki üç kategoriden birine girer:
Bağlayıcı dahili ve harici hataları, bağlayıcı geliştiricisi tarafından ele alınmalıdır. Bu hatalar, geliştiricinin yazdığı koddan kaynaklanır.
Bağlayıcı dahili hatası
Bağlayıcı yürütülürken bağlayıcı dahili hataları ortaya çıkar. Örneğin, bir bağlayıcı getData() yürütme sırasında API yanıtını ayrıştıramazsa.
Bu hataların öngörülmesi ve uygun durumlarda kullanıcı dostu açıklamalarla ele alınması gerekir.
Bağlayıcı dahili hatalarının işlenmesi hakkında daha fazla bilgi için Bağlayıcı hatalarını ele almak için en iyi uygulamalar bölümüne bakın.
Bağlayıcı harici hatası
Bağlayıcı yürütüldükten sonra bağlayıcı harici hataları ortaya çıkar. Örneğin, üç alan için yapılan getData() isteği yalnızca iki alana ait verileri döndürdüğünde. Bağlayıcı, yürütme işlemini tamamlamış olsa da Looker Studio isteğini yerine getirmemiştir. Kapsamlı testler bu hataları önleyebilir.
Bağlayıcı harici hataları, genellikle sorunu tanımlamak için hata ayrıntılarının incelenmesi (varsa) ve kodda hata ayıklama yoluyla düzeltilebilir. Bağlayıcınızda hata ayıklama hakkında daha fazla bilgi için Kodunuzda hata ayıklama bölümüne bakın.
Looker Studio hatası
Looker Studio hataları, bağlayıcı kodunuzla ilgili olmayan hatalardır. Örneğin, bir kullanıcı, tarih/saat boyutu olmayan bir veri kaynağına sahip zaman serisi grafiği kullanmaya çalışırsa.
Hata doğrudan bağlayıcıyla ilgili değilse bağlayıcı geliştiricisinin herhangi bir işlem yapması gerekmez. Kullanıcılar Looker Studio Yardım Merkezi'ni ziyaret ederek daha fazla yardım alabilir.
Hata mesajları gösteriliyor
Yönetici durumuna göre hata ayrıntıları gösteriliyor
Bağlayıcı hata verdiğinde Looker Studio, kullanıcının yönetici durumuna göre hata mesajı gösterir.
- Kullanıcı bir yönetici kullanıcıysa tüm ayrıntıları görebilir. Buna hata mesajı, hata türü ve yığın izleme (stack trace) dahildir.
- Kullanıcı, yönetici kullanıcı değilse yalnızca hatada kullanıcı dostu bir mesaj bulunması halinde ayrıntıları görür. Yönetici olmayan kullanıcılara hata mesajları gösterme hakkında daha fazla bilgi edinmek için Kullanıcılara yönelik hataları bildirme başlıklı makaleyi inceleyin.
Kullanıcılara yönelik hataları bildirme
Varsayılan olarak, hata ayrıntılarını yalnızca bağlayıcı yöneticileri görür. Bu, yığın izlemedeki API anahtarı gibi hassas bilgilerin yanlışlıkla ifşa edilmesini önlemeye yardımcı olur. Yönetici olmayan kullanıcılara hata mesajları göstermek için Looker Studio Apps Komut Dosyası hizmetinden newUserError() komutunu kullanın.
Örnek:
try {
// API request that can be malformed.
getDataFromAPI();
} catch (e) {
DataStudioApp.createCommunityConnector()
.newUserError()
.setDebugText('Error fetching data from API. Exception details: ' + e)
.setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
.throwException();
}
Bu örnekte, setText() tüm kullanıcılara gösterilecek metni, setDebugText() ise yalnızca yönetici kullanıcılara gösterilecek metni ayarlar.
Bağlayıcı hatalarını işlemeye yönelik en iyi uygulamalar
Bağlayıcı kodunuzun yürütülmesi sırasında mümkün olduğunca çok sayıda hatayı yakalamaya ve işlemeye çalışmalısınız. Örneğin, hatalara veya istenmeyen bir duruma neden olabilecek bazı yaygın işlemler şunlardır:
- Başarısız URL getirme denemesi (geçici hatalar, zaman aşımları)
- İstenen dönem için veri yok
- API'den gelen veriler ayrıştırılamıyor veya biçimlendirilemiyor
- Yetkilendirme jetonları iptal edildi
Kurtarılabilir hataları ele alma
Başarısız olabilecek ancak kurtarılabilir olan bağlayıcı yürütme noktaları işlenmelidir. Örneğin, bir API isteği önemli olmayan bir nedenle (ör. sunucu yükünün azalması) başarısız olursa hata bildirilmeden önce yeniden denenmelidir.
Hataları yakalama ve gönderme
Düzeltilemeyen hatalar yakalanıp yeniden ele alınmalıdır. Yeniden verilen hata, kullanıcıların hatanın neden oluştuğunu anlamalarına yardımcı olmalıdır. Sorun düzeltilebilirse düzeltici aksiyonla ilgili ayrıntılar verilmelidir.
Kullanıcılara karşılaşılan hataları bildirme bölümünü inceleyin.
Hataları Stackdriver'a kaydet
Hataları ve diğer mesajları günlüğe kaydetmek için Stackdriver'ı kullanın. Bu sayede hataları anlayabilir, sorunları giderebilir ve işlenmemiş istisnaları keşfedebilirsiniz.
Programatik Hata Bildirimi hakkında daha fazla bilgi edinmek, bir komut dosyası için istisna günlük kaydını nasıl etkinleştireceğinizi ve hata ayıklama amacıyla kullanıcıları güvenli bir şekilde tanımlamayı öğrenmek için Stackdriver Logging'i kullanma bölümüne bakın.
KULLANIMDAN KALDIRILDI: Güvenli hata mesajları için DS_USER: önekini kullanın.
Yönetici olmayan kullanıcılara kullanıcı dostu hata mesajları sağlamak için hata mesajlarıyla birlikte DS_USER: önekini ekleyin. Bu önek, yönetici olmayan kullanıcılar için güvenli mesajları tanımlamak için kullanılır ve gerçek hata mesajına dahil edilmez.
Aşağıdaki örneklerde, yönetici olmayan kullanıcılara bir hata mesajının gösterildiği ve bir hata mesajının yalnızca yönetici kullanıcılara gösterildiği bir durum mevcuttur: