Düzenleyici eklentileri için tetikleyiciler

Apps Komut Dosyası 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 uygulayın. Bu işlemde, etkinlik nesnesindeki verileri kullanabilirsiniz.

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

Düzenleyici eklentisi tetikleyici türleri

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

Google Workspace eklentileri, Düzenleyici eklentilerinin aksine genel Apps Komut Dosyası basit veya yüklenebilir tetikleyicilerini kullanamaz. Bunun yerine, Google Workspace eklentileri için özel olarak tasarlanmış tetikleyiciler kullanılır. Daha fazla bilgi için Google Workspace eklentileri tetikleyicileri başlıklı makaleyi inceleyin.

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 event object	E-Tablolar function onEdit(e)	E-Tablolar
Değiştir 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 bunun yerine yüklenebilir bir tetikleyici tarafından işlenebilir.

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

• onOpen, kullanıcı bir dokümanı, e-tabloyu veya sunuyu açtığında yürütülür. onOpen, 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, kullanıcı bir eklenti yüklediğinde yürütülür. Genellikle onInstall yalnızca onOpen işlevini çağırmak için kullanılır. Bu, eklenti menülerinin yüklemeden hemen sonra görünmesini sağlar ve kullanıcının sayfayı yenilemesini gerektirmez.
• onEdit, 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 hareketleri, 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 aşağıdaki kısıtlamalara özellikle dikkat edin:

• Basit tetikleyiciler, bir dosya salt okunur (görüntüleme veya yorum yapma) modunda açılırsa çalışmaz. Bu davranış, eklenti menülerinizin doldurulmasını engeller.
• Düzenleyici eklentileri, belirli durumlarda onOpen ve onEdit basit tetikleyicilerini yetkilendirme gerektirmeyen bir modda çalıştırır. Bu mod, eklenti yetkilendirme modelinde belirtildiği gibi komplikasyonları gösterir.
• 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 indirin.
• 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şturup 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, mümkün olduğunda eklentinizi hataları kullanıcı adına 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 e-tablodaki hücre değerini değiştirdiğinde yürütülü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 tetikleyicileri, Google Form yanıtı gönderildiğinde çalışır.

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

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

Yüklenebilir tetikleyicilere yetki verme

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 aylarca veya yıllarca çalışmaya bırakabilir. Eklenti geliştiricisi, eklentiyi ek yetkilendirme gerektiren yeni hizmetleri kullanacak şekilde güncellerse formu oluşturan kişi formu 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. Bunu önlemek için, eklentinin sürümleri arasında değişen kod bölümlerine erişimi sınırlamak üzere ScriptApp.getAuthorizationInfo kullanın.

Aşağıdaki örneklerde, yetkilendirme ile ilgili sorunları önlemek için tetikleyici işlevlerde kullanılması önerilen yapı gösterilmektedir. Ö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.

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

<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ı ve 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ı 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. Örneğin, A adlı Google Dokümanı'nda kullanılan bir eklenti, B adlı Google Dokümanı'nın ne zaman açıldığını izlemek 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. Geliştirici, hata durumlarını kontrol etmek ve sorunsuz bir şekilde ele almakla yükümlüdü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ılırsa (yeniden etkinleştirilirse tetikleyici tekrar çalışır) veya
  • Geliştirici, eklentinin yayınını kaldırırsa veya eklenti mağazasına bozuk bir sürüm gönderirse
• Eklenti tetikleyici işlevleri, yetkisiz bir hizmeti kullanan koda ulaşana kadar yürütülür ve bu noktada durur. Bu 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ı projesinde veya yayınlanmamış bir eklentideki aynı tetikleyici hiç çalışmaz.
• Yüklenebilir tetikleyiciler, Apps Komut Dosyası tetikleyici kota sınırlarına tabidir.