Yüklenebilir Tetikleyiciler

Basit tetikleyiciler gibi yüklenebilir tetikleyiciler de, 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. Bununla birlikte yüklenebilir tetikleyiciler basit tetikleyicilerden daha esnektir: Yetkilendirme gerektiren hizmetleri çağırabilir, zamana bağlı (saat) tetikleyiciler dahil olmak üzere çeşitli ek etkinlik türleri sunar ve programatik olarak kontrol edilebilirler. Apps Komut Dosyası, hem basit hem de yüklenebilir tetikleyicilerde, tetiklenen işleve etkinliğin gerçekleştiği bağlam hakkında bilgi içeren bir etkinlik nesnesi iletir.

Kısıtlamalar

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

  • Bir dosya salt okuma (görüntüleme veya yorum yapma) modunda açılırsa çalıştırılmazlar. Bağımsız komut dosyalarında, tetikleyicilerin düzgün çalışması için kullanıcıların en azından komut dosyası görüntüleme erişimine sahip olması gerekir.

  • Komut dosyası yürütme ve API istekleri, tetikleyicilerin çalıştırılması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.

  • Yüklenebilir tetikleyiciler her zaman bunları oluşturan kullanıcının hesabı altında çalışır. Örneğin, yüklenebilir bir açık tetikleyici oluşturursanız bu tetikleyici, iş arkadaşınız dokümanı açtığında çalışır (iş arkadaşınızın düzenleme erişimi varsa) ancak sizin hesabınız olarak çalışır. Yani, bir doküman açıldığında e-posta gönderecek bir tetikleyici oluşturduğunuzda e-posta her zaman hesabınızdan gönderilir (dokümanı açan hesaptan değil) her zaman hesabınızdan gönderilir. Ancak her hesap için yüklenebilir bir tetikleyici oluşturabilirsiniz. Bu durumda her hesaptan bir e-posta gönderilir.

  • İlk hesap yine de bu tetikleyicileri etkinleştirebilse bile, belirli bir hesap ikinci bir hesaptan yüklenen tetikleyicileri göremez.

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

Zamana dayalı tetikleyiciler

Zamana dayalı bir tetikleyici (saat tetikleyici olarak da adlandırılır) Unix'teki cron işine benzer. Zamana dayalı tetikleyiciler, komut dosyalarının belirli bir zamanda veya yinelenen bir aralıkta, dakikada bir olmak üzere veya ayda bir gibi seyrek şekilde yürütülmesini sağlar. (Eklentilerin, zaman odaklı bir tetikleyiciyi saatte en fazla bir kez kullanabileceğini unutmayın.) Saat biraz rastgele olabilir. Örneğin, yinelenen bir 09:00 tetikleyicisi oluşturursanız Apps Komut Dosyası, 09:00 ile 10:00 arasında bir saat seçer ve ardından bu zamanlamanın günden güne tutarlı kalmasını sağlar. Böylece, tetikleyici tekrar etkinleşmeden önce 24 saat geçer.

Aşağıda, uygulamanın bulunduğu her alana dakikada 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 = 'service-account@project-id.iam.gserviceaccount.com';

// 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üklenebilir açık tetikleyici, basit onOpen() tetikleyicisinde olduğu gibi, e-tablo düzenleme erişimine sahip herhangi bir kullanıcı tarafından 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şimine sahip başka bir kullanıcı açsa bile tetikleyiciyi oluşturan kullanıcının yetkilendirmesiyle çalışır.

Google Workspace uygulamalar için yüklenebilir 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ı e-tablodaki bir 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 sayfa ekleme veya sütunu kaldırma) yüklenebilir değişiklik tetikleyicisi çalışır.
  • Kullanıcı bir forma yanıt verdiğinde yüklenebilir bir form gönderme tetikleyicisi çalışır. Form gönderme tetikleyicisinin iki sürümü vardır. Biri Google Formlar için, diğeri form e-tabloya gönderildiğinde E-Tablolar için kullanılabilir.
  • Bir kullanıcının takvim etkinlikleri güncellendiğinde (oluşturulduğunda, düzenlendiğinde veya silindiğinde), yüklenebilir bir takvim etkinliği tetikleyicisi ç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) çağırıp e-tablonun kimliğini ileterek rastgele bir Google E-Tablolar dosyası için programatik olarak yüklenebilir bir tetikleyici oluşturabilir.

Tetikleyicileri manuel olarak yönetme

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

  1. Apps Komut Dosyası projenizi açın.
  2. Solda Tetikleyiciler'i tıklayın.
  3. Sağ altta Tetikleyici Ekle'yi tıklayın.
  4. Oluşturmak istediğiniz tetikleyici türünü seçip 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) çağrısı yaparak başlayın. Bu çağrı, TriggerBuilder döndürecektir.

Aşağıdaki örnekte, biri 6 saatte bir, diğeri 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.

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

triggers/triggers.gs
/**
 * 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 silip yenisini 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
/**
 * 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ığında veya form gönderme tetikleyicinizi başka bir kullanıcı etkinleştirdiğinde, bilgisayar başında bile olmayabilirsiniz.

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

From: noreply-apps-scripts-notifications@google.com
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-posta, tetikleyiciyi devre dışı bırakmak veya yeniden yapılandırmak için bir bağlantı içerir. Komut dosyası bir Google E-Tablolar, Dokümanlar veya Formlar dosyasına bağlıysa e-postada bu dosyanın bağlantısı da bulunur. Bu bağlantılar, tetikleyiciyi devre dışı bırakmanıza veya hatayı düzeltmek için komut dosyasını düzenlemenize olanak tanır.

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. Solda Tetikleyicilerim'i tıklayın.

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

Eklentilerdeki tetikleyiciler

Yüklenebilir tetikleyicilere ek olarak, eklentilerde manifest tetikleyicileri kullanabilirsiniz. Daha fazla bilgi için Google Workspace Eklentileri için Tetikleyiciler bölümüne bakın.