Basit Tetikleyiciler

Tetikleyiciler, 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 kullanıcı Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar dosyasını açtığında yürütülen onOpen(e) işlevi gibi Apps Komut Dosyası'nda yerleşik olarak bulunan ayrılmış bir dizi işlevdir. Yüklenebilir tetikleyiciler, basit tetikleyicilerden daha fazla özellik sunar ancak kullanılmadan önce etkinleştirilmelidir. Her iki tetikleyici türü için 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), kullanıcı düzenleme iznine sahip olduğu bir e-tabloyu, dokümanı, sunuyu veya formu açtığında çalıştırılı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), kullanıcı e-tablodaki bir değeri değiştirdiğinde çalıştırılır.
• onSelectionChange(e), kullanıcı bir e-tablodaki seçimi değiştirdiğinde çalıştırılı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ıştırılı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 aktarılan bir etkinlik nesnesidir. Nesne, tetikleyicinin etkinleşmesine neden olan bağlam hakkında bilgi içerir ancak bu kullanımın kullanılması isteğe bağlıdır.

Kısıtlamalar

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

• Komut dosyasının bir Google E-Tablolar, Slaytlar, Dokümanlar veya Formlar dosyasına bağlı ya da bu uygulamalardan birini genişleten bir eklenti olması gerekir.
• Bir dosya salt okuma (görüntüleme veya yorum yapma) modunda açıldığında bu etiketler çalışmaz.
• Komut dosyası yürütme ve API istekleri, tetikleyicilerin çalıştırılması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ıştırılmaz.
• Ancak yetkilendirme gerektiren hizmetlere erişemezler. Örneğin, Gmail hizmeti yetkilendirme gerektirdiği için 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ği için diğer dosyalara erişemezler.
• Bu yöneticiler, karmaşık güvenlik kısıtlamaları kümesine bağlı olarak mevcut kullanıcının kimliğini belirleyip belirleyemeyebilir.
• 30 saniyeden uzun süre çalıştırılamazlar.
• Düzenleyici Eklentileri, belirli durumlarda onOpen(e) ve onEdit(e) basit tetikleyicilerini yetkilendirme olmadan modda çalıştırır. Bu da bazı ek komplikasyonlara neden olur. Daha fazla bilgi için eklenti yetkilendirme yaşam döngüsü kılavuzuna göz atın.
• Basit tetikleyiciler, Apps Komut Dosyası tetikleyicisi olan kota sınırlarına tabidir.

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

onOpen(e)

Bir kullanıcı düzenleme iznine sahip olduğu bir e-tabloyu, dokümanı, sunuyu veya formu açtığında onOpen(e) tetikleyicisi otomatik olarak çalışır. (Tetikleyici bir forma yanıt verirken değil, yalnızca düzenlemek için formu açarken çalışır.) onOpen(e), en yaygın olarak Google E-Tablolar, Slaytlar, Dokümanlar veya Formlar'a özel menü öğeleri eklemek için kullanılır.

/**
 * 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)

Kullanıcı Google Dokümanlar, E-Tablolar, Slaytlar veya Formlar'dan bir Düzenleyici Eklentisi yüklediğinde onInstall(e) tetikleyicisi otomatik olarak çalışır. Kullanıcı eklentiyi Google Workspace Marketplace web sitesinden yüklediğinde tetikleyici çalışmaz. onInstall(e) hizmetinin yapabileceği işlemlerle 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) çağrısı yapmaktır. Sonuçta bir eklenti yüklendiğinde dosya zaten açıktır ve bu nedenle, dosya yeniden açılmadıkça onOpen(e) kendi başına çalışmaz.

/**
 * 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ücrenin son düzenlendiği zamanı kaydeden bir yorum ayarlar.

/**
 * 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, birbirlerinden sonraki iki saniye içinde çok sayıda seçim değişikliği yapılırsa onSelectionChange(e) tetikleyicisi yalnızca ilk ve son seçim değişiklikleri tarafından etkinleştirilir.

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

/**
 * 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, kullanıcı bir 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ıştırılır. Bu tetikleyiciler web uygulamaları, HTML hizmeti ve İçerik hizmeti kılavuzlarında daha fazla gösterilmiştir. doGet(e) ve doPost(e) için yukarıda listelenen kısıtlamalara tabi olmadığını unutmayın.

Kullanılabilir tetikleyici türleri

Basit tetikleyicilerdeki kısıtlamalar bunların ihtiyaçlarınızı karşılamalarını engelliyorsa bunun yerine yüklenebilir bir tetikleyici çalışabilir. Aşağıdaki tabloda her etkinlik türü için ne tür tetikleyicilerin kullanılabildiği özetlenmiştir. Örneğin, Google E-Tablolar, Slaytlar, Formlar ve Dokümanlar 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ç	function onOpen(e)
Düzenle	function onEdit(e)
Seçim değişikliği	function onSelectionChange(e)
Yükle	function onInstall(e)
Değiştir
Form gönderme
Zaman odaklı (saat)
Get	function doGet(e)
Gönderi	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 değişiklik yapmak için formu açtığında gerçekleşir.