Başlangıç projesi oluşturma

Bu belgede, uygulamanızın veya hizmetinizin bir etkinlik gerçekleştiğinde Google Workspace Studio'yu bilgilendirmesine ve akış yürütme başlatmasına olanak tanıyan bir başlatıcı oluşturma açıklanmaktadır. API'de başlangıçlar workflowTriggers olarak adlandırılır.

Başlatıcı, bir akışı başlatırken adım, bir akışı oluşturan görevler dizisindeki tek bir görevdir. Başlangıç uygulaması oluşturarak kullanıcıların, uygulamanızdaki veya hizmetinizdeki anlık etkinliklere tepki veren otomatik akışlar ayarlamasına olanak tanırsınız.

Başlatıcı oluşturmak için eklenti manifest dosyasında başlatıcıyı bildirmeniz ve Google Apps Komut Dosyası'nda yaşam döngüsü geri çağırmalarını uygulamanız veya Google Workspace Studio API uç noktasına yükler göndererek başlatıcıyı tetiklemeniz gerekir.

Ön koşullar ve OAuth yetkilendirmesi

Uygulamanızın veya hizmetinizin Workspace Studio API uç noktasıyla iletişim kurabilmesi için OAuth 2.0 kullanarak kimlik doğrulaması yapması gerekir. Uygulama, yetkilendirme sırasında kullanıcılardan aşağıdaki özel OAuth kapsamını istemelidir:

https://www.googleapis.com/auth/workspace.studio.trigger

Bu kapsam, uygulamanın Workspace Studio API'sini çağırmasına ve kullanıcının bu başlangıç için yapılandırdığı akışları tetiklemesine yetki verir.

Çevrimdışı erişim ve yenileme jetonları

Başlatıcılar, harici hizmette bir etkinlik gerçekleştiğinde Workspace Studio'yu eşzamansız olarak bilgilendirdiğinden (bu durum, kullanıcı bir akışı yapılandırdıktan saatler, günler veya aylar sonra gerçekleşebilir) hizmetiniz, API uç noktasını çağırırken geçerli bir OAuth 2.0 erişim jetonu sağlamalıdır.

Google tarafından eklenti etkinliği nesnesinde (ör. başlangıç yapılandırması veya yaşam döngüsü geri çağırma yöntemi istekleri sırasında) sağlanan erişim jetonu kısa ömürlüdür ve yalnızca 1 saat geçerlidir. Gelecekte başlangıç etkinliklerini eşzamansız olarak tetiklemek için yeterli değil. Workspace Studio API'yi zaman içinde çağırmak için hizmetinizin, gerektiğinde yeni erişim jetonları oluşturmak üzere çevrimdışı bir yenileme jetonu olması gerekir.

Yetkilendirmeyi nasıl işleyeceğiniz ve yenileme jetonunu nasıl alacağınız, eklenti çalışma zamanınıza bağlıdır:

  • HTTP eklentileri (alternatif çalışma zamanları): HTTP eklentileri için arka uç hizmetiniz, çevrimdışı erişim (access_type=offline) isteğinde bulunmak ve yenileme jetonu almak üzere yerleşik eklenti yetkilendirmesinden bağımsız ayrı bir OAuth 2.0 yetkilendirme akışı uygulamalıdır.

    Kullanıcı Workspace Studio'da başlangıç uygulamasını yapılandırırken oturum açma veya yetkilendirme kartı göstererek kullanıcıları bu bağlantıyı yetkilendirmeye yönlendirebilirsiniz. Yetkilendirme kartlarını döndürme ve OAuth akışını işleme hakkında daha fazla bilgi için Google Workspace eklentinizi üçüncü taraf hizmetine bağlama başlıklı makaleyi inceleyin (Google Workspace'i bağlandığınız üçüncü taraf hizmeti olarak ele alarak).

    Arka uç hizmetiniz, yenileme jetonunu güvenli bir şekilde saklamalıdır (ör. hizmetinizin veritabanında triggerId ile birlikte) ve başlatıcının notifyUri veya triggers.fire API uç noktasına istek göndermeden önce bir etkinlik gerçekleştiğinde yeni bir erişim jetonu almak için kullanmalıdır.

  • Google Apps Komut Dosyası eklentileri: Etkinlikleri yoklamak için planlanmış (zamana dayalı) tetikleyiciler kullanan Google Apps Komut Dosyası tabanlı eklentiler, bağımsız bir OAuth akışı uygulamayı atlayabilir. Planlanmış tetikleyiciler doğrudan Google Apps Komut Dosyası çalışma zamanı ortamında çalıştığından Google Apps Komut Dosyası, manifestte belirtilen kapsamları kullanarak OAuth jetonlarını otomatik olarak yönetir ve yeniler.

Başlatıcıyı manifest dosyasında tanımlayın

Başlatıcı tanımlamak için başlatıcıyı eklenti manifest dosyanıza (appsscript.json) addOns.studio.flows.workflowElements bloğuna ekleyin. Bu yapılandırma hem Apps Komut Dosyası hem de HTTP çalışma zamanları (alternatif çalışma zamanları) için gereklidir. Öğeyi workflowAction yerine workflowTrigger olarak yapılandırın (, bir adım tanımlanırken kullanılır). Daha fazla bilgi için Google Workspace eklentileri için manifest yapısı başlıklı makaleyi inceleyin.

workflowTrigger bloğunda şunları belirtin:

  • inputs: Kullanıcının yapılandırma kartında yapılandırdığı değişkenler (ör. proje adı, kaynak filtresi vb.).
  • outputs: Akışta başlatıcı tarafından sonraki adımlara döndürülebilen değişkenler.
  • onConfigFunction: Kullanıcı yapılandırma arayüzünü gösteren geri çağırma işlevinin adı.
  • onManageFunction: Google tarafından başlatıcı abonelik oluşturma ve silme işlemlerini yönetmek için çağrılan geri çağırma işlevinin adı.

Aşağıdaki kod örneğinde, bir etkinlik başlatıcı için örnek manifest tanımı gösterilmektedir:

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Trigger App",
      "logoUrl": "https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/start/default/24px.svg",
      "useLocaleFromApp": true
    },
    "studio": {
      "flows": {
        "workflowElements": [
          {
            "id": "triggerDemo",
            "state": "ACTIVE",
            "name": "Event Trigger",
            "description": "Fires when a event occurs in the app.",
            "workflowTrigger": {
              "inputs": [
                {
                  "id": "projectId",
                  "description": "The project identifier to watch.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                }
              ],
              "outputs": [
                {
                  "id": "eventName",
                  "description": "The name of the triggered event.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                },
                {
                  "id": "eventMessage",
                  "description": "Detailed event message description.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                }
              ],
              "onConfigFunction": "onConfigTrigger",
              "onManageFunction": "onManageTrigger"
            }
          }
        ]
      }
    }
  }
}

Başlangıç aboneliğinin yaşam döngüsünü yönetme

Bir kullanıcı, başlangıç öğenizi içeren bir akışı yapılandırıp etkinleştirdiğinde veya akış devre dışı bırakıldığında ya da silindiğinde Google, manifestte belirtilen onManageFunction geri çağırma işlevini kullanarak eklentinizi çağırır.

Yaşam döngüsü olayı nesnesi

Geri çağırma işlevi, işlem bağlamını içeren bir WorkflowEventObject alır. Başlangıçta bu özellikler arasında şunlar yer alıyor:

  • Tetikleyici Oluşturma (event.workflow.triggerCreation): Akış yayınlandığında veya etkinleştirildiğinde tetiklenir.

    • triggerId: Bu başlangıç kaydı örneğini tanımlayan benzersiz bir UUID dizesi.

    • notifyUri: Bu başlangıç kaydıyla ilişkili benzersiz REST API uç nokta URL'si (örneğin, https://workspacestudio.googleapis.com/v1/triggers/YOUR_TRIGGER_ID:fire).

    • inputs: Kullanıcı tarafından karttan yapılandırılan değişken girişleri.

  • Tetikleyici Silme (event.workflow.triggerDeletion): Başlatıcı akıştan kaldırıldığında veya akışın tamamı devre dışı bırakıldığında ya da silindiğinde tetiklenir.

    • triggerId: Temizlenecek abonelik örneğinin benzersiz UUID dizesi.

Alternate Runtimes (HTTP API) aboneliğinin yaşam döngüsü

Alternatif çalışma zamanları kullanılarak oluşturulan eklentilerde, abonelik yaşam döngüsü bildirimleri, onManageFunction geri çağırma işlevi tarafından belirtilen işlem adıyla birlikte eklentinin yapılandırılmış HTTP uç noktası URL'sine HTTP POST istekleri kullanılarak gönderilir. Yük, WorkflowEventObject öğesinin JSON gösterimiyle eşleşiyor.

Alternatif çalışma zamanları hakkında daha fazla bilgi için HTTP uç noktalarını kullanarak Google Workspace eklentisi oluşturma başlıklı makaleyi inceleyin.

Apps Komut Dosyası'nda yaşam döngüsü geri çağırma yöntemlerini uygulama

Aşağıdaki Apps Komut Dosyası örneğinde, kullanıcı arayüzü kartının nasıl yapılandırılacağı, onManageTrigger kullanılarak abonelik yaşam döngüsü etkinliklerinin nasıl işleneceği ve bir etkinlik gerçekleştiğinde başlatıcı isteğin Google'a nasıl geri gönderileceği gösterilmektedir.

Apps Komut Dosyası

/**
 * Generates and returns the user configuration card to collect inputs.
 */
function onConfigTrigger() {
  const projectInput = CardService.newTextInput()
    .setFieldName("projectId")
    .setTitle("Project ID")
    .setHint("Enter the project identifier to watch");

  const section = CardService.newCardSection()
    .setHeader("Configure Event Trigger")
    .addWidget(projectInput);

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

/**
 * Handles subscription lifecycle events sent from Google Workspace Studio.
 *
 * @param {Object} event The Workspace Studio event object.
 */
function onManageTrigger(event) {
  const triggerCreation = event.workflow.triggerCreation;
  const triggerDeletion = event.workflow.triggerDeletion;

  if (triggerCreation) {
    const triggerId = triggerCreation.triggerId;
    const notifyUri = triggerCreation.notifyUri;
    const inputs = triggerCreation.inputs;

    // Extract input values configured by the user.
    const projectId = inputs["projectId"].stringValues[0];

    // TODO: Save triggerId, notifyUri, and projectId in your database/service.
    // Your backend service listens for events related to 'projectId'
    // and calls notifyUri when those events occur.
    console.log("Trigger subscription created: " + triggerId +
                ", Notify URI: " + notifyUri +
                ", Match Project: " + projectId);

  } else if (triggerDeletion) {
    const triggerId = triggerDeletion.triggerId;

    // TODO: Remove references to triggerId from your database and stop
    // sending future event notifications to the associated notifyUri.
    console.log("Trigger subscription deleted: " + triggerId);
  }
}

/**
 * Mock function showing how your backend service fires the trigger.
 * This logic runs on your service when a watched event occurs.
 *
 * @param {string} notifyUri The stored notifyUri associated with the trigger.
 * @param {string} triggerId The stored triggerId.
 * @param {string} userAccessToken The OAuth 2.0 access token for the user
 *     (obtained using your stored refresh token).
 */
function simulateEventFire(notifyUri, triggerId, userAccessToken) {
  // A unique UUID version 4 is recommended as the requestId for idempotency.
  const requestId = Utilities.getUuid();

  const payload = {
    "name": "triggers/" + triggerId,
    "outputs": {
      "eventName": { "stringValues": ["EventOccurred"] },
      "eventMessage": { "stringValues": ["Hello from the service!"] }
    },
    "requestId": requestId
  };

  const options = {
    "method": "POST",
    "contentType": "application/json",
    "headers": {
      "Authorization": "Bearer " + userAccessToken
    },
    "payload": JSON.stringify(payload),
    "muteHttpExceptions": true
  };

  const response = UrlFetchApp.fetch(notifyUri, options);
  const responseCode = response.getResponseCode();

  if (responseCode === 200) {
    console.log("Trigger successfully fired!");
  } else if (responseCode === 404) {
    // 404 means the trigger registration is invalid or deleted.
    console.log("Trigger not found. Stop sending events for this trigger.");
    // TODO: Clean up the trigger from your backend database.
  } else if (responseCode === 429 || responseCode >= 500) {
    console.log("Temporary error (" + responseCode + "). Retry using exponential backoff.");
  } else {
    console.log("Failed to fire trigger. HTTP Code: " + responseCode + " - " + response.getContentText());
  }
}

Workspace Studio API'sini kullanma

Başlangıç etkinliklerini Google'a programatik olarak bildirmek için Workspace Studio API'yi (workspacestudio.googleapis.com) kullanabilirsiniz.

Uç noktalar, temel yolun altında bulunur: https://workspacestudio.googleapis.com/v1.

Başlangıç etkinliğini bildirir.

Bir akışın yürütülmesini başlatmak için triggers.fire yöntemini kullanarak bir başlatıcı tetikler.

  • HTTP Yöntemi: POST
  • Yol: /v1/triggers/{triggerId}:fire (burada {triggerId}, tetikleyici aboneliği oluşturma sırasında alınan benzersiz tanımlayıcıdır)
  • OAuth kapsamı: https://www.googleapis.com/auth/workspace.studio.trigger

Aşağıdaki kod örneğinde, istekte başlatıcı etkinliğin nasıl tetikleneceği gösterilmektedir.

İstek

{
  "name": "triggers/TRIGGER_ID",
  "outputs": {
    "eventName": {
      "stringValues": [
        "EventOccurred"
      ]
    },
    "eventMessage": {
      "stringValues": [
        "Hello from the service!"
      ]
    }
  },
  "log": {
    "textFormatElements": [
      {
        "text": "An event occurred in the app."
      }
    ]
  },
  "requestId": "UNIQUE_REQUEST_ID"
}
  • name (dize, zorunlu): Başlangıç öğesinin kaynak adı, triggers/{triggerId} biçiminde olmalıdır.
  • outputs (eşleme, isteğe bağlı): Etkinlik verilerini temsil eden başlangıç çıkış değişkenlerinin eşlemesi. Her değer, türü belirlenmiş listeleri (ör. stringValues, booleanValues, integerValues) destekleyen bir VariableData nesnesidir.
  • log (nesne, isteğe bağlı): Workspace Studio yürütme etkinliği günlüklerinde gösterilen TextFormat biçimlendirme gösterimi.
  • requestId (dize, isteğe bağlı): Yeniden denemelerde API'nin idempotent olmasını sağlamak için en fazla 36 ASCII karakterden oluşan benzersiz bir tanımlayıcı (UUID v4 önerilir).

Yanıt

Başarılı olursa yanıt, boş bir JSON nesnesi {} döndürür.

Workspace Studio API kotaları

workspacestudio.googleapis.com hizmetine gönderilen trafik, sistemin aşırı yüklenmesini önlemek, kaynakların adil kullanımını teşvik etmek ve Google Workspace'in genel performansını korumak için kısıtlanır.

Aşağıdaki kotalar uygulanır:

Kota türü Kota
Proje başına dakika 1.000 başlangıç isteği
Kullanıcı başına dakikada 100 başlangıç isteği

Kota türleri şunlardır:

  • Proje başına dakikada: Tek bir geliştiricinin Google Cloud projesinden tetiklenen başlangıç etkinliklerinin toplam sayısını,başlangıç etkinliklerini çalıştıran tüm kullanıcılar için proje başına dakikada 1.000 istek ile sınırlar.
  • Kullanıcı başına dakika: Belirli bir Cloud projesinde herhangi bir tek son kullanıcının toplam başlangıç çağrısını dakika başına 100 istekle sınırlar.

Zamana dayalı kota hatalarını giderme

Bu kotaları aşarsanız API, hız kotasının aşıldığını belirten bir HTTP 429 Too Many Requests (veya 429 Resource Exhausted) hata kodu döndürür.

Bu hataları gidermek için kodunuzun istisnayı yakalaması ve kısaltılmış eksponansiyel geri yükleme stratejisi kullanması gerekir. Eksponansiyel geri yükleme, başarısız olan istekleri yeniden denerken denemeler arasında giderek daha uzun gecikmeler kullanır. Birden fazla istemcinin aynı anda senkronize olmasını ve yeniden denemesini önlemek için rastgele jitter (her yinelemede rastgele bir gecikmeyi yeniden hesaplama) da kullanılır:

  1. Workspace Studio API'ye istekte bulunma
  2. İstek 429 hatasıyla başarısız olursa 1 second + random_number_milliseconds bekleyip tekrar deneyin.
  3. Yine başarısız olursa 2 seconds + random_number_milliseconds bekleyip tekrar deneyin.
  4. Yine başarısız olursa 4 seconds + random_number_milliseconds bekleyip tekrar deneyin.
  5. Bu döngüye devam edin ve gecikmeyi maximum_backoff eşiğine (genellikle 32 veya 64 saniye) ulaşana kadar iki katına çıkarın.
  6. Maksimum geri yükleme aralığı süresine ulaştığınızda, maksimum yeniden deneme sınırına ulaşılana kadar bu sabit gecikmeyi kullanarak yeniden deneyin, ardından duraklatın ve hatayı kaydedin.

En iyi uygulamalar

Başlangıç sitesi tasarlarken ve uygularken aşağıdaki en iyi uygulamaları göz önünde bulundurun:

Toplu listeler yerine tek etkinlikler yayınlayın

Başlangıç tetikleyicinizi, bir öğe grubu veya listesi içeren tek bir etkinlik yayınlamak yerine her farklı oluşum (ör. tek bir kayıt güncellendi, yeni bir mesaj yayınlandı veya bir görev atandı) için ayrı bir etkinlik yayınlayacak şekilde tasarlayın:

  • Yerleşik başlangıç görevleriyle tutarlılık: Workspace Studio'da yerleşik Google Workspace başlangıç görevleri (ör. Gmail'de e-posta alma veya Google Chat'te bir kullanıcı tarafından alana katılma) tek bir etkinlikte tetiklenir. Tek öğeli etkinlikler yayınlamak bu davranışla uyumludur ve tüm başlangıç uygulamalarında kullanıcılar için tutarlı ve tahmin edilebilir bir deneyim sağlar.
  • Daha basit akış yapılandırması: Bir akıştaki sonraki adımlar genellikle tek bir öğeyi işler. Tek öğeli etkinlikler yayınlamak, kullanıcıların dizilerde yineleme veya listeleri ayrıştırma için karmaşık adımlar eklemeden değişkenleri doğrudan eşlemesine olanak tanır.
  • Yoklama ve toplu değişiklikleri ayrı ayrı işleme: Arka uç hizmetiniz harici bir API'yi yokluyorsa ve tek bir yoklama aralığında birden fazla değiştirilmiş öğe algılıyorsa bunları tek bir toplu etkinlikte birleştirmek yerine her öğe için ayrı bir başlatma etkinliği tetikleyin.
  • Etkinlik sıklığını ve kotaları yönetme: Birden fazla değiştirilmiş öğe için ayrı ayrı etkinlik tetiklemek, isteklerde ani bir artışa neden olabileceğinden hizmetinizin Workspace Studio API kotaları (ör. kullanıcı başına dakikada 100 istek sınırı) dahilinde kaldığından emin olun. Bir yoklama döngüsü büyük miktarda öğe (örneğin, 100'den fazla değiştirilmiş kayıt) veriyorsa 429 Too Many Requests hatalarını önlemek için etkinlik gönderimlerini zaman içinde hızlandırın veya kısıtlayın.

Temel davranışlar ve sıra dışı durumlar

Başlangıç uygulamalarını entegre ederken geliştiriciler belirli hata davranışlarını ve çalışma zamanı özelliklerini ele almalıdır:

  • Test çalıştırma desteği yok: Workspace Studio, başlangıç için test çalıştırmalarını desteklemez.
  • İdempotency ve yeniden oynatma önleme: Kesinlikle zorunlu olmasa da HTTP veya Apps Script yükünüze benzersiz bir requestId (ör. UUID) eklemeniz gerekir. requestId sağlamak, API'nin yinelenen bildirimleri algılayıp yoksaymasına olanak tanıyarak idempotency (eş kuvvetlilik) sağlar ve akışın tek bir etkinlik için birden fazla kez çalışmasını önler.

  • Devre dışı bırakılan ve yeniden etkinleştirilen akışlar: Başlatıcınızı içeren bir akış Workspace Studio'da devre dışı bırakıldığında Google, triggerDeletion yaşam döngüsü olayı etkinliğini onManageFunction geri çağırma işlevinize gönderir. Ayrıca, ilişkili FireTrigger yöntemiyle yapılan tüm çağrılar 404 Not Found hata dönüş kodu (Requested entity was not found.) döndürür. Hizmetiniz, 404 hatalarına, bu başlangıç örneği kimliği için gelecekteki etkinlik bildirimi teslimatlarını durdurarak yanıt vermelidir.

    Kullanıcı daha sonra akışı yeniden etkinleştirirse Google, yeni bir triggerId ve notifyUri içeren yeni bir triggerCreation etkinliğiyle onManageFunction geri çağırmasını çağırarak yeni bir abonelik yaşam döngüsü başlatır. Önceki triggerId kalıcı olarak devre dışı bırakıldı ve yeniden etkinleştirilmedi. Bu nedenle, hizmetiniz eski bir tetikleyici örneğinin yeniden etkinleştirilip etkinleştirilmediğini yoklamamalı veya kontrol etmemelidir. Daha fazla bilgi için Başlangıç aboneliğinin yaşam döngüsünü yönetme başlıklı makaleyi inceleyin.

  • Aynı sonucu veren abonelik silme işlemi: onManageFunction geri çağırma işleviniz Google'dan gelen Starter silme isteklerini aynı sonucu verecek şekilde işlemelidir. Google, aynı triggerId için silme kancasını birden çok kez çağırırsa (örneğin, geçici bağlantı kayıpları nedeniyle yeniden denemeler sırasında) işlev başarılı bir şekilde döndürülmelidir.

  • Akış kotaları: Workspace Studio API kotalarının yanı sıra kullanıcı akışları da ek dahili kota denetimlerine tabidir. Yüksek sıklıklı döngüler veya aşırı etkinlik hacmi, güvenlik eşiklerini aşarak akışın otomatik olarak devre dışı bırakılmasına neden olabilir.