Basit Tetikleyiciler

Tetikleyiciler, Apps Komut Dosyası'nın belirli bir etkinlik (ör. doküman açma) gerçekleştiğinde bir işlevi otomatik olarak çalıştırmasına olanak tanır. Basit tetikleyiciler, Apps Komut Dosyası'na yerleştirilmiş bir dizi ayrılmış işlevdir. Örneğin, kullanıcı bir Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar dosyası açtığında yürütülen onOpen(e) işlevi. Yüklenebilir tetikleyiciler, basit tetikleyicilere kıyasla daha fazla özellik sunar ancak kullanılmadan önce etkinleştirilmesi gerekir. Apps Script, her iki tetikleyici türü için de tetiklenen işleve, etkinliğin gerçekleştiği bağlamla ilgili bilgileri içeren bir etkinlik nesnesi iletir.

Başlarken

Basit bir tetikleyici kullanmak için bu ayrılmış işlev adlarından birini kullanan bir işlev oluşturmanız yeterlidir:

  • onOpen(e), kullanıcının düzenleme izni olan bir e-tablo, doküman, sunu veya form açtığında çalışır.
  • onInstall(e), kullanıcı Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar'dan Düzenleyici eklentisi yüklediğinde çalışır.
  • onEdit(e), kullanıcı bir e-tablodaki değeri değiştirdiğinde çalışır.
  • onSelectionChange(e), kullanıcı bir e-tablodaki seçimi değiştirdiğinde çalışır.
  • doGet(e), kullanıcı bir web uygulamasını ziyaret ettiğinde veya bir program web uygulamasına HTTP GET isteği gönderdiğinde çalışır.
  • doPost(e), bir program web uygulamasına HTTP POST isteği gönderdiğinde çalışır.

Yukarıdaki işlev adlarındaki e parametresi, işleve iletilen bir etkinlik nesnesidir. Nesne, tetikleyicinin etkinleşmesine neden olan bağlamla ilgili bilgiler içerir ancak bu bilgilerin kullanılması isteğe bağlıdır.

Kısıtlamalar

Basit tetikleyiciler, kullanıcıdan yetki istenmeden otomatik olarak tetiklendiğinden çeşitli kısıtlamalara tabidir:

  • Komut dosyası, Google E-Tablolar, Slaytlar, Dokümanlar veya Formlar dosyasına bağlı olmalı ya da bu uygulamalardan birini genişleten bir eklenti olmalıdır.
  • Bir dosya salt okuma (görüntüleme veya yorum) modunda açılırsa çalışmazlar.
  • Komut dosyası yürütmeleri ve API istekleri, tetikleyicilerin çalışmasına neden olmaz. Örneğin, bir hücreyi düzenlemek için Range.setValue() işlevini çağırmak, e-tablonun onEdit tetikleyicisinin çalışmasına neden olmaz.
  • Yetkilendirme gerektiren hizmetlere erişemezler. Örneğin, Gmail hizmeti yetkilendirme gerektirdiğinden basit bir tetikleyici e-posta gönderemez ancak basit bir tetikleyici, anonim olan Language hizmeti ile bir ifadeyi çevirebilir.
  • Bağlı oldukları dosyayı değiştirebilirler ancak yetkilendirme gerektiği için diğer dosyalara erişemezler.
  • Karmaşık bir güvenlik kısıtlamaları grubu nedeniyle mevcut kullanıcının kimliğini belirleyebilir veya belirleyemeyebilirler.
  • 30 saniyeden uzun süre yayınlanamazlar.
  • Belirli durumlarda Doküman Düzenleyici eklentileri, onOpen(e) ve onEdit(e) basit tetikleyicilerini, bazı ek sorunlara yol açan yetkilendirme gerektirmeyen bir modda çalıştırır. Daha fazla bilgi için eklenti yetkilendirme yaşam döngüsü kılavuzuna bakın.
  • Basit tetikleyiciler, Apps Komut Dosyası tetikleyici kota sınırlarına tabidir.

Bu kısıtlamalar doGet(e) veya doPost(e) için geçerli değildir.

onOpen(e)

onOpen(e) tetikleyicisi, kullanıcı düzenleme izni olan bir e-tablo, doküman, sunu veya formu açtığında otomatik olarak çalışır. (Tetikleyici, forma yanıt verirken değil, yalnızca formu düzenlemek için açarken çalışır.) onOpen(e), en sık Google E-Tablolar, Slaytlar, Dokümanlar veya Formlar'a özel menü öğeleri eklemek için kullanılır.

triggers/triggers.gs
/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

onInstall(e) tetikleyicisi, kullanıcı Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar'dan bir Düzenleyici eklentisi yüklediğinde otomatik olarak çalışır. Eklenti, Google Workspace Marketplace web sitesinden yüklendiğinde tetikleyici çalışmaz. onInstall(e)'nın yapabilecekleriyle ilgili belirli kısıtlamalar olduğunu unutmayın. Yetkilendirme hakkında daha fazla bilgi edinin. onInstall(e) işlevinin en yaygın kullanımı, özel menüler eklemek için onOpen(e) işlevini çağırmaktır. Sonuçta, bir eklenti yüklendiğinde dosya zaten açıktır ve bu nedenle dosya yeniden açılmadığı sürece onOpen(e) kendi başına çalışmaz.

triggers/triggers.gs
/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

onEdit(e) tetikleyici, bir kullanıcı e-tablodaki herhangi bir hücrenin değerini değiştirdiğinde otomatik olarak çalışır. Çoğu onEdit(e) tetikleyici, uygun şekilde yanıt vermek için event nesnesindeki bilgileri kullanır. Örneğin, aşağıdaki onEdit(e) işlevi, son düzenleme zamanını kaydeden hücreye yorum ekler.

triggers/triggers.gs
/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

onSelectionChange(e) tetikleyicisi, kullanıcı bir e-tablodaki seçimi değiştirdiğinde otomatik olarak çalışır. Bu tetikleyiciyi etkinleştirmek için tetikleyici eklendikten sonra ve e-tablo her açıldığında e-tabloyu yenilemeniz gerekir.

Seçim kısa süre içinde birden fazla hücre arasında hareket ederse gecikmeyi azaltmak için bazı seçim değişikliği etkinlikleri atlanabilir. Örneğin, iki saniye içinde birçok seçim değişikliği yapılırsa yalnızca ilk ve son seçim değişiklikleri onSelectionChange(e) tetikleyicisini etkinleştirir.

Aşağıdaki örnekte, boş bir hücre seçilirse onSelectionChange(e) işlevi hücrenin arka planını kırmızı yapar.

triggers/triggers.gs
/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) ve doPost(e)

doGet(e) tetikleyicisi, bir kullanıcı web uygulamasını ziyaret ettiğinde veya bir program web uygulamasına HTTP GET isteği gönderdiğinde otomatik olarak çalışır. doPost(e), bir program web uygulamasına HTTP POST isteği gönderdiğinde çalışır. Bu tetikleyiciler, web uygulamaları, HTML hizmeti ve içerik hizmeti kılavuzlarında daha ayrıntılı olarak açıklanmaktadır. doGet(e) ve doPost(e) yukarıda listelenen kısıtlamalara tabi değildir.

Kullanılabilir tetikleyici türleri

Basit tetikleyicilerle ilgili kısıtlamalar ihtiyaçlarınızı karşılamanızı engelliyorsa bunun yerine yüklenebilir tetikleyici kullanabilirsiniz. Aşağıdaki tabloda, her etkinlik türü için hangi tetikleyici türlerinin kullanılabildiği özetlenmektedir. Örneğin, Google E-Tablolar, Slaytlar, Formlar ve Dokümanlar'ın tümü basit açma tetikleyicilerini destekler ancak yalnızca E-Tablolar, Dokümanlar ve Formlar yüklenebilir açma tetikleyicilerini destekler.

Etkinlik Basit tetikleyiciler Yüklenebilir tetikleyiciler
Aç
E-Tablolar
Slaytlar
Formlar*
Dokümanlar

function onOpen(e)
E-Tablolar
Formlar*
Dokümanlar
Düzenle
E-Tablolar

function onEdit(e)
E-Tablolar
Seçim değişikliği
E-Tablolar

function onSelectionChange(e)
Yükle
E-Tablolar
Slaytlar
Formlar
Dokümanlar

function onInstall(e)
Değiştir
E-Tablolar
Form gönderme
E-Tablolar
Formlar
Zamana dayalı (saat)
E-Tablolar
Slaytlar
Formlar
Dokümanlar
Bağımsız
Get
Bağımsız

function doGet(e)
Gönderi
Bağımsız

function doPost(e)

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