Basit Tetikleyiciler

Tetikleyiciler, Google 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 Komut Dosyası, 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.

Google Workspace eklenti projelerinde tetikleyicileri kullanma hakkında bilgi edinmek için Google Workspace eklentileri için tetikleyiciler başlıklı makaleyi inceleyin.

Başlarken

Basit bir tetikleyici kullanmak için şu ayrılmış işlev adlarından birini kullanan bir işlev oluşturun:

• 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 çalışmasına 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ği için ç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 okunur (görüntüleme veya yorum yapma) 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ı kümesine bağlı olarak mevcut kullanıcının kimliğini belirleyebilir veya belirleyemeyebilirler.
• 30 saniyeden uzun süre yayınlanamazlar.
• Belirli durumlarda, Düzenleyici eklentileri, onOpen(e) ve onEdit(e) basit tetikleyicilerini yetkilendirme gerektirmeyen bir modda çalıştırır. Bu durum, bazı ek sorunlara yol açar. 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) tetikleyici, bir 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 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)

onInstall(e) tetikleyici, 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) işlevinin en yaygın kullanım şekli, özel menüler eklemek için onOpen(e) işlevini çağırmaktır. Bir eklenti yüklendikten sonra dosya zaten açık olduğundan dosya yeniden açılmadığı sürece onOpen(e) kendi başına çalışmaz. onInstall(e)'nın yapabilecekleriyle ilgili belirli kısıtlamalar olduğunu unutmayın. Yetkilendirme hakkında daha fazla bilgi edinin.

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

/**
 * 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()}`);
}

onEdit() tetikleyicisi yalnızca 2 tetikleyici etkinliğini sıraya alır.

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

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ıya 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, 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 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ç	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
Zamana dayalı (saat)
Yükle	function doGet(e)
Gönderi	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.