Düzenleyici Eklentilerini Tetikleyiciler

Apps Komut Dosyası tetikleyicileri belirtilen bir komut dosyasına neden olur işlevi (tetikleyici işlevi) gerçekleşir. Yalnızca belirli etkinlikler tetikleyicilerin etkinleşmesine neden olabilir ve bunların her biri 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. Etkinlikteki bilgiler nesne yapısı, tetikleyici türüne göre farklı şekilde düzenlenir.

Etkinlik nesnesi oluşturulduktan sonra, Apps Komut Dosyası bu nesneyi parametre olarak tetikleyici işlevi. Tetikleyici işlevi bir geri çağırma işlevidir. gerekli adımları atıp gerekli önlemleri almanız için unutmayın. Örneğin, Düzenleyici eklentisinde bir tetikleyici doküman açıldığında eklenti menü öğeleri oluşturmak için kullanılır. Böyle durumlarda eklentinin menü öğelerini oluşturmak için onOpen(e) tetikleyici işlevinde uygulayın muhtemelen etkinlik nesnesindeki verileri kullanarak.

Bu sayfada, düzenleyici eklenti projeleri oluşturabilirsiniz.

Düzenleyici eklentisi tetikleyici türleri

Apps Komut Dosyası projelerinde kullanılabilen genel tetikleyici türlerinin çoğunu kullanabilirsiniz. basit tetikleyiciler dahil olmak üzere Düzenleyici Eklentileri'ne ve çoğu yüklenebilir tetikleyici. İlgili içeriği oluşturmak için kullanılan Tam kullanılabilir tetikleyici türleri grubu, genişletilmekte olan uygulamaya bağlıdır.

Aşağıdaki tabloda, uygulamanızın kullanılabilmesi için Düzenleyici Eklentileri, ilgili etkinlik nesnelerini kullanabilir ve bunlara bağlantı sağlar:

Etkinlik Etkinlik nesnesi Basit tetikleyiciler Yüklenebilir tetikleyiciler
Aç
Bir 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
Eklenti yüklü.		 oninstall etkinlik nesnesi . Dokümanlar
Formlar
E-Tablolar
Slaytlar

function onInstall(e)
Düzenle
E-tablonun hücre içeriği değiştirildi.		 E-Tablolar onEdit etkinlik nesnesi . E-Tablolar

function onEdit(e)

 . E-Tablolar
Değişiklik
Sayfadaki içerik düzenlenir veya biçimlendirilmiştir.		 E-Tablolar onChange etkinlik nesnesi . E-Tablolar
Form gönderme
Bir Google Formu gönderilir.		 Formlar'da form gönderme etkinlik nesnesi
E-Tablolar form gönderme etkinlik nesnesi 		. Formlar
E-Tablolar
Zaman odaklı (saat)
Tetikleyici, belirtilen bir zamanda veya aralıkta etkinleşir.		 Zamana dayalı etkinlik nesnesi . Dokümanlar
Formlar
E-Tablolar
Slaytlar

* Google Formlar için açık etkinlik, kullanıcı bir formu yanıtlayacak şekilde gönderin, daha ziyade bir düzenleyici oluşturmak için formu açtığında.

Eklentilerdeki basit tetikleyiciler

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

Sadece bir işlevi uygulayarak eklentiye basit bir tetikleyici ekleyebilirsiniz. aşağıdaki ayrılmış adlardan birine sahip olmalıdır:

  • onOpen(e), kullanıcı bir dokümanı, e-tabloyu veya en iyi uygulamaları paylaşacağız. 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 vardır ve genellikle dosyanın menü öğeleri.
  • onInstall(e), kullanıcı bir eklenti yüklediğinde yürütülür. Normalde onInstall(e) yalnızca onOpen(e) numaralı telefonu aramak için kullanılır; Böylece, eklenti menülerinin yüklemeden hemen sonra kullanıcının sayfayı yenilemesine gerek kalmadan.
  • onEdit(e), kullanıcı e-tablodaki bir hücre değerini değiştirdiğinde yürütülür. Bu tetikleyici, hücre taşıma, biçimlendirme veya hücre değerlerini değiştirmeyen başka değişiklikler var.

Kısıtlamalar

Eklentilerdeki basit tetikleyiciler aynı kısıtlamalara ve Google Apps Komut Dosyası projeleri için tetikleyicidir. Şunları not edin: kısıtlamalara dikkat edin:

  • Basit tetikleyiciler bir dosya salt okunur olarak açıldığında çalışmaz ( yorum) moduna girer. Bu durum, eklenti menülerinizin doldurulmasını engeller.
  • Düzenleyici eklentileri, belirli durumlarda onOpen(e) ve Yetkilendirmesiz modda onEdit(e) basit tetikleyici. Bu modda ekran belirtildiği gibi bazı ek komplikasyonlar eklenti yetkilendirme modeli hakkında daha fazla bilgi edinin.
  • Basit tetikleyiciler hizmetleri kullanamaz veya başka işlemler yapmayı da yetkilendirme, bu kılavuzda eklenti yetkilendirme modeli.
  • Basit tetikleyiciler 30 saniyeden uzun süre çalıştırılamaz. En aza indirmeye özen gösterin Basit bir tetikleyici işlevinde yapılan işlem miktarı.
  • Basit tetikleyiciler Apps Komut Dosyası tetikleyicisine tabidir. kota sınırlarını kaldırın.

Eklentilerde yüklenebilir tetikleyiciler

Eklentiler yüklenebilir tetikleyicileri programatik olarak oluşturma ve değiştirme Apps Komut Dosyası Script hizmetiyle. eklenti Yüklenebilir tetikleyiciler manuel olarak oluşturulamaz. Basit tetikleyicilerden farklı olarak Yüklenebilir tetikleyiciler, yetkilendirme gerektiren hizmetleri kullanabilir.

Eklentilerdeki yüklenebilir tetikleyiciler hata e-postaları göndermez çoğu durumda kullanıcı hatalarla karşılaştığında bunu kullanıcıya bildiremez. adım adım açıklıyor. Bu nedenle, eklentinizi Mümkün olduğunda hataları kullanıcı adına sorunsuz şekilde ele alın.

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

  • Aç yüklenebilir tetikleyiciler kullanıcı bir dokümanı açtığında yürütülür. veya form düzenleyicide bir form açıldığında (ancak yanıt verirken ekleyin).
  • Düzenle Yüklenebilir tetikleyiciler, kullanıcı bir mağazadaki hücre değerini değiştirdiğinde e-tablo kullanarak yapabilirsiniz. Bu tetikleyici, biçimlendirme veya diğer trafik süreçlerine hücre değerlerini değiştirmeyen değişiklikler.
  • Değiştir yüklenebilir tetikleyiciler kullanıcı reklam öğesinde herhangi bir değişiklik yaptığında, e-tabloda yapılan biçimlendirme düzenlemeleri ve değişiklikler de dahil olmak üzere elektronik tablo (satır ekleme gibi).

  • Form gönderme yüklenebilir tetikleyicileri, bir Google Form yanıtı şu durumlarda yürütülür: gönderildi.

  • Zamana dayalı tetikleyiciler (saat tetikleyicileri de denir) belirli bir zamanda veya belirli bir zamanda düzenli zaman aralığı.

Yüklenebilir tetikleyicileri yetkilendirme

Normalde bir geliştirici, ek yetkilendirme durumunda kullanıcılardan bir sonraki zaman geçirmeye hazır hale gelir.

Ancak, tetikleyici kullanan eklentiler özel yetkilendirme sorunlarıyla karşılaşır. Form gönderimlerini izlemek için tetikleyici kullanan bir eklenti düşünün: içerik üretici eklentiyi ilk kez kullandığında yetkilendirebilir, sonra da aylar veya yıllarca çalıştırılabilir. Eklenti geliştiricisi, ek yetkilendirme gerektirirse formu oluşturan kullanıcı Yeniden yetkilendirme iletişim kutusu, çünkü formun ve eklentinin hiçbir zaman çalışmayı durduracaktı.

Normal Apps Komut Dosyası projelerindeki tetikleyicilerden farklı olarak, eklentiler yeniden yetkilendirme gerekse bile etkinleşmeye devam eder. Ancak komut dosyası komut dosyası için yetkilendirme gerektiren bir kod satırına gelirse de başarısız olur. sahip değil. Bu durumu önlemek için geliştiriciler ScriptApp.getAuthorizationInfo() uygulamanızın yayınlanan sürümleri arasında değişen kod bölümlerine erişim görebilirsiniz.

Aşağıda, tetikleme işlevlerinde kullanılması önerilen bir yapı örneği verilmiştir: yetkilendirme tuzaklarından kaçınmalısınız. Örnek tetikleyici işlevi, bir Google E-Tablolar eklentisinde form-gönderme etkinliği yapın ve eklentisinin 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 kısıtlamalar Google Apps Komut Dosyası projesi türlerindeki yüklenebilir tetikleyicileri yönetir.

Bu kısıtlamalara ek olarak, tetikleyicilere otomatik olarak eklenir:

  • Her eklentinin, kullanıcı ve doküman başına her türde yalnızca bir tetikleyicisi olabilir. Örneğin, belirli bir e-tabloda, belirli bir kullanıcı yalnızca tek bir düzenleme yapabilir (kullanıcının da bir form gönderme tetikleyicisi veya aynı e-tabloda yer alan zamana bağlı bir tetikleyicidir. Erişimi olan farklı bir kullanıcı ayrı bir tetikleyici grubuna sahip 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 izle.
  • Zamana dayalı tetikleyiciler, saatte bir defadan daha sık çalıştırılamaz.
  • Eklentiler, yüklenebilir tetikleyici bir istisna oluşturur. Bunu kontrol etmek geliştiriciye bağlıdır ve bunları sorunsuz şekilde ele almaktır.
  • Eklenti tetikleyicileri aşağıdaki durumlardan herhangi birinde etkinleşmez:
    • Eklenti, kullanıcı tarafından kaldırılırsa
    • Eklenti bir dokümanda devre dışı bırakılırsa (yeniden etkinleştirilirse) yeniden çalışır hale gelir) veya
    • Geliştirici, eklentiyi yayından kaldırır veya ekleyebilirsiniz.
  • Eklenti tetikleyici işlevleri yetkisiz bir hizmeti devre dışı bırakabilirler. Bu yalnızca Eklenti yayınlandığında, normal bir Apps Komut Dosyası projesinde aynı tetikleyiciyi yayınlanmamış bir eklenti, komut dosyasının herhangi bir bölümünde yetkilendirme.
  • Yüklenebilir tetikleyiciler, Apps Komut Dosyası tetikleyicisine tabidir. kota sınırlarını kaldırın.