Topluluk Bağlayıcıları için hata işleme ve iletiler

İyi bir kullanıcı deneyimi sağlamak için kodunuz hataları doğru şekilde işlemelidir. Kullanıcılara, sorunu çözmek için düzeltici adımları özetleyen, işlem yapılabilir hata mesajları gösterin.

Bu belgede, bağlayıcılarla ilgili olabilecek hatalar, hata mesajlarının işleyiş şekli ve bağlayıcı hatalarının nasıl düzgün şekilde ele alınacağı açıklanmaktadır.

Bilgi: JavaScript'te istisnaları işleme hakkında daha fazla bilgi edinmek için try...catch ifadesi konusuna bakın.

Hata türleri

Kullanıcının bağlayıcınızı kullanırken karşılaşabileceği hata türleri ve nedenleri genellikle aşağıdaki üç kategoriden birine girer:

  1. bağlayıcı dahili hataları
  2. bağlayıcı harici hataları
  3. Looker Studio hataları

Bağlayıcıdaki dahili ve harici hatalar, bağlayıcı geliştiricisi tarafından ele alınmalıdır. Bu hatalar, geliştiriciler tarafından yazılan kodlardan kaynaklanır.

Bağlayıcı dahili hatası

Bağlayıcı yürütülürken dahili bağlayıcı hataları oluşur. Örneğin, bir bağlayıcı getData() yürütülürken bir API yanıtını ayrıştıramıyorsa. Bu hatalar öngörülmeli ve uygun olduğu durumlarda kullanıcı dostu açıklamalarla ele alınmalıdır.

Bağlayıcı dahili hatalarını ele alma hakkında daha fazla bilgi için Bağlayıcı hatalarını ele alma ile ilgili en iyi uygulamalar başlıklı makaleyi inceleyin.

Bağlayıcı harici hatası

Bağlayıcı harici hataları, bağlayıcı yürütüldükten sonra oluşur. Örneğin, üç alan için yapılan bir getData() isteği yalnızca iki alanın verilerini döndürdüğünde. Bağlayıcı yürütmeyi tamamlamış olsa da Looker Studio'nun isteğini karşılamadı. Kapsamlı testler bu hataları önleyebilir.

Bağlayıcı harici hataları genellikle hata ayrıntılarını (varsa) inceleyip sorunu belirlemek için kodda hata ayıklayarak düzeltebilirsiniz. Bağlayıcınızda hata ayıklama hakkında daha fazla bilgi için Kodunuzda hata ayıklama başlıklı makaleyi inceleyin.

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ğıyla zaman serisi grafiği kullanmaya çalıştığında.

Hata doğrudan bağlayıcıyla ilgili değilse bağlayıcı geliştiricisinin yapması gereken bir işlem yoktur. Kullanıcılar, Looker Studio Yardım Merkezi'ni ziyaret ederek ek yardım alabilir.

Hata mesajlarını gösterme

Yönetici durumuna göre hata ayrıntılarını gösterme

Bir bağlayıcı hata verdiğinde Looker Studio, kullanıcının yönetici durumuna bağlı olarak hata mesajını gösterir.

  • Kullanıcı bir yönetici kullanıcısıysa tüm ayrıntıları görür. Hata mesajı, hata türü ve yığın izleme bu kapsamdadır.
  • Kullanıcı yönetici kullanıcısı değilse yalnızca hata kullanıcı dostu bir mesaj içeriyorsa 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ıya yönelik hatalar oluşturma başlıklı makaleyi inceleyin.

Kullanıcıya yönelik hatalar oluşturma

Varsayılan olarak, yalnızca bağlayıcı yöneticileri hata ayrıntılarını görür. Bu, yığın izlemede 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ı hizmetindeki newUserError() işlevini 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ı ele alma ile ilgili en iyi uygulamalar

Bağlayıcı kodunuzun yürütülmesi sırasında mümkün olduğunca çok hata 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 girişimi (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ı işleme

Başarısız olabilecek ancak kurtarılabilir olan bağlayıcı yürütme noktaları ele alınmalıdır. Örneğin, bir API isteği ölümcül olmayan bir nedenden (ör. sunucu yükü azaltma) dolayı başarısız olursa hata vermeden önce yeniden denenmelidir.

Hataları yakalama ve atma

Kurtarılamayan hatalar yakalanmalı ve yeniden oluşturulmalıdır. Yeniden oluşturulan hata, kullanıcıların hatanın neden oluştuğunu anlamasına yardımcı olmalıdır. Sorun düzeltilebiliyorsa düzeltici işlemle ilgili ayrıntılar sağlanmalıdır.

Kullanıcıya yönelik hatalar bölümüne bakın.

Hataları Stackdriver'a kaydetme

Hataları ve diğer mesajları kaydetmek için Stackdriver'ı kullanın. Bu, hataları anlamanıza, sorunları ayıklamanıza ve işlenmemiş istisnaları keşfetmenize yardımcı olur.

Stackdriver Error Reporting, bir komut dosyası için istisna günlüğünü etkinleştirme ve hata ayıklama amacıyla kullanıcıları güvenli bir şekilde tanımlama hakkında daha fazla bilgi edinmek için Stackdriver Logging'i Kullanma başlıklı makaleyi inceleyin.

DEPRECATED: Use DS_USER: prefix for safe error messages

Yönetici olmayan kullanıcılara kullanıcı dostu hata mesajları sağlamak için hata mesajlarına DS_USER: önekini ekleyin. Bu önek, yönetici olmayan kullanıcılar için güvenli mesajları tanımlamak amacıyla kullanılır ve gerçek hata mesajına dahil edilmez.

Aşağıdaki örneklerde, hata mesajının yönetici olmayan kullanıcılara gösterileceği bir durum ve hata mesajının yalnızca yönetici kullanıcılara gösterileceği başka bir durum yer almaktadır:

data-studio/errors.gs
// Admin and non-admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('DS_USER:This will be shown to admin & non-admin.');
}

// Only admin users will see the following error.
try {
  // Code that might fail.
} catch (e) {
  throw new Error('This message will only be shown to admin users');
}