Starter erstellen

In diesem Dokument wird beschrieben, wie Sie einen Starter erstellen, mit dem Ihre App oder Ihr Dienst Google Workspace Studio benachrichtigen kann, wenn ein Ereignis eintritt, und eine Ablaufausführung initiieren kann. In der API werden sie als workflowTriggers bezeichnet.

Ein Starter beginnt einen Flow, während ein Schritt eine einzelne Aufgabe in der Abfolge von Aufgaben ist, aus denen ein Flow besteht. Wenn Sie einen Starter erstellen, können Nutzer automatisierte Abläufe einrichten, die auf Echtzeitereignisse aus Ihrer App oder Ihrem Dienst reagieren.

Um einen Starter zu erstellen, müssen Sie ihn in der Add-on-Manifestdatei deklarieren und Lebenszyklus-Callbacks in Google Apps Script implementieren oder den Starter auslösen, indem Sie Nutzlasten an den Google Workspace Studio API-Endpunkt senden.

Voraussetzungen und OAuth-Autorisierung

Für die Kommunikation mit dem Workspace Studio API-Endpunkt muss sich Ihre App oder Ihr Dienst mit OAuth 2.0 authentifizieren. Die App muss während der Autorisierung den folgenden dedizierten OAuth-Bereich von Nutzern anfordern:

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

Mit diesem Bereich wird die App autorisiert, die Workspace Studio API aufzurufen und Flows auszulösen, die der Nutzer für diesen Starter konfiguriert hat.

Offlinezugriff und Aktualisierungstokens

Da Starter Workspace Studio asynchron benachrichtigen, wenn ein Ereignis im externen Dienst eintritt, was Stunden, Tage oder Monate nach der Konfiguration eines Ablaufs durch einen Nutzer geschehen kann, muss Ihr Dienst beim Aufrufen des API-Endpunkts ein gültiges OAuth 2.0-Zugriffstoken bereitstellen.

Das von Google im Add-on-Ereignisobjekt bereitgestellte Zugriffstoken (z. B. bei der Starterkonfiguration oder bei Lifecycle-Callback-Anfragen) ist kurzlebig und nur eine Stunde lang gültig. Es reicht nicht aus, um Starter-Ereignisse in Zukunft asynchron auszulösen. Wenn Ihr Dienst die Workspace Studio API im Laufe der Zeit aufrufen soll, ist ein Aktualisierungstoken für die Offline-Nutzung erforderlich, um bei Bedarf neue Zugriffstokens zu generieren.

Wie Sie die Autorisierung handhaben und ein Aktualisierungstoken abrufen, hängt von der Add-on-Laufzeit ab:

  • HTTP-Add-ons (alternative Runtimes): Bei HTTP-Add-ons muss Ihr Backend-Dienst einen separaten OAuth 2.0-Autorisierungsablauf implementieren, der unabhängig von der integrierten Add-on-Autorisierung ist, um Offlinezugriff (access_type=offline) anzufordern und ein Aktualisierungstoken zu erhalten.

    Sie können Nutzer auffordern, diese Verbindung zu autorisieren, indem Sie eine Anmelde- oder Autorisierungskarte anzeigen, wenn der Nutzer den Starter in Workspace Studio konfiguriert. Weitere Informationen zum Zurückgeben von Autorisierungskarten und zum Verarbeiten des OAuth-Ablaufs finden Sie unter Google Workspace-Add‑on mit einem Drittanbieterdienst verbinden (wobei Google Workspace als der Drittanbieterdienst betrachtet wird, mit dem Sie eine Verbindung herstellen).

    Ihr Backend-Dienst muss das Aktualisierungstoken sicher speichern (z. B. in der Datenbank Ihres Dienstes neben dem triggerId) und damit ein neues Zugriffstoken abrufen, wenn ein Ereignis eintritt, bevor Anfragen an den notifyUri- oder den triggers.fire-API-Endpunkt des Starters gesendet werden.

  • Google Apps Script-Add-ons: Add-ons, die auf Google Apps Script basieren und geplante (zeitgesteuerte) Trigger verwenden, um Ereignisse abzufragen, können die Implementierung eines unabhängigen OAuth-Ablaufs überspringen. Da geplante Trigger direkt in der Google Apps Script-Laufzeitumgebung ausgeführt werden, verwaltet und aktualisiert Google Apps Script die OAuth-Tokens automatisch anhand der im Manifest deklarierten Bereiche.

Starter in der Manifestdatei definieren

Wenn Sie einen Auslöser definieren möchten, fügen Sie ihn in der Manifestdatei des Add-ons (appsscript.json) in den addOns.studio.flows.workflowElements-Block ein. Diese Konfiguration ist sowohl für Apps Script- als auch für HTTP-Laufzeiten (alternative Laufzeiten) erforderlich. Konfigurieren Sie das Element als workflowTrigger anstelle von workflowAction (das beim Definieren eines Schritts verwendet wird). Weitere Informationen finden Sie unter Manifeststruktur für Google Workspace-Add-ons.

Geben Sie im Block workflowTrigger Folgendes an:

  • inputs: Variablen, die der Nutzer auf der Konfigurationskarte konfiguriert (z. B. Projektname, Ressourcenfilter usw.).
  • outputs: Variablen, die vom Starter an nachgelagerte Schritte im Ablauf zurückgegeben werden können.
  • onConfigFunction: Der Name der Callback-Funktion, die die Benutzeroberfläche für die Nutzerkonfiguration anzeigt.
  • onManageFunction: Der Name der Callback-Funktion, die von Google aufgerufen wird, um die Erstellung und Löschung von Starter-Abos zu verarbeiten.

Das folgende Codebeispiel zeigt eine Beispielmanifestdefinition für einen Event-Starter:

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"
            }
          }
        ]
      }
    }
  }
}

Lebenszyklus von Starter-Abos verarbeiten

Wenn ein Nutzer einen Flow konfiguriert und aktiviert, der Ihren Starter enthält, oder wenn der Flow deaktiviert oder gelöscht wird, ruft Google Ihr Add-on über die im Manifest deklarierte Callback-Funktion onManageFunction auf.

Das Lifecycle-Event-Objekt

Die Callback-Funktion empfängt ein WorkflowEventObject mit dem Aktionskontext. Dazu gehören:

  • Trigger Creation (event.workflow.triggerCreation) (Triggererstellung): Wird ausgelöst, wenn der Flow veröffentlicht oder aktiviert wird.

    • triggerId: Ein eindeutiger UUID-String, der diese Starterregistrierungsinstanz identifiziert.

    • notifyUri: Die eindeutige REST API-Endpunkt-URL, die mit dieser Starter-Registrierung verknüpft ist (z. B. https://workspacestudio.googleapis.com/v1/triggers/YOUR_TRIGGER_ID:fire).

    • inputs: Die vom Nutzer über die Karte konfigurierten Variableneingaben.

  • Trigger Deletion (event.workflow.triggerDeletion): Wird ausgelöst, wenn der Starter aus dem Ablauf entfernt wird oder wenn der gesamte Ablauf deaktiviert oder gelöscht wird.

    • triggerId: Der eindeutige UUID-String der zu bereinigenden Aboinstanz.

Abonnementlebenszyklus für Alternate Runtimes (HTTP API)

Bei Add-ons, die mit alternativen Runtimes erstellt wurden, werden Benachrichtigungen zum Abo-Lebenszyklus über HTTP-POST-Anfragen an die konfigurierte HTTP-Endpunkt-URL des Add-ons gesendet. Der Aktionsname wird von der onManageFunction-Callback-Funktion angegeben. Die Nutzlast entspricht der JSON-Darstellung von WorkflowEventObject.

Weitere Informationen zu alternativen Laufzeiten finden Sie unter Google Workspace-Add‑on mit HTTP-Endpunkten erstellen.

Lebenszyklus-Callbacks in Apps Script implementieren

Im folgenden Apps Script-Beispiel wird gezeigt, wie Sie die Benutzeroberflächenkarte konfigurieren, Abo-Lebenszyklusereignisse mit onManageTrigger verarbeiten und die Starteranfrage bei einem Ereignis an Google zurücksenden.

Apps Script

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

Mit der Workspace Studio API (workspacestudio.googleapis.com) können Sie Google programmatisch über Starter-Ereignisse benachrichtigen.

Die Endpunkte befinden sich unter dem Basispfad: https://workspacestudio.googleapis.com/v1.

Benachrichtigt über ein Starter-Ereignis

Löst einen Starter mit der Methode triggers.fire aus, um die Ausführung eines Flows zu starten.

  • HTTP-Methode: POST
  • Pfad: /v1/triggers/{triggerId}:fire (wobei {triggerId} die eindeutige Kennung ist, die beim Erstellen des Triggerabos abgerufen wurde)
  • OAuth-Bereich: https://www.googleapis.com/auth/workspace.studio.trigger

Das folgende Codebeispiel zeigt, wie Sie einen Starter in der Anfrage auslösen.

Ersuchen

{
  "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 (String, erforderlich): Der Ressourcenname des Starters im Format triggers/{triggerId}.
  • outputs (map, optional): Eine Zuordnung von Starter-Ausgabevariablen, die die Ereignisdaten darstellen. Jeder Wert ist ein VariableData-Objekt, das typisierte Listen unterstützt (z. B. stringValues, booleanValues, integerValues).
  • log (Objekt, optional): Eine TextFormat-Markierung, die in den Ausführungsprotokollen von Workspace Studio angezeigt wird.
  • requestId (String, optional): Eine eindeutige ID (UUID v4 empfohlen) mit bis zu 36 ASCII-Zeichen, um die Idempotenz der API bei Wiederholungsversuchen zu gewährleisten.

Antwort

Bei Erfolg wird in der Antwort ein leeres JSON-Objekt {} zurückgegeben.

Workspace Studio API-Kontingente

Der an den workspacestudio.googleapis.com-Dienst gesendete Traffic ist eingeschränkt, um eine Systemüberlastung zu verhindern, eine faire Nutzung der Ressourcen zu fördern und die allgemeine Google Workspace-Leistung zu schützen.

Es gelten die folgenden Kontingente:

Kontingenttyp Kontingent
Pro Minute und Projekt 1.000 Starter-Anfragen
Pro Minute und Nutzer 100 Starter-Anfragen

Die Kontingenttypen sind:

  • Pro Minute und Projekt: Beschränkt die kumulative Anzahl von Starter-Ereignissen, die von einem einzelnen Google Cloud-Projekt eines Entwicklers ausgelöst werden, auf 1.000 Anfragen pro Minute für alle Nutzer, die die Starter ausführen.
  • Pro Minute und Nutzer: Beschränkt die kumulativen Aufrufe von Auslösern eines einzelnen Endnutzers in einem bestimmten Cloud-Projekt auf 100 Anfragen pro Minute.

Zeitbasierte Kontingentfehler beheben

Wenn Sie diese Kontingente überschreiten, gibt die API den HTTP-Fehlercode 429 Too Many Requests (oder 429 Resource Exhausted) zurück, der angibt, dass das Ratenkontingent überschritten wurde.

Um diese Fehler zu beheben, sollte Ihr Code die Ausnahme abfangen und eine Strategie mit abgeschnittenem exponentiellem Backoff verwenden. Beim exponentiellen Backoff werden fehlgeschlagene Anfragen mit immer längeren Verzögerungen zwischen den Versuchen wiederholt. Dazu gehört auch ein zufälliger Jitter (Neuberechnung einer zufälligen Verzögerung bei jeder Iteration), um zu verhindern, dass mehrere Clients synchronisiert werden und gleichzeitig Wiederholungsversuche starten:

  1. Stellen Sie eine Anfrage an die Workspace Studio API.
  2. Wenn die Anfrage mit dem Fehler 429 fehlschlägt, warten Sie 1 second + random_number_milliseconds und wiederholen Sie die Anfrage.
  3. Wenn der Vorgang wieder fehlschlägt, warten Sie 2 seconds + random_number_milliseconds und versuchen Sie es noch einmal.
  4. Wenn der Vorgang wieder fehlschlägt, warten Sie 4 seconds + random_number_milliseconds und versuchen Sie es noch einmal.
  5. Setzen Sie diese Schleife fort und verdoppeln Sie die Verzögerung bis zu einem Schwellenwert von maximum_backoff (normalerweise 32 oder 64 Sekunden).
  6. Sobald Sie die maximale Backoff-Dauer erreicht haben, wiederholen Sie den Vorgang mit dieser konstanten Verzögerung, bis das maximale Wiederholungslimit erreicht ist. Halten Sie dann an und protokollieren Sie den Fehler.

Best Practices

Beachten Sie beim Entwerfen und Implementieren eines Starters die folgenden Best Practices:

Einzelne Ereignisse statt Batchlisten ausgeben

Der Auslöser sollte für jedes einzelne Ereignis ein separates Ereignis ausgeben, z. B. wenn ein einzelner Datensatz aktualisiert, eine neue Nachricht gepostet oder eine Aufgabe zugewiesen wird. Er sollte also nicht ein einzelnes Ereignis ausgeben, das einen Batch oder eine Liste von Elementen enthält:

  • Konsistenz mit integrierten Startern: In Workspace Studio werden integrierte Google Workspace-Starter (z. B. der Empfang einer E‑Mail in Gmail oder der Beitritt eines Nutzers zu einem Bereich in Google Chat) durch ein einzelnes Ereignis ausgelöst. Das Senden von Ereignissen mit nur einem Element entspricht diesem Verhalten und sorgt für eine einheitliche, vorhersehbare Nutzererfahrung bei allen Startern.
  • Einfachere Ablaufkonfiguration: Bei Downstream-Schritten in einem Ablauf wird in der Regel jeweils ein Element verarbeitet. Durch das Ausgeben von Ereignissen mit nur einem Element können Nutzer Variablen direkt zuordnen, ohne komplexe Schritte zum Durchlaufen von Arrays oder zum Parsen von Listen hinzufügen zu müssen.
  • Polling und Batch-Änderungen einzeln verarbeiten: Wenn Ihr Backend-Dienst eine externe API abfragt und während eines einzelnen Polling-Intervalls mehrere geänderte Elemente erkennt, lösen Sie für jedes Element ein einzelnes Starter-Ereignis aus, anstatt sie in einem Batch-Ereignis zu bündeln.
  • Ereignisrate und Kontingente verwalten: Das Auslösen einzelner Ereignisse für mehrere geänderte Elemente kann zu einem plötzlichen Anstieg der Anfragen führen. Achten Sie daher darauf, dass Ihr Dienst die Workspace Studio API-Kontingente einhält, z. B. das Limit von 100 Anfragen pro Minute und Nutzer. Wenn bei einem Abfragezyklus eine große Anzahl von Elementen zurückgegeben wird (z. B. mehr als 100 geänderte Datensätze), sollten Sie die Ereignisübermittlungen im Laufe der Zeit verlangsamen oder drosseln, um 429 Too Many Requests-Fehler zu vermeiden.

Wichtigste Verhaltensweisen und Grenzfälle

Bei der Integration von Startern müssen Entwickler bestimmte Fehlerverhalten und Laufzeitfunktionen berücksichtigen:

  • Keine Unterstützung für Testläufe: Workspace Studio unterstützt keine Testläufe für Starter.
  • Idempotenz und Replay-Schutz: Obwohl nicht unbedingt erforderlich, sollten Sie eine eindeutige requestId (z. B. eine UUID) in Ihre HTTP- oder Apps Script-Nutzlast aufnehmen. Durch die Angabe einer requestId wird die Idempotenz sichergestellt, da die API doppelte Benachrichtigungen erkennen und ignorieren kann. So wird verhindert, dass der Ablauf für ein einzelnes Ereignis mehrmals ausgeführt wird.

  • Deaktivierte und reaktivierte Flows: Wenn ein Flow, der Ihren Starter enthält, in Workspace Studio deaktiviert wird, sendet Google ein triggerDeletion-Lifecycle-Event an Ihren onManageFunction-Callback. Außerdem wird bei allen Aufrufen der zugehörigen FireTrigger-Methode der Fehler-Rückgabecode 404 Not Found (Requested entity was not found.) zurückgegeben. Ihr Dienst sollte auf 404-Fehler reagieren, indem er die Zustellung zukünftiger Ereignisbenachrichtigungen für diese Starter-Instanz-ID beendet.

    Wenn ein Nutzer den Ablauf später wieder aktiviert, startet Google einen neuen Abo-Lebenszyklus, indem der onManageFunction-Callback mit einem neuen triggerCreation-Ereignis aufgerufen wird, das eine neue triggerId und notifyUri enthält. Die vorherige triggerId wurde dauerhaft deaktiviert und wird nicht reaktiviert. Ihr Dienst sollte daher nicht abfragen oder prüfen, ob eine alte Triggerinstanz reaktiviert wurde. Weitere Informationen finden Sie unter Umgang mit dem Abolebenszyklus.

  • Idempotentes Löschen von Abos: Ihre onManageFunction-Callback-Funktion muss Anfragen zum Löschen von Starter-Abos von Google idempotent verarbeiten. Wenn Google den Lösch-Hook mehrmals für dieselbe triggerId aufruft (z. B. bei Wiederholungsversuchen aufgrund vorübergehender Verbindungsverluste), sollte die Funktion erfolgreich zurückgegeben werden.

  • Flow-Kontingente: Neben den Workspace Studio API-Kontingenten unterliegen Nutzer-Flows zusätzlichen internen Kontingentkontrollen. Schleifen mit hoher Häufigkeit oder ein übermäßiges Ereignisvolumen können die Sicherheitsschwellen überschreiten, was zur automatischen Deaktivierung des Ablaufs führt.