Tworzenie polecenia inicjującego

Z tego dokumentu dowiesz się, jak utworzyć aktywator, który umożliwi Twojej aplikacji lub usłudze powiadamianie Google Workspace Studio o wystąpieniu zdarzenia i inicjowanie wykonania automatyzacji. W interfejsie API aktywatory są nazywane workflowTriggers.

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

Tworzenie aktywatora obejmuje zadeklarowanie go w pliku manifestu dodatku i zaimplementowanie wywołań zwrotnych cyklu życia w Google Apps Script lub wywołanie aktywatora przez wysłanie ładunków do punktu końcowego Google Workspace Studio API.

Wymagania wstępne

  • Konto Google z dostępem do Workspace Studio.
  • Projekt Google Cloud.

Włącz API

W projekcie Google Cloud włącz Google Workspace Studio API:

Włącz API

Przełączanie na standardowy projekt w chmurze Google (tylko Google Apps Script)

Domyślnie projekty Apps Script używają domyślnego projektu w chmurze, który nie obsługuje włączania interfejsów API ani konfigurowania ekranów zgody OAuth. Jeśli tworzysz aktywator za pomocą Apps Script, musisz przełączyć się na standardowy projekt w chmurze Google Cloud:

  1. W edytorze Apps Script kliknij Ustawienia projektu .
  2. W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.
  3. Wpisz numer standardowego projektu w chmurze i kliknij Ustaw projekt.
  4. Po przełączeniu projektów ponownie autoryzuj skrypt, uruchamiając dowolną funkcję w edytorze i przyznając wymagane uprawnienia.

Więcej informacji znajdziesz w artykule Przełączanie na standardowy projekt Google Cloud.

Konfigurowanie ekranu zgody OAuth

Aby komunikować się z punktem końcowym Workspace Studio API, Twoja aplikacja lub usługa musi uwierzytelniać się za pomocą protokołu OAuth 2.0. Skonfiguruj ekran zgody OAuth w projekcie i dodaj ten dedykowany zakres OAuth:

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

Ten zakres autoryzuje aplikację do wywoływania Workspace Studio API i uruchamiania automatyzacji skonfigurowanych przez użytkownika dla tego aktywatora.

Więcej informacji znajdziesz w artykule Konfigurowanie ekranu zgody OAuth i wybieranie zakresów.

Dostęp offline i tokeny odświeżania

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

Token dostępu udostępniany przez Google w obiekcie zdarzenia dodatku (np. podczas konfigurowania aktywatora lub żądań wywołania zwrotnego cyklu życia) jest ważny przez krótki czas i tylko przez 1 godzinę. Nie wystarczy do asynchronicznego wywoływania zdarzeń aktywatora w przyszłości. Aby wywoływać Workspace Studio API w czasie, Twoja usługa wymaga tokena odświeżania offline do generowania 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 zaimplementować osobny proces autoryzacji OAuth 2.0 niezależny od wbudowanej autoryzacji dodatku, aby poprosić o dostęp offline (access_type=offline) i otrzymać 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 aktywator 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 notifyUri aktywatora lub punktu końcowego triggers.fire API.

  • Dodatki Google Apps Script: dodatki oparte na Google Apps Script, które używają zaplanowanych (wyzwalanych przez czas) reguł do sprawdzania zdarzeń, mogą pominąć implementację niezależnego procesu OAuth. Ponieważ zaplanowane reguły działają bezpośrednio w środowisku wykonawczym Google Apps Script, Google Apps Script automatycznie zarządza tokenami OAuth i odświeża je za pomocą zakresów zadeklarowanych w manifeście. Token dostępu OAuth możesz pobrać za pomocą ScriptApp.getOAuthToken().

Definiowanie aktywatora 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 (alternatywnych środowisk wykonawczych). Skonfiguruj element jako workflowTrigger zamiast workflowAction (który jest używany podczas definiowania kroku). Więcej informacji znajdziesz w artykule Struktura 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, które aktywator może zwrócić do kolejnych kroków w automatyzacji.
  • onConfigFunction: nazwa funkcji wywołania zwrotnego, która wyświetla interfejs konfiguracji użytkownika.
  • onManageFunction: nazwa funkcji wywołania zwrotnego wywoływanej przez Google do obsługi tworzenia i usuwania subskrypcji aktywatora.

Poniższy przykładowy kod pokazuje definicję manifestu aktywatora zdarzeń:

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/workspace.studio.trigger"
  ],
  "urlFetchWhitelist": [
    "https://workspacestudio.googleapis.com/"
  ],
  "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 aktywatora

Gdy użytkownik skonfiguruje i włączy automatyzację zawierającą Twój aktywator lub gdy automatyzacja zostanie wyłączona lub usunięta, Google wywoła Twój dodatek za pomocą funkcji wywołania zwrotnego onManageFunction zadeklarowanej w manifeście.

Obiekt zdarzenia cyklu życia

Funkcja wywołania zwrotnego otrzymuje WorkflowEventObject zawierający kontekst działania. W przypadku aktywatorów obejmuje to:

  • Utworzenie reguły (event.workflow.triggerCreation): wywoływane, gdy automatyzacja zostanie opublikowana lub włączona.

    • triggerId: unikalny ciąg UUID identyfikujący tę instancję rejestracji aktywatora.

    • notifyUri: unikalny adres URL punktu końcowego API (typu) REST powiązany z tą rejestracją aktywatora (np. https://workspacestudio.googleapis.com/v1/triggers/YOUR_TRIGGER_ID:fire). Jeśli notifyUri zostanie pominięty w ładunku zdarzenia, utwórz adres URL punktu końcowego bezpośrednio za pomocą triggerId: https://workspacestudio.googleapis.com/v1/triggers/{triggerId}:fire.

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

  • Usunięcie reguły (event.workflow.triggerDeletion): wywoływane, gdy aktywator zostanie usunięty z automatyzacji lub gdy cała automatyzacja zostanie wyłączona lub usunięta.

    • triggerId: unikalny ciąg UUID instancji subskrypcji do wyczyszczenia.

Cykl życia subskrypcji w alternatywnych środowiskach wykonawczych (HTTP API)

W przypadku dodatków utworzonych za pomocą alternatywnych środowisk wykonawczych powiadomienia o cyklu życia subskrypcji są dostarczane za pomocą żądań POST HTTP do skonfigurowanego adresu URL punktu końcowego HTTP dodatku z nazwą działania określoną przez funkcję wywołania zwrotnego onManageFunction. Ładunek jest zgodny z reprezentacją 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 użytkownika, obsługiwać zdarzenia cyklu życia subskrypcji za pomocą onManageTrigger i wywoływać żądanie aktywatora z powrotem do Google, gdy wystąpi zdarzenie.

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;
    // Fall back to constructing the endpoint URL if notifyUri is omitted.
    const notifyUri = triggerCreation.notifyUri ||
        ("https://workspacestudio.googleapis.com/v1/triggers/" +
         triggerId + ":fire");
    const inputs = triggerCreation.inputs;

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

    // Tip: In Apps Script, use PropertiesService to persist triggerId and notifyUri:
    // const props = PropertiesService.getUserProperties();
    // props.setProperty("notifyUri", notifyUri);
    // props.setProperty("triggerId", triggerId);
    //
    // 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;

    // In Apps Script, clean up stored properties:
    // PropertiesService.getUserProperties().deleteProperty("notifyUri");
    // PropertiesService.getUserProperties().deleteProperty("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.
 *     In Apps Script, defaults to ScriptApp.getOAuthToken().
 */
function simulateEventFire(notifyUri, triggerId, userAccessToken) {
  // In Apps Script, obtain the OAuth token using ScriptApp.getOAuthToken().
  const token = userAccessToken || ScriptApp.getOAuthToken();
  // 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 " + token
    },
    "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 Workspace Studio API

Możesz używać Workspace Studio API (workspacestudio.googleapis.com), aby programowo powiadamiać Google o zdarzeniach aktywatora.

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

Powiadamianie o zdarzeniu aktywatora

Wywołuje aktywator za pomocą metody triggers.fire , aby zainicjować wykonanie automatyzacji.

  • 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 wywołać aktywator 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 aktywatora w formacie triggers/{triggerId}.
  • outputs (mapa, opcjonalna): mapa zmiennych wyjściowych aktywatora reprezentujących dane zdarzenia. Każda wartość jest obiektem VariableData obsługującym listy typów (np. stringValues, booleanValues, integerValues).
  • log (obiekt, opcjonalny): reprezentacja znacznika TextFormat wyświetlana w historii aktywności wykonania 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 ponawiania.

Odpowiedź

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

Limity Workspace Studio API

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

Obowiązują te limity:

Typ limitu Quota
Na minutę na projekt 1000 żądań aktywatora
Na minutę na użytkownika 100 żądań aktywatora

Typy limitów:

  • Na minutę na projekt w chmurze: ogranicza łączną liczbę zdarzeń aktywatora wywoływanych z jednego projektu w chmurze Google dewelopera do 1000 żądań na minutę we wszystkich użytkownikach uruchamiających jego aktywatory.
  • Na minutę na użytkownika: ogranicza łączną liczbę wywołań polecenia inicjującego przez jednego użytkownika w danym projekcie w chmurze do 100 żądań na minutę.

Obsługa błędów limitu czasu

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 błędy, Twój kod powinien przechwycić wyjątek i zastosować strategię skróconego wzrastającego czasu do ponowienia. Wzrastający czas do ponowienia ponawia nieudane żądania z coraz dłuższymi opóźnieniami między próbami, w tym z losowym opóźnieniem (ponowne obliczanie losowego opóźnienia w każdej iteracji), aby zapobiec synchronizacji i ponawianiu przez wielu klientów w tym samym czasie:

  1. Wyślij żądanie do Workspace Studio API.
  2. Jeśli żądanie nie powiedzie się z 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 ponownie.
  4. Jeśli ponownie się nie powiedzie, poczekaj 4 seconds + random_number_milliseconds i spróbuj ponownie.
  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 tym stałym opóźnieniem, aż do osiągnięcia maksymalnego limitu ponowień. Następnie zatrzymaj działanie i zarejestruj błąd.

Sprawdzone metody

Podczas projektowania i implementowania aktywatora pamiętaj o tych sprawdzonych metodach:

Emitowanie pojedynczych zdarzeń zamiast list zbiorczych

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

  • Spójność z wbudowanymi aktywatorami: w Workspace Studio, wbudowane aktywatory Google Workspace (np. otrzymanie e-maila w Gmailu lub dołączenie użytkownika do pokoju w Google Chat) są wywoływane przez pojedyncze zdarzenie. Emitowanie zdarzeń z pojedynczymi elementami jest zgodne z tym zachowaniem i zapewnia użytkownikom spójne, przewidywalne działanie we wszystkich aktywatorach.
  • Prostsza konfiguracja automatyzacji: kolejne kroki w automatyzacji zwykle przetwarzają po jednym elemencie na raz. Emitowanie zdarzeń z pojedynczymi elementami umożliwia użytkownikom bezpośrednie mapowanie zmiennych bez dodawania złożonych kroków do iteracji tablic lub analizowania list.
  • Indywidualna obsługa sprawdzania i zmian zbiorczych: jeśli usługa backendu sprawdza zewnętrzne API i wykryje wiele zmienionych elementów w jednym interwale sprawdzania, wywołaj osobne zdarzenie aktywatora dla każdego elementu, zamiast łączyć je w jedno zdarzenie zbiorcze.
  • Zarządzanie liczbą zdarzeń i limitami: ponieważ wywoływanie pojedynczych zdarzeń dla wielu zmienionych elementów może spowodować nagły wzrost liczby żądań, upewnij się, że Twoja usługa mieści się w limitach Workspace Studio API (np. 100 żądań na minutę na użytkownika). Jeśli cykl sprawdzania zwróci dużą liczbę elementów (np. ponad 100 zmienionych rekordów), ogranicz lub zmniejsz liczbę wysyłanych zdarzeń w czasie, aby uniknąć błędów 429 Too Many Requests.

Podstawowe zachowania i przypadki brzegowe

Podczas integrowania aktywatorów deweloperzy muszą obsługiwać określone zachowania związane z błędami i funkcje środowiska wykonawczego:

  • Brak obsługi testowych uruchomień: Workspace Studio nie obsługuje testowych uruchomień aktywatorów.
  • Idempotencja i zapobieganie powtórkom: chociaż nie jest to bezwzględnie wymagane, w ładunku HTTP lub Apps Script warto umieścić unikalny requestId (np. UUID). Podanie requestId zapewnia idempotentność, umożliwiając interfejsowi API wykrywanie i ignorowanie zduplikowanych powiadomień, co zapobiega wielokrotnemu uruchamianiu automatyzacji dla jednego zdarzenia.

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

    Jeśli użytkownik później ponownie włączy automatyzację, Google zainicjuje nowy cykl życia subskrypcji, wywołując wywołanie zwrotne onManageFunction z nowym zdarzeniem triggerCreation zawierającym nowy triggerId i notifyUri. Poprzedni triggerId zostanie trwale wycofany i nie zostanie ponownie aktywowany, więc Twoja usługa nie powinna sprawdzać, czy stara instancja aktywatora została ponownie włączona. Więcej informacji znajdziesz w artykule Obsługa cyklu życia subskrypcji aktywatora.

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

  • Limity automatyzacji: oprócz limitów 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 automatyzacji.

  • Odmowa dostępu (403) podczas wywoływania reguły: jeśli wywołania punktu końcowego triggers.fire zwracają 403 PERMISSION_DENIED ze stanem błędu SERVICE_DISABLED, sprawdź, czy:

    • Google Workspace Studio API jest włączony w Twoim projekcie w chmurze Google.
    • Jeśli używasz Google Apps Script, Twój projekt jest połączony ze standardowym projektem w chmurze, a nie z domyślnym projektem Apps Script Cloud.
    • Token dostępu OAuth zawiera zakres https://www.googleapis.com/auth/workspace.studio.trigger.