Yüklenebilir Tetikleyiciler

Basit tetikleyiciler gibi, yüklenebilir tetikleyiciler de Apps Script'in bir doküman açma gibi belirli bir etkinlik gerçekleştiğinde işlevi otomatik olarak çalıştırmasına olanak tanır. Ancak yüklenebilir tetikleyiciler, basit tetikleyicilerden daha fazla esneklik sunar: Yetkilendirme gerektiren hizmetleri çağırabilir, zamana dayalı (saat) tetikleyiciler de dahil olmak üzere çeşitli ek etkinlik türleri sunar ve programatik olarak kontrol edilebilir. Hem basit hem de yüklenebilir tetikleyiciler için Apps Script, tetiklenen işleve etkinliğin gerçekleştiği bağlamla ilgili bilgileri içeren bir etkinlik nesnesi iletir.

Not: Eklentilerde tetikleyicilerin nasıl kullanılacağı hakkında daha fazla bilgi edinmek için Google Workspace Eklentileri için Tetikleyiciler başlıklı makaleyi inceleyin.

Kısıtlamalar

Yüklenebilir tetikleyiciler, basit tetikleyicilerden daha fazla esneklik sunsa da bazı kısıtlamalara tabidir:

• Dosya salt okuma (görüntüleme veya yorum) modunda açılırsa bu makrolar çalışmaz. Bağımsız komut dosyalarında, tetikleyicilerin düzgün şekilde çalışabilmesi için kullanıcıların komut dosyası dosyasına en azından görüntüleme erişimi olması gerekir.

• Komut dosyası yürütmeleri ve API istekleri, tetikleyicilerin çalışmasına neden olmaz. Örneğin, yeni bir form yanıtı göndermek için FormResponse.submit() yönteminin çağrılması, formun gönderme tetikleyicisinin çalıştırılmasına neden olmaz.

  Not: Bu kısıtlamanın istisnası Form.submitGrades()'dir. Kodunuzda onFormSubmit tetikleyici kullanılıyorsa Form.submitGrades() çağrısı onFormSubmit koşulunu tetikler ve sonsuz döngüye neden olur. Sonsuz döngüyü önlemek için submitGrades() çağrısından önce notların zaten mevcut olup olmadığını kontrol eden bir kod ekleyin.

• Yüklenebilir tetikleyiciler her zaman onları oluşturan kullanıcının hesabı altında çalışır. Örneğin, yüklenebilecek bir açma tetikleyicisi oluşturursanız bu tetikleyici, iş arkadaşınız dokümanı açtığında (iş arkadaşınız düzenleme erişimine sahipse) çalışır ancak hesabınız olarak çalışır. Yani bir doküman açıldığında e-posta göndermek için bir tetikleyici oluşturursanız e-posta her zaman hesabınızdan gönderilir. Ancak her hesap için yüklenebilecek bir tetikleyici oluşturabilirsiniz. Bu durumda her hesaptan bir e-posta gönderilir.

• Belirli bir hesap, ikinci hesaptan yüklenen tetikleyicileri göremez ancak ilk hesap bu tetikleyicileri etkinleştirebilir.

• Yüklenebilir tetikleyiciler, Apps Komut Dosyası tetikleyicisi için kota sınırlarına tabidir.

Zamana dayalı tetikleyiciler

Zamana dayalı tetikleyici (saat tetikleyicisi olarak da bilinir), Unix'teki cron işine benzer. Zamana dayalı tetikleyiciler, komut dosyalarının belirli bir zamanda veya tekrarlanan bir aralıkta (dakikada bir veya ayda bir gibi) yürütülmesine olanak tanır. (Eklentiler, zamana dayalı tetikleyiciyi en fazla saatte bir kullanabilir.) Saat biraz rastgele olabilir. Örneğin, tekrarlanan 09:00 tetikleyicisi oluşturursanız Apps Script 09:00 ile 10:00 arasında bir saat seçer ve tetikleyicinin tekrar tetiklenmesi için 24 saat geçmesi gerektiğinden bu zamanlamayı her gün tutar.

Aşağıda, uygulamanın bulunduğu her alana her dakika bir mesaj yayınlayan bir Google Chat uygulaması örneği verilmiştir:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = '[e-mail]';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Etkinliğe dayalı tetikleyiciler

Yüklenebilir, etkinliğe dayalı tetikleyiciler kavram olarak onOpen() gibi basit tetikleyicilere benzer, ancak ek etkinliklere yanıt verebilir ve farklı davranırlar.

Örneğin, Google E-Tablolar için yüklenilebilir açık tetikleyici, basit onOpen() tetikleyici gibi düzenleme erişimi olan herhangi bir kullanıcı tarafından e-tablo açıldığında etkinleştirilir. Ancak yüklenebilir sürüm, yetkilendirme gerektiren hizmetleri çağırabilir. Yüklenebilir sürüm, e-tabloyu düzenleme erişimi olan başka bir kullanıcı açsa bile tetikleyiciyi oluşturan kullanıcının yetkisiyle çalışır.

Google Workspace uygulamaları için yüklenebilecek birkaç tetikleyici vardır:

• Kullanıcı düzenleme iznine sahip olduğu bir e-tabloyu, dokümanı veya formu açtığında yüklenebilir bir open tetikleyicisi çalışır.
• Kullanıcı bir e-tablodaki değeri değiştirdiğinde yüklenebilir bir düzenleme tetikleyicisi çalışır.
• Kullanıcı, e-tablonun yapısını değiştirdiğinde (ör. yeni bir sayfa ekleme veya sütun kaldırma) yüklenebilir değişiklik tetikleyicisi çalışır.
• Kullanıcı bir forma yanıt verdiğinde, yüklenebilecek bir form gönderme tetikleyicisi çalışır. Form gönderme tetikleyicisinin iki sürümü vardır: Google Formlar için ve form bir e-tabloya gönderiliyorsa E-Tablolar için.
• Yüklenebilir bir takvim etkinliği tetikleyicisi, kullanıcının takvim etkinlikleri güncellendiğinde (oluşturulduğunda, düzenlendiğinde veya silindiğinde) çalışır.

Yüklenebilir tetikleyicileri bağımsız ve bağlı komut dosyalarında kullanabilirsiniz. Örneğin, bağımsız bir komut dosyası, TriggerBuilder.forSpreadsheet(key) işlevini çağırıp e-tablonun kimliğini ileterek rastgele bir Google E-Tablolar dosyası için programlı olarak yüklenebilecek bir tetikleyici oluşturabilir.

Tetikleyicileri manuel olarak yönetme

Komut dosyası düzenleyicide manuel olarak yüklenebilir bir tetikleyici oluşturmak için aşağıdaki adımları uygulayın:

1. Apps Komut Dosyası projenizi açın.
2. Sol tarafta Tetikleyiciler'i tıklayın.
3. Sağ altta, Tetikleyici Ekle'yi tıklayın.
4. Oluşturmak istediğiniz tetikleyici türünü seçin ve yapılandırın.
5. Kaydet'i tıklayın.

Tetikleyicileri programatik olarak yönetme

Komut dosyası hizmeti ile tetikleyicileri programatik olarak da oluşturup silebilirsiniz. ScriptApp.newTrigger(functionName) işlevini çağırarak başlayın. Bu işlev, TriggerBuilder döndürür.

Aşağıdaki örnekte, biri 6 saatte bir, diğeri de her pazartesi saat 09:00'da (komut dosyanızın ayarlandığı saat diliminde) olmak üzere iki zamana dayalı tetikleyicinin nasıl oluşturulacağı gösterilmektedir.

tetikleyiciler/tetikleyiciler.gs

GitHub'da göster

/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .everyHours(6)
      .create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(9)
      .create();
}

Aşağıdaki örnekte, bir e-tablo için yüklenebilir açık tetikleyicinin nasıl oluşturulacağı gösterilmektedir. Basit bir onOpen() tetikleyicisinin aksine, yüklenebilir tetikleyicinin komut dosyasının e-tabloya bağlı olması gerekmediğini unutmayın. Bu tetikleyiciyi bağımsız bir komut dosyasından oluşturmak için SpreadsheetApp.getActive() öğesini SpreadsheetApp.openById(id) çağrısıyla değiştirin.

tetikleyiciler/tetikleyiciler.gs

GitHub'da göster

/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger('myFunction')
      .forSpreadsheet(ss)
      .onOpen()
      .create();
}

Mevcut bir yüklenebilir tetikleyiciyi programatik olarak değiştirmek için tetikleyiciyi silmeniz ve yeni bir tetikleyici oluşturmanız gerekir. Bir tetikleyicinin kimliğini daha önce depoladıysanız kimliği aşağıdaki işleve bağımsız değişken olarak ileterek silebilirsiniz.

triggers/triggers.gs

GitHub'da göster

/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Tetikleyicilerdeki hatalar

Yüklenebilir bir tetikleyici etkinleştiğinde ancak işlev bir istisna oluşturduğunda veya başka bir şekilde başarılı bir şekilde çalışamadığında, ekranınızda bir hata mesajı görmezsiniz. Sonuçta, zamana dayalı bir tetikleyici çalıştırıldığında veya başka bir kullanıcı form gönderme tetikleyicinizi etkinleştirdiğinde bilgisayarınızın başında olmayabilirsiniz.

Bunun yerine Apps Komut Dosyası size aşağıdaki gibi bir e-posta gönderir:

From: [e-mail]
Subject: Summary of failures for Google Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

E-postada tetikleyiciyi devre dışı bırakma veya yeniden yapılandırma bağlantısı yer alır. Komut dosyası bir Google E-Tablolar, Dokümanlar veya Formlar dosyasına bağlıysa e-postada söz konusu dosyanın bağlantısı da yer alır. Bu bağlantılar, tetikleyiciyi devre dışı bırakmanıza veya hatayı düzeltmek için komut dosyasını düzenlemenize olanak tanır.

Not: Eklentiler tarafından oluşturulan yüklenebilir tetikleyiciler, kullanıcılara bu e-posta bildirimlerini göndermez.

Google Hesabınızla ilişkilendirilmiş tüm tetikleyicileri incelemek ve artık ihtiyacınız olmayan tetikleyicileri devre dışı bırakmak için aşağıdaki adımları uygulayın:

1. script.google.com adresine gidin.
2. Sol tarafta Tetikleyicilerim'i tıklayın.

3. Bir tetikleyiciyi silmek için tetikleyicinin sağındaki Diğer > Tetikleyiciyi sil'i tıklayın.

   Not: onOpen() gibi basit tetikleyiciler bu sayfadan devre dışı bırakılamaz. Bunun yerine, uygun komut dosyasını düzenlemeniz ve onOpen() işlevini kaldırmanız veya yeniden adlandırmanız gerekir.

Eklentilerdeki tetikleyiciler

Yüklenebilir tetikleyicilere ek olarak, eklentilerde manifest tetikleyicileri de kullanabilirsiniz. Daha fazla bilgi için Google Workspace eklentileri için tetikleyiciler başlıklı makaleyi inceleyin.