Basit Tetikleyiciler

Tetikleyiciler, Apps Script'in 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 çalışan onOpen(e) işlevi. Yüklenebilir tetikleyiciler, basit tetikleyicilerden daha fazla özellik sunar ancak kullanılmadan önce etkinleştirilmelidir. 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 aşağıdaki ayrılmış işlev adlarından birini kullanan bir işlev oluşturmanız yeterlidir:

  • onOpen(e), kullanıcı düzenleme izni olan bir e-tabloyu, dokümanı, sunuyu veya formu açtığında çalışır.
  • onInstall(e), kullanıcı Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar'dan bir Düzenleyici eklentisi yüklediğinde çalışır.
  • onEdit(e), bir kullanıcı e-tablodaki bir 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 bir web uygulamasına HTTP GET isteği gönderdiğinde çalışır.
  • doPost(e), bir program bir 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 tetiklenmesine neden olan bağlamla ilgili bilgiler içerir ancak bu nesne isteğe bağlıdır.

Kısıtlamalar

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

  • Komut dosyası bir Google E-Tablolar, Slaytlar, Dokümanlar veya Formlar dosyasına bağlı olmalıdır ya da bu uygulamalardan birini genişleten bir eklenti olmalıdır.
  • Dosya salt okuma (görüntüleme veya yorum) modunda açılırsa bu makrolar çalışmaz.
  • 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() çağrısı yapıldığında e-tablonun onEdit tetikleyicisi çalışmaz.
  • Yetkilendirme gerektiren hizmetlere erişemezler. Örneğin, Gmail hizmeti yetkilendirme gerektirdiği için basit bir tetikleyici e-posta gönderemez ancak anonim olan Dil hizmeti ile bir ifadeyi çevirebilir.
  • Bağlandıkları dosyayı değiştirebilirler ancak yetkilendirme gerektirdiği için diğer dosyalara erişemezler.
  • Karmaşık güvenlik kısıtlamalarına bağlı olarak, mevcut kullanıcının kimliğini belirleyebilir veya belirleyemeyebilir.
  • 30 saniyeden uzun süre yayınlanamaz.
  • Belirli durumlarda Düzenleyici Eklentileri, onOpen(e) ve onEdit(e) basit tetikleyicilerini bazı ek komplikasyonlar sunan yetkilendirmesiz 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, bir forma yanıt verildiğinde değil, yalnızca düzenlemek için form açıldığında çalışır.) onOpen(e), Google E-Tablolar, Slaytlar, Dokümanlar veya Formlar'a özel menü öğeleri eklemek için en yaygın şekilde 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, bir kullanıcı Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar'dan 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)'ün yapabileceği işlemler konusunda 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 kendine ç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) tetikleyicisi, 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 etkinlik nesnesinde bulunan bilgileri kullanır. Örneğin, aşağıdaki onEdit(e) işlevi, hücrede en son ne zaman düzenlendiğini 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)

onSelectionChange(e) tetikleyicisi, bir kullanıcı 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ürede birden fazla hücre arasında hareket ederse gecikmeyi azaltmak için bazı seçim değişikliği etkinlikleri atlanabilir. Örneğin, birbirinden iki saniye içinde çok sayıda 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)

doGet(e) tetikleyicisi, bir kullanıcı bir web uygulamasını ziyaret ettiğinde veya bir program bir web uygulamasına HTTP GET isteği gönderdiğinde otomatik olarak çalışır. doPost(e) tetikleyicisi, bir program bir 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 gösterilmektedir. doGet(e) ve doPost(e)'ın yukarıda listelenen kısıtlamalara tabi olmadığını unutmayın.

Kullanılabilen tetikleyici türleri

Basit tetikleyicilerdeki kısıtlamalar, bu tetikleyicilerin ihtiyaçlarınızı karşılamasını 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çılış tetikleyicilerini destekler ancak yalnızca E-Tablolar, Dokümanlar ve Formlar, yüklenebilir açılış 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 için açık etkinliği, bir kullanıcı yanıt vermek üzere formu açtığında değil, bir düzenleyici formu değiştirmek için açtığında gerçekleşir.