Düzenleyici eklentileri için tetikleyiciler

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

Bir tetikleyici tetiklendiğinde etkinlik nesnesi oluşturulur. Bu JSON yapısı, meydana gelen etkinlik hakkında 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 Komut Dosyası, bunu tetikleyici işlevine parametre olarak aktarır. Tetikleyici işlevi, etkinliğe yanıt vermek için uygun işlemleri gerçekleştirmek üzere kendiniz uygulamanız gereken bir geri çağırma işlevidir. Örneğin, bir Düzenleyici eklentisinde, 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 uygularsınız. Bu işlemde, etkinlik nesnesindeki verileri kullanabilirsiniz.

Bu sayfada, düzenleyici eklenti projelerinde tetikleyicileri kullanmayla ilgili yönergeler verilmektedir.

Düzenleyici eklentisi tetikleyici türleri

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

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

Etkinlik Etkinlik nesnesi Basit tetikleyiciler Yüklenebilir tetikleyiciler
Aç
Bir düzenleyici dosyası açılır.		 Docs onOpen event object
Forms onOpen event object
Sheets onOpen event object
Slides onOpen event object 		Dokümanlar
Formlar*
E-Tablolar
Slaytlar

function onOpen(e)

 Dokümanlar
Formlar
E-Tablolar
Yükle'yi tıklayın.
Eklenti yüklenir.		 onInstall etkinlik nesnesi Dokümanlar
Formlar
E-Tablolar
Slaytlar

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

function onEdit(e)

 E-Tablolar
Değişiklik
Bir sayfadaki içerik düzenlenir veya biçimlendirilir.		 Sheets onChange event object E-Tablolar
Form gönderme
Bir Google Formu gönderildiğinde.		 Forms form-submit event object
Sheets form-submit event object 		Formlar
E-Tablolar
Zamana dayalı (saat)
Tetikleyici, belirli bir zamanda veya aralıkta etkinleşir.		 Zamana dayalı etkinlik nesnesi Dokümanlar
Formlar
E-Tablolar
Slaytlar

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

Eklentilerdeki basit tetikleyiciler

Basit tetikleyiciler, ayrılmış bir dizi işlev adı kullanır, yetkilendirme gerektiren hizmetleri kullanamaz ve kullanım için otomatik olarak etkinleştirilir. Bazı durumlarda basit bir tetikleyici etkinliği, yüklenebilir tetikleyici tarafından da işlenebilir.

Aşağıdaki ayrılmış adlardan birine sahip bir işlev uygulayarak 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), form düzenleyicide açıldığında da çalıştırılabilir (ancak forma yanıt verirken çalıştırılamaz). Yalnızca kullanıcının söz konusu dosyayı düzenleme izni varsa yürütülür ve en sık menü öğeleri oluşturmak için kullanılır.
  • onInstall(e), kullanıcı bir eklenti yüklediğinde yürütülür. Genellikle onInstall(e) yalnızca onOpen(e)'ı çağırmak için kullanılır. Bu, eklenti menülerinin, kullanıcının sayfayı yenilemesini gerektirmeden yüklemeden hemen sonra görünmesini sağlar.
  • onEdit(e), 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 hücre taşımaları, biçimlendirme veya diğer değişikliklere yanıt olarak tetiklenmez.

Kısıtlamalar

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

  • Basit tetikleyiciler, bir dosya salt okunur (görüntüleme veya yorum) modunda açılırsa çalışmaz. Bu davranış, eklenti menülerinizin doldurulmasını engeller.
  • Bazı durumlarda, Düzenleyici eklentileri onOpen(e) ve onEdit(e) basit tetikleyicilerini yetkilendirme gerektirmeyen bir modda çalıştırır. Bu mod, eklenti yetkilendirme modelinde belirtildiği gibi bazı ek sorunlara yol açar.
  • Basit tetikleyiciler, hizmetleri kullanamaz veya eklenti yetkilendirme modelinde belirtilenler dışında 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 indirmeye dikkat edin.
  • Basit tetikleyiciler, Apps Komut Dosyası tetikleyici 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ıklarında kullanıcıya hata e-postaları göndermez. Bunun nedeni, çoğu durumda kullanıcının sorunu çözememesidir. Bu nedenle, eklentinizi mümkün olduğunda kullanıcı adına hataları sorunsuz bir şekilde işleyecek şekilde tasarlamanız gerekir.

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

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

  • Form gönderme yüklenebilir tetikleyiciler, Google Formlar yanıtı gönderildiğinde çalışır.

  • Zamana dayalı tetikleyiciler (saat tetikleyicileri olarak da adlandırılır) belirli bir zamanda veya düzenli aralıklarla tekrar tekrar tetiklenir.

Yüklenebilir tetikleyicileri yetkilendirme

Normalde, bir geliştirici eklentiyi ek yetkilendirme gerektiren yeni hizmetleri kullanacak şekilde güncellerse kullanıcılar eklentiyi bir sonraki kullanımlarında yeniden yetkilendirmeye yönlendirilir.

Ancak tetikleyicileri kullanan eklentiler özel yetkilendirme sorunlarıyla karşılaşır. Form gönderimlerini izlemek için tetikleyici kullanan bir eklenti düşünün: Formu oluşturan kişi, eklentiyi ilk kez kullandığında yetkilendirebilir ve formu bir daha hiç açmadan eklentinin aylarca veya yıllarca çalışmasına izin verebilir. Eklenti geliştirici, 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 görmez ve eklenti çalışmayı durdurur.

Normal Apps Komut Dosyası projelerindeki tetikleyicilerin aksine, eklentilerdeki tetikleyiciler yeniden yetkilendirme gerektirse bile çalışmaya devam eder. Ancak komut dosyası, yetkilendirme gerektiren bir kod satırına ulaştığında yine de başarısız olur. Geliştiriciler bu durumu önlemek için ScriptApp.getAuthorizationInfo() yöntemini kullanarak eklentinin yayınlanmış sürümleri arasında değişen kod bölümlerine erişimi sınırlayabilir.

Aşağıda, yetkilendirme tuzaklarından kaçınmak için tetikleyici işlevlerde kullanılması önerilen yapının bir ö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 eklentinin 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 Apps Komut Dosyası projelerindeki yüklenebilir tetikleyicileri yöneten kısıtlamalara tabidir.

Bu kısıtlamaların yanı sıra, özellikle eklentilerdeki yüklenebilir tetikleyiciler için de çeşitli kısıtlamalar geçerlidir:

  • Her eklenti, kullanıcı, doküman başına her türden yalnızca bir tetikleyiciye sahip olabilir. Örneğin, belirli bir e-tabloda belirli bir kullanıcının yalnızca bir düzenleme tetikleyicisi olabilir. Ancak aynı e-tabloda form gönderme tetikleyicisi veya zamana dayalı tetikleyici de olabilir. Aynı elektronik tabloya erişimi olan farklı bir kullanıcının kendi tetikleyici grubu olabilir.
  • Eklentiler yalnızca eklentinin kullanıldığı dosya için tetikleyici oluşturabilir. Örneğin, A adlı Google Dokümanı'nda kullanılan bir eklenti, B adlı Google Dokümanı açıldığında izleme yapmak için tetikleyici oluşturamaz.
  • Zamana dayalı tetikleyiciler saatte bir defadan daha sık çalıştırılamaz.
  • 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ı kontrol etmek ve sorunsuz şekilde yönetmek geliştiricinin sorumluluğundadır.
  • Eklenti tetikleyicileri aşağıdaki durumlarda etkinleşmeyi durdurur:
    • Eklenti kullanıcı tarafından kaldırılırsa
    • Eklenti bir dokümanda devre dışı bırakılmışsa (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, yetkisiz bir hizmetin kullanıldığı koda ulaşana kadar yürütülür ve bu noktada durur. Bu durum yalnızca eklenti yayınlandıysa geçerlidir. Komut dosyasının herhangi bir bölümü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ırlarına tabidir.