Düzenleyici Eklentileri için tetikleyiciler

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

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

Etkinlik nesnesi oluşturulduktan sonra Apps Komut Dosyası, bunu tetikleyici işlevine parametre olarak aktarır. Tetikleyici işlevi, etkinliğe yanıt vermek için uygun işlemleri yapmak üzere sizin 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 bir tetikleyici kullanılır. Bu durumda, muhtemelen etkinlik nesnesindeki verileri kullanarak eklentinin ihtiyaç duyduğu menü öğelerini oluşturmak için onOpen(e) tetikleyici işlevini uygularsınız.

Bu sayfada, düzenleyici eklenti projelerinde tetikleyicileri kullanma hakkında yönergeler yer almaktadır.

Düzenleyici eklentisi tetikleyici türleri

Basit tetikleyiciler ve yüklenebilir tetikleyicilerin çoğu dahil olmak üzere Düzenleyici Eklentileri'nde Apps Komut Dosyası projeleri için kullanılabilen genel tetikleyici türlerinin çoğunu kullanabilirsiniz. Kullanılabilen tetikleyici türlerinin tam grubu, genişletilen uygulamaya bağlıdır.

Not: Düzenleyici Eklentileri'nin aksine Google Workspace Eklentileri, şu anda genel Apps Komut Dosyası basit veya yüklenebilir tetikleyicilerini kullanamaz. Bunun yerine, Google Workspace Eklentileri için özel olarak tasarlanmış tetikleyiciler kullanırlar. Daha fazla bilgi için Google Workspace Eklentileri tetikleyicileri başlıklı makaleyi inceleyin.

Aşağıdaki tabloda, Düzenleyici Eklentilerinin kullanabileceği basit ve yüklenebilir tetikleyici türleri gösterilmiştir ve ilgili etkinlik nesnelerine bağlantılar verilmiştir:

Etkinlik	Etkinlik nesnesi	Basit tetikleyiciler	Yüklenebilir tetikleyiciler
Aç Bir düzenleyici dosyası açılır.	Docs onOpen etkinlik nesnesi Formlar onOpen etkinlik nesnesi Sheets onOpen etkinlik nesnesi Slaytlar onOpen etkinlik nesnesi	Dokümanlar Formlar* E-Tablolar Slaytlar function onOpen(e)	Dokümanlar Formlar E-Tablolar
Yükle Eklenti yüklenir.	onInstall etkinlik nesnesi	Dokümanlar Formlar E-Tablolar Slaytlar function onInstall(e)
Düzenle E-tablo hücre içeriği değiştiriliyor.	Sheets onEdit etkinlik nesnesi	E-Tablolar function onEdit(e)	E-Tablolar
Değiştirme Bir sayfadaki içerik düzenlenir veya biçimlendirilir.	Sheets onChange etkinlik nesnesi		E-Tablolar
Form gönderme Bir Google Formu gönderilir.	Formlar form gönderme etkinlik nesnesi E-Tablolar form gönderme etkinlik nesnesi		Formlar E-Tablolar
Zaman odaklı (saat) Tetikleyici, belirtilen bir zaman veya aralıkta etkinleşir.	Zamana dayalı etkinlik nesnesi		Dokümanlar Formlar E-Tablolar Slaytlar

* Google Formlar için açık etkinlik, bir kullanıcı yanıt vermek için bir formu açtığında değil, bir düzenleyen kullanıcı formda değişiklik yapmak üzere formu açtığında gerçekleşir.

Eklentilerdeki basit tetikleyiciler

Basit tetikleyiciler ayrılmış işlev adları kullanır, yetkilendirme gerektiren hizmetleri kullanamaz ve kullanım için otomatik olarak etkinleştirilir. Bazı durumlarda, basit bir tetikleyici etkinlik bunun yerine yüklenebilir bir tetikleyici tarafından gerçekleştirilebilir.

Aşağıdaki ayrılmış adlardan biriyle bir işlevi uygulayarak bir eklentiye basit bir tetikleyici ekleyebilirsiniz:

• onOpen(e), kullanıcı bir dokümanı, e-tabloyu veya sunuyu açtığında yürütülür. onOpen(e), düzenleyicide bir form açıldığında da yürütülebilir (ancak forma yanıt verirken değil). Yalnızca kullanıcının söz konusu dosyayı düzenleme izni varsa yürütülür ve çoğunlukla menü öğeleri oluşturmak için kullanılır.
• onInstall(e), bir kullanıcı eklenti yüklediğinde yürütülür. onInstall(e) genellikle yalnızca onOpen(e) çağrısı yapmak için kullanılır. Bu da kullanıcının sayfayı yenilemesine gerek kalmadan eklenti menülerinin yükleme işleminden hemen sonra görünmesini sağlar.
• onEdit(e), kullanıcı e-tabloda bir hücre değerini değiştirdiğinde yürütülür. Bu tetikleyici, hücre taşımalarına, biçimlendirmeye veya hücre değerlerini değiştirmeyen diğer değişikliklere yanıt olarak etkinleşmez.

Kısıtlamalar

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

• Bir dosya salt okuma (görüntüleme veya yorum yapma) modunda açılırsa basit tetikleyiciler çalışmaz. Bu davranış, eklenti menülerinizin doldurulmasını engeller.
• Belirli durumlarda, Düzenleyici Eklentileri 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 açıklanan durumlar haricinde hizmetleri kullanamaz veya yetkilendirme gerektiren başka işlemler gerçekleştiremez.
• Basit tetikleyiciler 30 saniyeden uzun süre çalışamaz. Basit bir tetikleyici işlevinde yapılan işleme miktarını en aza indirmeye dikkat edin.
• Basit tetikleyiciler, Apps Komut Dosyası tetikleyicisi kota sınırlarına tabidir.

Eklentilerde yüklenebilir tetikleyiciler

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

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

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

• Açık yüklenebilir tetikleyiciler, bir kullanıcı bir dokümanı veya e-tabloyu açtığında ya da düzenleyicide bir form açıldığında yürütülür (ancak forma yanıt verirken değil).
• Düzenle yüklenebilir tetikleyiciler, bir kullanıcı e-tabloda bir hücre değerini değiştirdiğinde yürütülür. Bu tetikleyici, hücre değerlerini değiştirmeyen biçimlendirmeye veya diğer değişikliklere yanıt olarak etkinleşmez.
• Değiştirme yüklenebilir tetikleyiciler, kullanıcılar e-tablonun kendisinde yapılan biçimlendirme düzenlemeleri ve değişiklikler (satır ekleme gibi) dahil olmak üzere bir e-tabloda herhangi bir değişiklik yaptığında yürütülür.

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

  Not: Form gönderme tetikleyicilerinin biri E-Tablolar (form yanıtlarının toplandığı) ve diğeri Google Formlar için olmak üzere iki sürümü vardır. E-Tablolar form gönderme tetikleyici işlevine iletilen etkinlik nesnesi daha basittir ve basit dizilerde yanıt değerlerini döndürür. Form form gönderme tetikleyici işlevine iletilen etkinlik nesnesi, bir FormResponse nesnesinde yer alan daha fazla bilgi sağlar.

• Zamana dayalı tetikleyiciler (saat tetikleyicileri olarak da adlandırılır) belirli bir zamanda veya düzenli bir zaman aralığında tekrar tekrar etkinleşir.

Yüklenebilir tetikleyicileri yetkilendirme

Normalde, bir geliştirici bir eklentiyi ek yetkilendirme gerektiren yeni hizmetleri kullanacak şekilde güncellerse kullanıcıdan eklentiyi bir sonraki kullanışında yeniden yetkilendirmesi istenir.

Ancak tetikleyici kullanan eklentiler özel yetkilendirme sorgulamalarıyla karşılaşır. Form gönderimlerini izlemek için tetikleyici kullanan bir eklenti düşünün: Bir form oluşturucu, eklentiyi ilk kez kullandığında eklentiyi yetkilendirebilir, ardından formu yeniden açmadan aylar veya yıllar boyunca çalışır durumda bırakabilir. Eklenti geliştiricisi, eklentiyi ek yetkilendirme gerektiren yeni hizmetler kullanacak şekilde güncellerse formu oluşturan kullanıcı, formu yeniden açmadığı ve eklenti çalışmayı durduracağı için yeniden yetkilendirme iletişim kutusunu hiçbir zaman görmez.

Normal Apps Komut Dosyası projelerindeki tetikleyicilerin aksine, eklentilerdeki tetikleyiciler yeniden yetkilendirme gerekse bile etkinleşmeye devam eder. Ancak komut dosyası, komut dosyasının sahip olmadığı yetkilendirme gerektiren bir kod satırına ulaşırsa yine de başarısız olur. Geliştiriciler, bu durumu önlemek için eklentinin yayınlanan sürümleri arasında değişen kod parçalarına erişimi denetlemek için ScriptApp.getAuthorizationInfo() yöntemini kullanabilir.

Aşağıda, yetkilendirme tuzaklarından kaçınmak için tetikleyici işlevlerinde kullanılması önerilen bir yapı örneği verilmiştir. Örnek tetikleyici işlevi, bir Google E-Tablolar eklentisindeki form gönderme etkinliğine yanıt verir ve yeniden yetkilendirme gerekirse eklenti kullanıcısına şablonlu HTML kullanarak bir uyarı e-postası gönderir.

Kod.g

tetikleyiciler/form/Code.gs

GitHub'da göster

/**
 * 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.
  }
}

yetkilendirmee-postasi.html

tetikleyiciler/form/AuthorizationEmail.html

GitHub'da göster

<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 Apps Komut Dosyası projesi türlerindeki yüklenebilir tetikleyicileri yöneten kısıtlamalara tabidir.

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

• Her eklentinin her türden (kullanıcı ve doküman başına) yalnızca bir tetikleyicisi olabilir. Örneğin, belirli bir e-tabloda, 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ı bir tetikleyicisi de olabilir. Aynı e-tabloya erişimi olan farklı bir kullanıcının kendi ayrı tetikleyici grupları olabilir.
• Eklentiler yalnızca eklentinin kullanıldığı dosya için tetikleyici oluşturabilir. Yani Google Dokümanı A'da kullanılan bir eklenti, Google Dokümanı B açıldığında izlenmesi için tetikleyici oluşturamaz.
• Zamana dayalı tetikleyiciler saatte bir defadan daha sık çalışamaz.
• Yüklenebilir bir 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ı sorunsuz bir şekilde kontrol etmek ve ele almak geliştiriciye kalmıştır.
• Eklenti tetikleyicileri aşağıdaki durumlarda etkinleşmeyi durdurur:
  • Eklenti kullanıcı tarafından kaldırıldıysa
  • Eklenti bir dokümanda devre dışı bırakılırsa (yeniden etkinleştirilirse tetikleyici tekrar çalışır hale gelir) veya
  • Geliştirici eklentiyi yayından kaldırır veya eklenti mağazasına bozuk bir sürüm gönderir.
• Eklenti tetikleyici işlevleri, yetkisiz bir hizmet kullanan bir koda ulaşana kadar yürütülür ve bu noktada durur. Bu işlem yalnızca eklenti yayınlanırsa geçerlidir. Normal Apps Komut Dosyası projesindeki veya yayınlanmamış bir eklentideki aynı tetikleyici, komut dosyasının herhangi bir bölümü yetkilendirme gerektiriyorsa hiç yürütülmez.
• Yüklenebilir tetikleyiciler, Apps Komut Dosyası tetikleyicisi kota sınırlarına tabidir.