Tworzenie polecenia inicjującego

Z tego dokumentu dowiesz się, jak utworzyć starter, który umożliwi aplikacji lub usłudze powiadamianie Google Workspace Studio o wystąpieniu zdarzenia i inicjowanie wykonania przepływu. W interfejsie API dania na początek są nazywane workflowTriggers.

Polecenie inicjujące rozpoczyna przepływ, a krok to pojedyncze zadanie w sekwencji zadań, które składają się na przepływ. Tworząc starter, umożliwiasz użytkownikom konfigurowanie zautomatyzowanych przepływów, które reagują na zdarzenia w czasie rzeczywistym z Twojej aplikacji lub usługi.

Utworzenie elementu startowego polega na zadeklarowaniu go w pliku manifestu dodatku i zaimplementowaniu wywołań zwrotnych cyklu życia w Google Apps Script lub na uruchomieniu elementu startowego przez wysłanie ładunków do punktu końcowego interfejsu Google Workspace Studio API.

Wymagania wstępne i autoryzacja OAuth

Aby komunikować się z punktem końcowym interfejsu Workspace Studio API, Twoja aplikacja lub usługa musi uwierzytelniać się za pomocą protokołu OAuth 2.0. Podczas autoryzacji aplikacja musi poprosić użytkowników o przyznanie tego zakresu OAuth:

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

Ten zakres uprawnień umożliwia aplikacji wywoływanie interfejsu Workspace Studio API i uruchamianie automatyzacji, które użytkownik skonfigurował dla tego elementu początkowego.

Dostęp offline i tokeny odświeżania

Ponieważ startery powiadamiają Workspace Studio asynchronicznie o zdarzeniu w usłudze zewnętrznej (co może nastąpić kilka godzin, dni lub miesięcy po skonfigurowaniu przepływu przez użytkownika), Twoja usługa musi podać prawidłowy token dostępu OAuth 2.0 podczas wywoływania punktu końcowego interfejsu API.

Token dostępu udostępniany przez Google w obiekcie zdarzenia dodatku (np. podczas konfiguracji początkowej lub żądań wywołania zwrotnego cyklu życia) ma krótki okres ważności i jest ważny tylko przez godzinę. Nie wystarczy to do asynchronicznego wywoływania zdarzeń inicjujących w przyszłości. Aby wywoływać interfejs Workspace Studio API, usługa potrzebuje tokena odświeżania offline, który umożliwia generowanie nowych tokenów dostępu na żądanie.

Sposób obsługi autoryzacji i uzyskiwania tokena odświeżania zależy od środowiska wykonawczego dodatku:

  • Dodatki HTTP (alternatywne środowiska wykonawcze): w przypadku dodatków HTTP usługa backendu musi implementować oddzielny proces autoryzacji OAuth 2.0 niezależny od wbudowanej autoryzacji dodatku, aby wysyłać żądania dostępu offline (access_type=offline) i otrzymywać token odświeżania.

    Możesz poprosić użytkowników o autoryzację tego połączenia, wyświetlając kartę logowania lub autoryzacji, gdy użytkownik konfiguruje starter w Workspace Studio. Więcej informacji o zwracaniu kart autoryzacji i obsłudze procesu OAuth znajdziesz w artykule Łączenie dodatku do Google Workspace z usługą innej firmy (traktując Google Workspace jako usługę innej firmy, z którą się łączysz).

    Usługa backendu musi bezpiecznie przechowywać token odświeżania (np. w bazie danych usługi obok triggerId) i używać go do pobierania nowego tokena dostępu za każdym razem, gdy wystąpi zdarzenie, przed wysłaniem żądań do punktu końcowego interfejsu API notifyUri lub triggers.fire.

  • Dodatki Google Apps Script: dodatki oparte na Google Apps Script, które używają zaplanowanych (wywoływanych przez czas) reguł do sprawdzania zdarzeń, mogą pominąć implementację niezależnego przepływu OAuth. Zaplanowane wyzwalacze działają bezpośrednio w środowisku wykonawczym Google Apps Script, więc Google Apps Script automatycznie zarządza tokenami OAuth i odświeża je za pomocą zakresów zadeklarowanych w pliku manifestu.

Zdefiniuj starter w pliku manifestu

Aby zdefiniować aktywator, dodaj go do pliku manifestu dodatku (appsscript.json) w bloku addOns.studio.flows.workflowElements. Ta konfiguracja jest wymagana zarówno w przypadku środowisk wykonawczych Apps Script, jak i HTTP (środowisk alternatywnych). Skonfiguruj element jako workflowTrigger zamiast workflowAction (który jest używany podczas definiowania kroku). Więcej informacji znajdziesz w artykule Struktura pliku manifestu dodatków do Google Workspace.

W bloku workflowTrigger określ:

  • inputs: zmienne konfigurowane przez użytkownika na karcie konfiguracji (np. nazwa projektu, filtr zasobów itp.).
  • outputs: zmienne zwracane przez element początkowy do kolejnych kroków w przepływie.
  • onConfigFunction: Nazwa funkcji wywołania zwrotnego, która wyświetla interfejs konfiguracji użytkownika.
  • onManageFunction: nazwa funkcji wywołania zwrotnego wywoływanej przez Google w celu obsługi tworzenia i usuwania subskrypcji startowej.

Poniższy przykładowy kod pokazuje definicję pliku manifestu dla narzędzia do uruchamiania zdarzeń:

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

Obsługa cyklu życia subskrypcji startowej

Gdy użytkownik skonfiguruje i włączy przepływ zawierający Twój starter lub gdy przepływ zostanie wyłączony lub usunięty, Google wywoła Twój dodatek za pomocą funkcji wywołania zwrotnego onManageFunction zadeklarowanej w pliku manifestu.

Obiekt zdarzenia cyklu życia

Funkcja wywołania zwrotnego otrzymuje obiekt WorkflowEventObject zawierający kontekst działania. Obejmuje to m.in.:

  • Utworzenie reguły (event.workflow.triggerCreation): uruchamia się, gdy przepływ zostanie opublikowany lub włączony.

    • triggerId: Unikalny ciąg UUID identyfikujący tę instancję rejestracji początkowej.

    • notifyUri: unikalny adres URL punktu końcowego interfejsu API typu REST powiązany z tą rejestracją początkową (np. https://workspacestudio.googleapis.com/v1/triggers/YOUR_TRIGGER_ID:fire).

    • inputs: dane wejściowe zmiennej skonfigurowane przez użytkownika na karcie.

  • Usunięcie reguły (event.workflow.triggerDeletion): uruchamia się, gdy element rozpoczynający zostanie usunięty z procesu lub gdy cały proces zostanie wyłączony lub usunięty.

    • triggerId: Unikalny ciąg UUID instancji subskrypcji do zwolnienia miejsca.

Cykl życia subskrypcji alternatywnych środowisk wykonawczych (interfejs API HTTP)

W przypadku dodatków utworzonych przy użyciu alternatywnych środowisk wykonawczych powiadomienia o cyklu życia subskrypcji są dostarczane za pomocą żądań HTTP POST na skonfigurowany adres URL punktu końcowego HTTP dodatku z nazwą działania określoną przez funkcję wywołania zwrotnego onManageFunction. Ładunek pasuje do reprezentacji JSON WorkflowEventObject.

Więcej informacji o alternatywnych środowiskach wykonawczych znajdziesz w artykule Tworzenie dodatku do Google Workspace przy użyciu punktów końcowych HTTP.

Implementowanie wywołań zwrotnych cyklu życia w Apps Script

Poniższy przykład Apps Script pokazuje, jak skonfigurować kartę interfejsu, obsługiwać zdarzenia cyklu życia subskrypcji za pomocą onManageTrigger i wysyłać z powrotem do Google żądanie początkowe, gdy wystąpi zdarzenie.

Google 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());
  }
}

Korzystanie z interfejsu Workspace Studio API

Za pomocą interfejsu Workspace Studio APIworkspacestudio.googleapis.com możesz programowo powiadamiać Google o zdarzeniach związanych z rozpoczęciem pracy.

Punkty końcowe znajdują się w ścieżce podstawowej:https://workspacestudio.googleapis.com/v1.

Powiadamia o zdarzeniu początkowym

Uruchamia starter za pomocą metody triggers.fire, aby rozpocząć wykonywanie przepływu.

  • HTTP Method (Metoda HTTP): POST
  • Ścieżka: /v1/triggers/{triggerId}:fire (gdzie {triggerId} to unikalny identyfikator pobrany podczas tworzenia subskrypcji reguły)
  • Zakres OAuth: https://www.googleapis.com/auth/workspace.studio.trigger

Poniższy przykładowy kod pokazuje, jak uruchomić starter w żądaniu.

Żądanie

{
  "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 (ciąg znaków, wymagany): nazwa zasobu elementu początkowego w formacie triggers/{triggerId}.
  • outputs (map, opcjonalnie): mapa zmiennych wyjściowych modułu początkowego reprezentujących dane zdarzenia. Każda wartość jest obiektem VariableData obsługującym listy typowane (np. stringValues, booleanValues, integerValues).
  • log (obiekt, opcjonalnie): reprezentacja znaczników TextFormat wyświetlana w dziennikach aktywności wykonywania Workspace Studio.
  • requestId (ciąg znaków, opcjonalny): unikalny identyfikator (zalecany UUID w wersji 4) o długości do 36 znaków ASCII, który zapewnia idempotentność interfejsu API podczas ponownych prób.

Odpowiedź

W przypadku powodzenia odpowiedź zwraca pusty obiekt JSON {}.

Limity interfejsu Workspace Studio API

Ruch wysyłany do usługi workspacestudio.googleapis.com jest ograniczony, aby zapobiegać przeciążeniu systemu, zachęcać do sprawiedliwego korzystania z zasobów i chronić ogólną wydajność Google Workspace.

Obowiązują te limity:

Typ limitu Limit
Za minutę na projekt 1000 zapytań początkowych
Za minutę na użytkownika 100 przykładowych żądań

Rodzaje limitów:

  • Na minutę na projekt w chmurze: ogranicza łączną liczbę zdarzeń początkowych uruchamianych z pojedynczego projektu w chmurze Google dewelopera do 1000 żądań na minutę w przypadku wszystkich użytkowników korzystających z jego poleceń inicjujących.
  • Na minutę na użytkownika: ogranicza łączną liczbę wywołań funkcji startowej przez jednego użytkownika w danym projekcie Google Cloud do 100 próśb na minutę.

Obsługa błędów związanych z limitami czasowymi

Jeśli przekroczysz te limity, interfejs API zwróci kod błędu HTTP 429 Too Many Requests (lub 429 Resource Exhausted) wskazujący, że limit liczby żądań został przekroczony.

Aby rozwiązać te problemy, kod powinien przechwytywać wyjątek i stosować strategię wzrastającego czasu do ponowienia z ograniczeniem. Algorytm wzrastający czas do ponowienia ponawia nieudane żądania z coraz dłuższymi opóźnieniami między próbami, w tym z losowymi zakłóceniami (ponowne obliczanie losowego opóźnienia w każdej iteracji), aby zapobiec synchronizacji i ponawianiu prób przez wielu klientów w tym samym czasie:

  1. Wysyłanie żądań do interfejsu Workspace Studio API.
  2. Jeśli żądanie zakończy się błędem 429, poczekaj 1 second + random_number_milliseconds i spróbuj ponownie.
  3. Jeśli ponownie się nie powiedzie, poczekaj 2 seconds + random_number_milliseconds i spróbuj jeszcze raz.
  4. Jeśli ponownie się nie powiedzie, poczekaj 4 seconds + random_number_milliseconds i spróbuj jeszcze raz.
  5. Kontynuuj tę pętlę, podwajając opóźnienie aż do osiągnięcia progu maximum_backoff (zwykle 32 lub 64 sekundy).
  6. Gdy osiągniesz maksymalny czas do ponowienia, ponawiaj próbę z użyciem stałego opóźnienia, dopóki nie osiągniesz maksymalnego limitu ponownych prób. Następnie zatrzymaj działanie i zarejestruj błąd.

Sprawdzone metody

Podczas projektowania i wdrażania pakietu startowego pamiętaj o tych sprawdzonych metodach:

Wysyłaj pojedyncze zdarzenia zamiast list zbiorczych.

Zaprojektuj starter tak, aby emitował osobne zdarzenie dla każdego odrębnego wystąpienia (np. zaktualizowanego pojedynczego rekordu, opublikowanej nowej wiadomości lub przypisanego zadania), a nie pojedyncze zdarzenie zawierające partię lub listę elementów:

  • Spójność z wbudowanymi starterami: w Workspace Studio wbudowane startery Google Workspace (np. otrzymanie e-maila w Gmailu lub dołączenie użytkownika do pokoju w Google Chat) są wywoływane przez jedno zdarzenie. Wysyłanie zdarzeń dotyczących pojedynczych elementów jest zgodne z tym zachowaniem i zapewnia użytkownikom spójne i przewidywalne wrażenia we wszystkich wersjach startowych.
  • Prostsza konfiguracja przepływu: kolejne kroki w przepływie zwykle przetwarzają po jednym elemencie. Wysyłanie zdarzeń z 1 elementem umożliwia użytkownikom bezpośrednie mapowanie zmiennych bez dodawania złożonych kroków do iteracji po tablicach lub analizowania list.
  • Obsługuj sondowanie i zmiany zbiorcze osobno: jeśli usługa backendu sondowała zewnętrzny interfejs API i wykryła wiele zmienionych elementów w jednym przedziale czasu sondowania, wywołaj osobne zdarzenie początkowe dla każdego elementu, zamiast łączyć je w jedno zdarzenie zbiorcze.
  • Zarządzaj liczbą zdarzeń i limitami: wysyłanie poszczególnych zdarzeń dotyczących wielu zmienionych elementów może spowodować nagły wzrost liczby żądań. Upewnij się, że Twoja usługa mieści się w limitach interfejsu Workspace Studio API (np. w limicie 100 żądań na minutę na użytkownika). Jeśli cykl odpytywania generuje dużą liczbę elementów (np. ponad 100 zmienionych rekordów), rozłóż wysyłanie zdarzeń w czasie, aby uniknąć błędów 429 Too Many Requests.

Główne zachowania i przypadki graniczne

Podczas integrowania pakietów startowych deweloperzy muszą obsługiwać określone zachowania w przypadku błędów i funkcje środowiska wykonawczego:

  • Brak obsługi testów: Workspace Studio nie obsługuje testów w przypadku wersji Starter.
  • Idempotentność i zapobieganie ponownemu odtwarzaniu: chociaż nie jest to bezwzględnie wymagane, w ładunku HTTP lub Apps Script warto umieścić unikalny requestId (np. UUID). Podanie requestId zapewnia idempotentność, ponieważ umożliwia interfejsowi API wykrywanie i ignorowanie zduplikowanych powiadomień, co zapobiega wielokrotnemu uruchamianiu procesu w przypadku jednego zdarzenia.

  • Wyłączone i ponownie włączone automatyzacje: gdy automatyzacja zawierająca starter zostanie wyłączona w Workspace Studio, Google wyśle zdarzenie cyklu życia triggerDeletion do Twojego wywołania zwrotnego onManageFunction. Dodatkowo wszystkie wywołania powiązanej metody FireTrigger zwracają kod błędu 404 Not Found (Requested entity was not found.). Usługa powinna reagować na błędy 404, zatrzymując dostarczanie przyszłych powiadomień o zdarzeniach dla tego identyfikatora instancji początkowej.

    Jeśli użytkownik później ponownie włączy ten proces, Google rozpocznie nowy cykl życia subskrypcji, wywołując Twoje wywołanie zwrotne onManageFunction z nowym zdarzeniem triggerCreation zawierającym nowe wartości triggerId i notifyUri. Poprzedni triggerId jest trwale wyłączony i nie zostanie ponownie aktywowany, więc usługa nie powinna odpytywać ani sprawdzać, czy stara instancja wyzwalacza została ponownie włączona. Więcej informacji znajdziesz w artykule Zarządzanie cyklem życia subskrypcji startowej.

  • Idempotentne usuwanie subskrypcji: funkcja wywołania zwrotnego onManageFunction musi obsługiwać żądania usunięcia subskrypcji próbnej od Google w sposób idempotentny. Jeśli Google wywoła funkcję usuwania wiele razy dla tego samego triggerId (np. podczas ponawiania prób z powodu tymczasowej utraty połączenia), funkcja powinna zwrócić wynik wskazujący na powodzenie.

  • Limity automatyzacji: oprócz limitów interfejsu Workspace Studio API automatyzacje użytkowników podlegają dodatkowym wewnętrznym limitom. Pętle o wysokiej częstotliwości lub nadmierna liczba zdarzeń mogą przekroczyć progi bezpieczeństwa, co spowoduje automatyczne wyłączenie przepływu.