Basit Tetikleyiciler

Tetikleyiciler, bir dokümanı açma gibi belirli bir etkinlik gerçekleştiğinde Apps Komut Dosyası'nın bir işlevi otomatik olarak çalıştırmasını sağlar. Basit tetikleyiciler, Apps Komut Dosyası'nda yerleşik olarak bulunan ve bir kullanıcı Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar dosyasını açtığında yürütülen onOpen(e) işlevi gibi ayrılmış işlevlerdir. Yüklenebilir tetikleyiciler, basit tetikleyicilerden daha fazla özellik sunar ancak kullanılmadan önce etkinleştirilmesi gerekir. Her iki tetikleyici türünde de Apps Komut Dosyası, tetiklenen işleve etkinliğin gerçekleştiği bağlam hakkında bilgi içeren bir etkinlik nesnesi iletir.

Başlarken

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

  • onOpen(e), bir kullanıcı düzenleme iznine sahip olan bir e-tablo, doküman, sunu veya formu açtığında çalışır.
  • onInstall(e), bir kullanıcı Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar'dan bir Düzenleyici Eklentisi yüklediğinde çalışır.
  • onEdit(e), kullanıcı e-tablodaki bir değeri değiştirdiğinde çalışır.
  • onSelectionChange(e), kullanıcı e-tablodaki seçimi değiştirdiğinde çalıştırılır.
  • doGet(e), bir 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ında bulunan e parametresi, işleve geçirilen bir etkinlik nesnesidir. Nesne, tetikleyicinin etkinleşmesine neden olan bağlamla ilgili bilgiler içerir ancak tetikleyicinin kullanılması isteğe bağlıdır.

Kısıtlamalar

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

  • Komut dosyası bir Google E-Tablolar, Slaytlar, Dokümanlar veya Formlar dosyasına bağlı ya da bu uygulamalardan birini genişleten bir eklenti olmalıdır.
  • Bu dosyalar, bir dosya salt okuma (görüntüleme veya yorum yapma) modunda açılırsa çalışmaz.
  • Komut dosyası yürütme işlemleri ve API istekleri, tetikleyicilerin çalışmasına neden olmaz. Örneğin, bir hücreyi düzenlemek için Range.setValue() çağrısı, 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, bir ifadeyi anonim olan Dil hizmeti ile çevirebilir.
  • Bağlı oldukları dosyayı değiştirebilirler ancak yetkilendirme gerektireceğinden diğer dosyalara erişemezler.
  • Karmaşık bir güvenlik kısıtlamaları grubuna bağlı olarak geçerli kullanıcının kimliğini tespit edebilir veya belirleyemeyebilirler.
  • 30 saniyeden uzun süre boyunca yayınlanamaz.
  • Belirli durumlarda Düzenleyici Eklentileri, onOpen(e) ve onEdit(e) basit tetikleyicilerini bazı ek özellikler sunan yetkilendirme yok modunda ç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ı tetikleyicisi 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, bir kullanıcı düzenleme iznine sahip olduğu bir e-tabloyu, dokümanı, sunuyu veya formu açtığında otomatik olarak çalışır. (Tetikleyici bir forma yanıt verirken çalışmaz, yalnızca düzenlemek için formu açarken çalışır.) onOpen(e), çoğunlukla 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. Kullanıcı, eklentiyi Google Workspace Marketplace web sitesinden yüklediğinde tetikleyici çalışmaz. onInstall(e) uygulamasının yapabileceği 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) çağrısı yapmaktır. Sonuçta, bir eklenti yüklendiğinde dosya zaten açıktır ve bu nedenle onOpen(e), dosya yeniden açılıncaya kadar 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)

Kullanıcı e-tablodaki herhangi bir hücrenin değerini değiştirdiğinde onEdit(e) tetikleyicisi otomatik olarak çalışır. Çoğu onEdit(e) tetikleyicisi, uygun şekilde yanıt vermek için etkinlik nesnesindeki bilgileri kullanır. Örneğin, aşağıdaki onEdit(e) işlevi, hücrede, en son düzenlendiği zamanı kaydeden bir yorum ayarlar.

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)

Kullanıcı bir e-tablodaki seçimi değiştirdiğinde onSelectionChange(e) tetikleyicisi 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 bir süre içinde birden çok hücre arasında hareket ederse gecikmeyi azaltmak için bazı seçim değişikliği etkinlikleri atlanabilir. Örneğin, birbirini izleyen 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ıya ayarlar.

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)

Kullanıcı bir web uygulamasını ziyaret ettiğinde veya bir program web uygulamasına HTTP GET isteği gönderdiğinde doGet(e) tetikleyicisi otomatik olarak çalışır. Bir program web uygulamasına HTTP POST isteği gönderdiğinde doPost(e) çalıştırılır. Bu tetikleyiciler web uygulamaları, HTML hizmeti ve İçerik hizmeti rehberlerinde daha ayrıntılı olarak açıklanmıştır. doGet(e) ve doPost(e) özelliklerinin yukarıda listelenen kısıtlamalara tabi olmadığını unutmayın.

Kullanılabilir tetikleyici türleri

Basit tetikleyiciler üzerindeki kısıtlamalar bunların ihtiyaçlarınızı karşılamalarını engelliyorsa bunun yerine yüklenebilir bir tetikleyici kullanılabilir. Aşağıdaki tabloda, her etkinlik türü için ne tür tetikleyicilerin kullanılabileceği özetlenmektedir. Örneğin, Google E-Tablolar, Slaytlar, Formlar ve Dokümanlar'ın tümü basit açık tetikleyicileri destekler, ancak yalnızca E-Tablolar, Dokümanlar ve Formlar yüklenebilir açık tetikleyicileri 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
Zaman odaklı (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 için açık etkinlik, bir kullanıcı yanıt vermek üzere bir formu açtığında değil, bir düzenleyici formda değişiklik yapmak üzere formu açtığında gerçekleşir.