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 fazla esneklik sunar. Yetkilendirme gerektiren hizmetleri çağırabilirler, zamana bağlı (saat) tetikleyiciler de dahil olmak üzere çeşitli ek etkinlik türleri sunarlar ve programatik olarak kontrol edilebilirler. Apps Komut Dosyası, hem basit hem de yüklenebilir tetikleyiciler için 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ışmazlar. Bağımsız komut dosyalarında, tetikleyicilerin düzgün şekilde çalışması için kullanıcıların komut dosyası için en azından görüntüleme erişimine sahip olması gerekir.

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

  • Yüklenebilir tetikleyiciler her zaman onları 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 (iş arkadaşınızın düzenleme erişimi varsa) çalışır, ancak sizin hesabınız olarak çalışır. Diğer bir deyişle, bir doküman açıldığında e-posta göndermek için bir tetikleyici oluşturursanız e-posta, dokümanı açan hesaptan değil, her zaman sizin 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.

  • Belirli bir hesap, ilk hesap tarafından etkinleştirilse bile ikinci bir hesaptan yüklenen tetikleyicileri göremez.

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

Zamana dayalı tetikleyiciler

Zamana dayalı tetikleyici (saat tetikleyicisi olarak da adlandırılır), Unix'teki cron işine benzer. Zaman odaklı tetikleyiciler, komut dosyalarının belirli bir zamanda veya yinelenen bir aralıkta, yani dakikada bir veya ayda bir kez yürütülmesine olanak tanır. (Eklentinin zamana dayalı bir tetikleyiciyi en fazla saatte bir kez kullanabileceğini unutmayın.) Saatler biraz rastgele olabilir. Örneğin, 09:00'da yinelenen bir tetikleyici oluşturursanız Apps Komut Dosyası, 09:00 ile 10:00 arasında bir saat seçer ve ardından bu zamanlamayı günden güne tutarlı hâle getirir. 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 verebilirler ve farklı davranırlar.

Örneğin, basit onOpen() tetikleyicisinde olduğu gibi, Google E-Tablolar için yüklenebilir açık tetikleyici, e-tablo düzenleme erişimine sahip herhangi bir kullanıcı tarafından her açıldığında etkinleşir. 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 yetkisiyle çalışır.

Google Workspace uygulamaları için farklı yüklenebilir tetikleyiciler vardır:

  • Kullanıcı düzenleme iznine sahip olduğu bir e-tabloyu, dokümanı veya formu açtığında yüklenebilir açık bir tetikleyici çalışır.
  • Kullanıcı, bir e-tablodaki değeri değiştirdiğinde yüklenebilir bir düzenleme tetikleyicisi çalışır.
  • Yüklenebilir bir değişiklik tetikleyicisi, kullanıcı e-tablonun yapısını değiştirdiğinde (örneğin, yeni bir sayfa ekleyerek veya bir sütun kaldırarak) çalışır.
  • Kullanıcı bir forma yanıt verdiğinde yüklenebilir bir form gönderme tetikleyicisi çalışır. Form gönderme tetikleyicisinin biri Google Formlar için, diğeri form bir e-tabloya gönderilirse E-Tablolar için olmak üzere iki sürümü vardır.
  • Bir kullanıcının takvim etkinlikleri güncellendiğinde, düzenlendiğinde veya silindiğinde yüklenebilir bir takvim etkinliği tetikleyicisi çalışır.

Bağımsız ve bağlı komut dosyalarında yüklenebilir tetikleyiciler kullanabilirsiniz. Örneğin, bağımsız bir komut dosyası, TriggerBuilder.forSpreadsheet(key) yöntemini çağırıp e-tablonun kimliğini ileterek programatik olarak rastgele bir Google E-Tablolar dosyası için 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 aşağıdaki adımları uygulayın:

  1. Apps Komut Dosyası projenizi açın.
  2. Solda, Tetikleyiciler'i tıklayın.
  3. Sağ alttan 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

Ayrıca Komut Dosyası hizmetiyle tetikleyicileri programatik olarak oluşturup silebilirsiniz. TriggerBuilder döndüren ScriptApp.newTrigger(functionName) yöntemini çağırarak başlayın.

Aşağıdaki örnekte, biri 6 saatte bir, diğeri her pazartesi günü sabah 9'da (komut dosyanızın ayarlandığı saat diliminde) olmak üzere, zamana dayalı iki 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();
}

Sıradaki örnekte, e-tablo için yüklenebilir bir 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() kodunu SpreadsheetApp.openById(id) çağrısıyla değiştirmeniz yeterlidir.

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 bu tetikleyiciyi 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şir ancak işlev bir istisna atarsa veya başka bir şekilde başarılı bir şekilde çalışmazsa ekranınızda hata mesajı görmezsiniz. Sonuçta, zamana dayalı bir tetikleyici çalıştığında veya başka bir kullanıcı form gönderme tetikleyicinizi etkinleştirdiğinde bilgisayarınızın başında bile olmayabilirsiniz.

Bunun yerine, Apps Komut Dosyası size aşağıdaki gibi 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çeriyor. 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ızı veya hatayı düzeltmek için komut dosyasını düzenlemenizi sağlar.

Google Hesabınızla ilişkili 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ğ tarafında Diğer > Tetikleyiciyi sil'i tıklayın.

Eklentilerdeki yüklenebilir tetikleyiciler

Eklentilerde yüklenebilir tetikleyici kullanma hakkında daha fazla bilgi için Eklenti tetikleyicileri konusuna bakın.