Düzenleyici eklentileri için tetikleyiciler

Apps Script tetikleyicileri, belirli bir etkinlik gerçekleştiğinde belirtilen bir komut dosyası işlevinin (tetikleyici işlevi) yürütülmesine neden olur. Yalnızca belirli etkinlikler tetikleyicilerin tetiklenmesine neden olabilir ve her Google Workspace uygulaması farklı bir etkinlik grubunu destekler.

Bir tetikleyici tetiklendiğinde bir etkinlik nesnesi oluşturulur. Bu JSON yapısı, gerçekleşen etkinlikle ilgili ayrıntıları içerir. Etkinlik nesnesi yapısındaki bilgiler, tetikleyici türüne göre farklı şekilde düzenlenir.

Etkinlik nesnesi oluşturulduktan sonra Apps Script, tetikleyici işlevine parametre olarak iletir. Tetikleyici işlevi, etkinliğe yanıt vermek için uygun işlemleri yapmak üzere kendiniz uygulamanız gereken bir geri çağırma işlevidir. Örneğin, bir Düzenleyici eklentisinde, bir doküman açıldığında eklenti menü öğeleri oluşturmak için tetikleyici kullanılır. Bu durumda, eklentinin ihtiyaç duyduğu menü öğelerini oluşturmak için onOpen(e) tetikleyici işlevini (muhtemelen etkinlik nesnesinde bulunan verileri kullanarak) uygularsınız.

Bu sayfada, düzenleyici eklenti projelerinde tetikleyicilerin kullanımıyla ilgili kurallar sağlanmaktadır.

Düzenleyici eklentisi tetikleyici türleri

Düzenleyici eklentilerinde, Apps Komut Dosyası projelerinde kullanılabilen genel tetikleyici türlerinin çoğunu (basit tetikleyiciler ve çoğu yüklenebilir tetikleyici dahil) kullanabilirsiniz. Kullanılabilir tetikleyici türlerinin tam listesi, genişletilen uygulamaya bağlıdır.

Aşağıdaki tabloda, Düzenleyici eklentilerinin kullanabileceği basit ve yüklenebilir tetikleyici türleri gösterilmekte ve ilgili etkinlik nesnelerinin bağlantıları sağlanmaktadır:

Etkinlik Etkinlik nesnesi Basit tetikleyiciler Yüklenebilir tetikleyiciler
Aç
Düzenleyici dosyası açılır.		 Dokümanlar onOpen etkinlik nesnesi
Formlar onOpen etkinlik nesnesi
E-Tablolar onOpen etkinlik nesnesi
Slaytlar onOpen etkinlik nesnesi 		Dokümanlar
Formlar*
E-Tablolar
Slaytlar

function onOpen(e)

 Dokümanlar
Formlar
E-Tablolar
Yükle
Eklentiyi yükleyin.		 onInstall etkinlik nesnesi Dokümanlar
Formlar
E-Tablolar
Slaytlar

function onInstall(e)
Düzenleme
E-tablo hücre içeriği değiştirilir.		 E-Tablolar onEdit etkinlik nesnesi E-Tablolar

function onEdit(e)

 E-Tablolar
Değişiklik
E-tablodaki içerik düzenlenir veya biçimlendirilir.		 Sheets onChange etkinlik nesnesi E-Tablolar
Form-submit
Bir Google formu gönderilir.		 Formlar form gönderme etkinliği nesnesi
E-Tablolar form gönderme etkinliği nesnesi 		Formlar
E-Tablolar
Zaman denetimli (saat)
Tetikleyici, belirtilen bir zamanda veya aralıkta etkinleştirilir.		 Zamana dayalı etkinlik nesnesi Dokümanlar
Formlar
E-Tablolar
Slaytlar

* Google Formlar için açık etkinliği, bir kullanıcı yanıt vermek üzere formu açtığında değil, bir düzenleyici formu değiştirmek için açtığında gerçekleşir.

Eklentilerde basit tetikleyiciler

Basit tetikleyiciler, ayrılmış bir işlev adı grubu kullanır, yetkilendirme gerektiren hizmetleri kullanamaz ve otomatik olarak kullanıma etkinleştirilir. Bazı durumlarda, basit bir tetikleyici etkinliği yerine yüklenebilir tetikleyici kullanılabilir.

Aşağıdaki ayrılmış adlardan birini kullanarak bir işlev uygulayarak eklentiye basit bir tetikleyici ekleyebilirsiniz:

  • onOpen(e), kullanıcı bir doküman, e-tablo veya sunu açtığında yürütülür. onOpen(e), bir form düzenleyicide açıldığında da yürütülebilir (ancak forma yanıt verirken değil). Bu işlev yalnızca kullanıcının söz konusu dosyayı düzenleme izni varsa yürütülür ve genellikle menü öğeleri oluşturmak için kullanılır.
  • onInstall(e), kullanıcı bir eklenti yüklediğinde çalışır. Genellikle onInstall(e), yalnızca onOpen(e) çağrılmak için kullanılır. Bu, eklenti menüsünün yükleme işleminden hemen sonra kullanıcının sayfayı yenilemesine gerek kalmadan görünmesini sağlar.
  • onEdit(e), bir kullanıcı e-tablodaki bir hücrenin değerini değiştirdiğinde çalışır. Bu tetikleyici, hücre taşıma, biçimlendirme veya hücre değerlerini değiştirmeyen diğer değişikliklere yanıt olarak etkinleştirilmez.

Kısıtlamalar

Eklentilerdeki basit tetikleyiciler, diğer türdeki Apps Komut Dosyası projelerindeki basit tetikleyicileri yöneten aynı kısıtlamalara tabidir. Eklentileri tasarlarken aşağıdaki kısıtlamalara özellikle dikkat edin:

  • Dosya salt okunur (görüntüleme veya yorum) modunda açılırsa basit tetikleyiciler çalışmaz. Bu davranış, eklenti menülerinizin doldurulmasını engeller.
  • Düzenleyici eklentileri, belirli durumlarda onOpen(e) ve onEdit(e) basit tetikleyicilerini yetkilendirmesiz modda çalıştırır. Bu mod, eklenti yetkilendirme modelinde belirtildiği gibi bazı ek komplikasyonlar sunar.
  • Basit tetikleyiciler, eklenti yetkilendirme modelinde belirtildiği şekilde hizmetleri kullanamaz veya yetkilendirme gerektiren başka işlemler yapamaz.
  • Basit tetikleyiciler 30 saniyeden uzun süre çalışamaz. Basit bir tetikleyici işlevinde yapılan işlem miktarını en aza indirin.
  • Basit tetikleyiciler, Apps Komut Dosyası tetikleyici kota sınırlamalarına tabidir.

Eklentilerde yüklenebilir tetikleyiciler

Eklentiler, Apps Komut Dosyası Script hizmetiyle yüklenebilir tetikleyicileri programatik olarak oluşturup değiştirebilir. Eklenti yüklenebilir tetikleyicileri manuel olarak oluşturulamaz. Basit tetikleyicilerin aksine, yüklenebilir tetikleyiciler yetkilendirme gerektiren hizmetleri kullanabilir.

Eklentilerdeki yüklenebilir tetikleyiciler, kullanıcı hatalarla karşılaştığında kullanıcıya hata e-postaları göndermez. Bunun nedeni, çoğu durumda kullanıcının sorunu çözememesidir. Bu nedenle, mümkün olduğunda eklentinizi kullanıcı adına hataları sorunsuz bir şekilde ele alacak şekilde tasarlamanız gerekir.

Eklentiler aşağıdaki yüklenebilir tetikleyicileri kullanabilir:

  • Yüklenebilir Aç tetikleyicileri, kullanıcı bir doküman veya e-tablo açtığında ya da düzenleyicide bir form açıldığında (ancak forma yanıt verildiğinde değil) çalışır.
  • Düzenle yüklenebilir tetikleyicileri, kullanıcı bir e-tablodaki hücre değerini değiştirdiğinde yürütülür. Bu tetikleyici, hücre değerlerini değiştirmeyen biçimlendirme veya diğer değişikliklere yanıt olarak tetiklenmez.
  • Yüklenebilir değişiklik tetikleyicileri, kullanıcı bir e-tabloda herhangi bir değişiklik yaptığında (e-tabloda biçimlendirme düzenlemeleri ve değişiklikler de dahil olmak üzere (ör. satır ekleme)) çalışır.

  • Form-submit yüklenebilir tetikleyicileri, bir Google Form yanıtı gönderildiğinde çalışır.

  • Zaman denetimli tetikleyiciler (saat tetikleyicileri olarak da bilinir) belirli bir zamanda veya düzenli bir zaman aralığında tekrar tekrar tetiklenir.

Yüklenebilir tetikleyicileri yetkilendirme

Normalde, bir geliştirici bir eklentiyi ek yetkilendirme gerektiren yeni hizmetleri kullanacak şekilde güncellediğinde, kullanıcılardan eklentiyi bir sonraki kullanımlarında yeniden yetkilendirmeleri istenir.

Ancak tetikleyici kullanan eklentiler, özel yetkilendirme zorluklarıyla karşılaşır. Form gönderimlerini izlemek için tetikleyici kullanan bir eklenti düşünün: Form oluşturucu, eklentiyi ilk kez kullandığında yetkilendirebilir ve ardından formu hiç yeniden açmadan aylarca veya yıllarca çalışmasına izin verebilir. Eklenti geliştiricisi, eklentiyi ek yetkilendirme gerektiren yeni hizmetleri kullanacak şekilde güncellerse form oluşturucu formu hiç yeniden açmadığı için yeniden yetkilendirme iletişim kutusunu hiç görmez ve eklenti çalışmayı durdurur.

Normal Apps Komut Dosyası projelerindeki tetikleyicilerin aksine, eklentilerdeki tetikleyiciler yeniden yetkilendirme gerektirse bile tetiklenmeye devam eder. Ancak, komut dosyası, komut dosyasının sahip olmadığı yetkilendirme gerektiren bir kod satırına rastlarsa yine başarısız olur. Geliştiriciler bu durumu önlemek için ScriptApp.getAuthorizationInfo() yöntemini kullanarak eklentinin yayınlanan sürümleri arasında değişen kod bölümlerinin erişimini kısıtlayabilir.

Yetkilendirmeyle ilgili sorunların önüne geçmek için tetikleyici işlevlerde kullanılması önerilen yapının bir örneğini aşağıda bulabilirsiniz. Örnek tetikleyici işlevi, bir Google E-Tablolar eklentisinde form gönderme etkinliğine yanıt verir ve yeniden yetkilendirme gerekiyorsa eklenti kullanıcısına şablonlu HTML kullanarak bir uyarı e-postası gönderir.

Code.gs

triggers/form/Code.gs
/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html
<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Kısıtlamalar

Eklentilerdeki yüklenebilir tetikleyiciler, diğer türdeki Apps Komut Dosyası projelerindeki yüklenebilir tetikleyicileri yöneten aynı kısıtlamalara tabidir.

Bu kısıtlamalara ek olarak, özellikle eklentilerdeki yüklenebilir tetikleyiciler için çeşitli kısıtlamalar geçerlidir:

  • Her eklentide, kullanıcı başına ve belge başına her türden yalnızca bir tetikleyici olabilir. Örneğin, belirli bir e-tabloda belirli bir kullanıcının yalnızca bir düzenleme tetikleyicisi olabilir. Ancak kullanıcının aynı e-tabloda form gönderme tetikleyicisi veya zamana dayalı tetikleyicisi de olabilir. Aynı e-tabloya erişimi olan farklı bir kullanıcının kendi ayrı tetikleyici grubu olabilir.
  • Eklentiler yalnızca eklentinin kullanıldığı dosya için tetikleyici oluşturabilir. Yani A Google Dokümanında kullanılan bir eklenti, B Google Dokümanının açılmasını izleyen bir tetikleyici oluşturamaz.
  • Zamana dayalı tetikleyiciler saatte bir defadan daha sık çalışamaz.
  • Yüklenebilir tetikleyici tarafından çalıştırılan kod bir istisna oluşturduğunda eklentiler kullanıcıya otomatik olarak e-posta göndermez. Hata durumlarını kontrol etmek ve sorunsuz şekilde ele almak geliştiricinin sorumluluğundadır.
  • Eklenti tetikleyicileri aşağıdaki durumlardan herhangi birinde etkinleşmeyi durdurur:
    • Eklenti kullanıcı tarafından kaldırılırsa
    • Eklenti bir dokümanda devre dışıysa (yeniden etkinleştirilirse tetikleyici tekrar çalışır) veya
    • Geliştirici, eklentiyi yayından kaldırırsa veya eklenti mağazasına bozuk bir sürüm gönderirse.
  • Eklenti tetikleyici işlevleri, izinsiz bir hizmeti kullanan koda ulaşana kadar yürütülür ve bu noktada durur. Bu durum yalnızca eklenti yayınlanmışsa geçerlidir. Komut dosyasının herhangi bir kısmının yetkilendirilmesi gerekiyorsa normal bir Apps Komut Dosyası projesindeki veya yayınlanmamış bir eklentideki aynı tetikleyici hiç çalışmaz.
  • Yüklenebilir tetikleyiciler, Apps Komut Dosyası tetikleyici kota sınırlamalarına tabidir.