Yüklenebilir Tetikleyiciler

Basit tetikleyiciler gibi, yüklenebilir tetikleyiciler de belirli bir etkinlik (ör. doküman açma) gerçekleştiğinde Google Apps Komut Dosyası'nın bir işlevi otomatik olarak çalıştırmasına olanak tanır. Ancak yüklenebilir tetikleyiciler, basit tetikleyicilere kıyasla daha fazla esneklik sunar: Yetkilendirme gerektiren hizmetleri çağırabilir, zamana dayalı (saat) tetikleyiciler de dahil olmak üzere çeşitli ek etkinlik türleri sunar ve programatik olarak kontrol edilebilir. Hem basit hem de yüklenebilir tetikleyiciler için Apps Komut Dosyası, tetiklenen işleve, etkinliğin gerçekleştiği bağlamla ilgili bilgileri içeren bir etkinlik nesnesi iletir.

Eklentilerde tetikleyicileri kullanma hakkında daha fazla bilgi için Google Workspace eklentileri için tetikleyiciler başlıklı makaleyi inceleyin.

Kısıtlamalar

Yüklenebilir tetikleyiciler, basit tetikleyicilere kıyasla daha fazla esneklik sunsa da birkaç kısıtlamaya tabidir:

  • Bir dosya salt okunur (görüntüleme veya yorum yapma) modunda açılırsa çalışmazlar. Bağımsız komut dosyalarında tetikleyicilerin düzgün çalışması için kullanıcıların komut dosyası dosyasına en azından görüntüleme erişimine sahip olması gerekir.

  • Komut dosyası yürütmeleri ve API istekleri, tetikleyicilerin çalışmasına neden olmaz. Örneğin, yeni bir form yanıtı göndermek için FormResponse.submit() işlevini çağırmak, formun gönderme tetikleyicisinin çalışmasına neden olmaz.

    Bu kısıtlamanın istisnası Form.submitGrades()'dır. Kodunuz onFormSubmit tetikleyicisini kullanıyorsa Form.submitGrades() tetikleyicisini çağırmak onFormSubmit koşulunu tetikler ve sonsuz döngüye neden olur. Sonsuz döngüyü önlemek için submitGrades() işlevi çağrılmadan önce notların mevcut olup olmadığını kontrol eden bir kod ekleyin.

  • Yüklenebilir tetikleyiciler her zaman bunları oluşturan kişinin hesabında çalışır. Örneğin, yüklenebilir bir açık tetikleyici oluşturursanız bu tetikleyici, iş arkadaşınız dokümanı açtığında (iş arkadaşınızın düzenleme erişimi varsa) çalışır ancak hesabınızla çalışır. Bu nedenle, bir doküman açıldığında e-posta gönderme tetikleyicisi oluşturursanız e-posta her zaman dokümanı açan hesaptan değil, sizin hesabınızdan gönderilir. Ancak her hesap için yüklenebilir bir tetikleyici oluşturabilirsiniz. Bu durumda her hesaptan bir e-posta gönderilir.

  • Belirli bir hesap, ikinci bir hesaptan yüklenen tetikleyicileri göremez. Ancak ilk hesap bu tetikleyicileri etkinleştirmeye devam edebilir.

  • Yüklenebilir tetikleyiciler, Apps Komut Dosyası tetikleyici kota sınırlarına tabidir.

Zamana dayalı tetikleyiciler

Zamana dayalı tetikleyici (saat tetikleyici olarak da adlandırılır), Unix'teki cron işine benzer. Zamana dayalı tetikleyiciler, komut dosyalarının belirli bir zamanda veya düzenli aralıklarla (ör. her dakika veya ayda bir) yürütülmesini sağlar. (Bir eklenti, zamana dayalı tetikleyiciyi en fazla saatte bir kez kullanabilir.) Saat biraz rastgele olabilir. Örneğin, tekrar eden bir 09:00 tetikleyicisi oluşturursanız Apps Komut Dosyası 09:00 ile 10:00 arasında bir saat seçer ve tetikleyici tekrar çalışmadan önce 24 saat geçmesi için bu zamanlamayı günden güne tutarlı tutar.

Etkinliğe dayalı tetikleyiciler

Yüklenebilir etkinliğe dayalı tetikleyiciler, kavramsal olarak onOpen() gibi basit tetikleyicilere benzer ancak ek etkinliklere yanıt verebilir ve farklı şekilde davranırlar.

Örneğin, Google E-Tablolar için yüklenebilir açık tetikleyici, basit onOpen() tetikleyicisi gibi, e-tablo düzenleme erişimi olan herhangi bir kullanıcı tarafından açıldığında etkinleşir. Ancak yüklenebilir sürüm, yetkilendirme gerektiren hizmetleri çağırabilir. Yüklenebilir sürüm, e-tabloyu düzenleme erişimine sahip başka bir kullanıcı açsa bile tetikleyiciyi oluşturan kullanıcının yetkilendirmesiyle çalışır.

Google Workspace uygulamaları için yüklenebilir çeşitli tetikleyiciler vardır:

  • Yüklenebilir bir açma tetikleyicisi, kullanıcının düzenleme izni olan bir e-tablo, doküman veya formu açtığında çalışır.
  • Kullanıcı bir e-tablodaki değeri değiştirdiğinde yüklenebilir bir düzenleme tetikleyicisi çalışır.
  • Yüklenebilir bir değişiklik tetikleyicisi, bir kullanıcı e-tablonun yapısını değiştirdiğinde (ör. yeni bir sayfa ekleyerek veya bir sütunu kaldırarak) çalışır.
  • Kullanıcı bir forma yanıt verdiğinde yüklenebilir bir form gönderme tetikleyicisi çalışır. Form gönderme tetikleyicisinin iki sürümü vardır: Biri Google Formlar'ın kendisi için, diğeri ise form bir e-tabloya gönderiliyorsa E-Tablolar için.
  • Yüklenebilir takvim etkinliği tetikleyicisi, kullanıcının takvim etkinlikleri güncellendiğinde (oluşturulduğunda, düzenlendiğinde veya silindiğinde) çalışır.

Yüklenebilir tetikleyiciler, bağımsız ve bağlı komut dosyalarında kullanılabilir. Örneğin, bağımsız bir komut dosyası, TriggerBuilder.forSpreadsheet(key) işlevini çağırıp e-tablonun kimliğini ileterek rastgele bir Google E-Tablolar dosyası için programatik olarak yüklenebilir bir tetikleyici oluşturabilir.

Tetikleyicileri manuel olarak yönetme

Komut dosyası düzenleyicide manuel olarak yüklenebilir bir tetikleyici oluşturmak için aşağıdaki adımları uygulayın:

  1. Apps Komut Dosyası projenizi açın.
  2. Sol tarafta Tetikleyiciler'i tıklayın.
  3. Sağ altta Tetikleyici Ekle'yi tıklayın.
  4. Oluşturmak istediğiniz tetikleyici türünü seçin ve yapılandırın.
  5. Kaydet'i tıklayın.

Tetikleyicileri programatik olarak yönetme

Script hizmeti ile tetikleyicileri programatik olarak oluşturma ve silme. ScriptApp.newTrigger(functionName) işlevini çağırarak başlayın. Bu işlev, TriggerBuilder değerini döndürür.

Aşağıdaki örnekte, iki zamana dayalı tetikleyicinin nasıl oluşturulacağı gösterilmektedir. Bu tetikleyicilerden biri her 6 saatte bir, diğeri ise her pazartesi saat 09:00'da (komut dosyanızın ayarlandığı saat diliminde) etkinleşir.

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger("myFunction").timeBased().everyHours(6).create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger("myFunction")
    .timeBased()
    .onWeekDay(ScriptApp.WeekDay.MONDAY)
    .atHour(9)
    .create();
}

Bir sonraki örnekte, e-tablo için yüklenebilir bir açık tetikleyicinin nasıl oluşturulacağı gösterilmektedir. Basit bir onOpen() tetikleyicinin aksine, yüklenebilir tetikleyicinin komut dosyasının e-tabloya bağlanması gerekmez. Bu tetikleyiciyi bağımsız bir komut dosyasından oluşturmak için SpreadsheetApp.getActive() yerine SpreadsheetApp.openById(id) çağrısı ekleyin.

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger("myFunction").forSpreadsheet(ss).onOpen().create();
}

Mevcut bir yüklenebilir tetikleyiciyi programatik olarak değiştirmek için tetikleyiciyi silip yeni bir tetikleyici oluşturmanız gerekir. Daha önce bir tetikleyicinin kimliğini sakladıysanız aşağıdaki işleve kimliği bağımsız değişken olarak ileterek bu kimliği silin.

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Tetikleyici oluşturmadan önce, ilişkili işlevin gerekli tüm OAuth izinlerine sahip olduğunu doğrulayın.

Tetikleyicilerdeki hatalar

Yüklenebilir bir tetikleyici etkinleştirildiğinde ancak işlev bir istisna oluşturduğunda veya başka bir şekilde başarıyla çalışmadığında ekranınızda hata mesajı görünmez. Sonuçta, zamana dayalı bir tetikleyici çalıştığında veya başka bir kullanıcı form gönderme tetikleyicinizi etkinleştirdiğinde bilgisayarınızın başında olmayabilirsiniz.

Bunun yerine Apps Komut Dosyası, aşağıdaki gibi bir e-posta gönderir:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

E-postada tetikleyiciyi devre dışı bırakmak veya yeniden yapılandırmak için bir bağlantı yer alır. Komut dosyası bir Google E-Tablolar, Dokümanlar veya Formlar dosyasına bağlıysa e-postada bu dosyanın bağlantısı da yer alır. Bu bağlantılar, tetikleyiciyi devre dışı bırakmanıza veya komut dosyasını düzenleyerek hatayı düzeltmenize olanak tanır.

Senaryonuzdaki hataları gidermek için bildirim e-postasındaki bağlantıyı tıklayarak senaryo projenizi açın. Proje açıldıktan sonra sol gezinme panelinde Yürütmeler'i tıklayarak yürütme günlüklerini görüntüleyin. Günlükler, hangi yürütmelerin başarısız olduğunu gösterir ve sorunu teşhis edip düzeltmenize yardımcı olmak için hata mesajları içerir.

Eklentiler tarafından oluşturulan yüklenebilir tetikleyiciler, kullanıcılara bu e-posta bildirimlerini göndermez.

Google Hesabınızla ilişkili tüm tetikleyicileri incelemek ve artık ihtiyacınız olmayan tetikleyicileri devre dışı bırakmak için aşağıdaki adımları uygulayın:

  1. script.google.com adresine gidin.
  2. Sol tarafta Tetikleyicilerim'i tıklayın.
  3. Bir tetikleyiciyi silmek için tetikleyicinin sağ tarafında Diğer > Tetikleyiciyi sil'i tıklayın.

Bir tetikleyici devre dışı bırakılırsa ilgili hata bildirimleri de devre dışı bırakılır. Hata bildirimleri, etkin bir tetikleyicinin doğal bir parçasıdır. Dolayısıyla, belirli bir tetikleyiciyle ilgili tüm hata bildirimlerini almayı durdurmak için tetikleyiciyi devre dışı bırakın veya silin. Bir tetikleyici etkin durumdayken yalnızca bu bildirimlerin sıklığını ayarlayabilirsiniz.

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

Eklentilerdeki tetikleyiciler

Eklentilerde, yüklenebilir tetikleyicilere ek olarak manifest tetikleyicileri kullanın. Daha fazla bilgi için Google Workspace eklentileri için tetikleyiciler başlıklı makaleyi inceleyin.