Criar um starter

Este documento explica como criar um acionador que permite que seu app ou serviço notifique o Google Workspace Studio quando um evento ocorre e inicie a execução de um fluxo. Na API, os acionadores são chamados de workflowTriggers.

Um acionador inicia um fluxo, enquanto uma etapa é uma única tarefa na sequência de tarefas que abrangem um fluxo. Ao criar um acionador, você permite que os usuários configurem fluxos automatizados que reagem a eventos em tempo real do seu app ou serviço.

A criação de um acionador envolve a declaração dele no arquivo de manifesto do complemento e a implementação de callbacks do ciclo de vida no Google Apps Script ou o acionamento do acionador postando payloads no endpoint da API Google Workspace Studio.

Pré-requisitos

Ativar a API

No projeto do Google Cloud, ative a API Google Workspace Studio:

Ativar a API

Mudar para um projeto na nuvem padrão do Google Cloud (somente Google Apps Script)

Por padrão, os projetos do Apps Script usam um projeto padrão do Cloud que não oferece suporte à ativação de APIs ou à configuração de telas de permissão OAuth. Se você estiver criando o acionador com o Apps Script, mude para um projeto na nuvem padrão do Google Cloud:

  1. No editor do Apps Script, clique em Configurações do projeto .
  2. Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.
  3. Insira o número do projeto padrão do Cloud e clique em Definir projeto.
  4. Depois de mudar de projeto, autorize o script novamente executando qualquer função no editor e concedendo as permissões solicitadas.

Para mais informações, consulte Mudar para um projeto na nuvem padrão do Google Cloud.

Configurar a tela de permissão OAuth

Para se comunicar com o endpoint de API do Workspace Studio, seu app ou serviço precisa ser autenticado usando o OAuth 2.0. Configure a tela de permissão OAuth do seu projeto e adicione o seguinte escopo OAuth dedicado:

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

Esse escopo autoriza o app a chamar a Studio API do Workspace Studio e acionar fluxos que o usuário configurou para esse acionador.

Para mais informações, consulte Configurar a tela de permissão OAuth e escolher escopos.

Acesso off-line e tokens de atualização

Como os acionadores notificam o Workspace Studio de forma assíncrona quando um evento ocorre no serviço externo, o que pode acontecer horas, dias ou meses depois que um usuário configura um fluxo, seu serviço precisa fornecer um token de acesso OAuth 2.0 válido ao chamar o endpoint da API.

O token de acesso fornecido pelo Google no objeto de evento do complemento (por exemplo, durante a configuração do acionador ou solicitações de callback do ciclo de vida) é de curta duração e válido apenas por 1 hora. Ele não é suficiente para acionar eventos de acionador de forma assíncrona no futuro. Para chamar a API Workspace Studio ao longo do tempo, seu serviço exige um token de atualização off-line para gerar novos tokens de acesso sob demanda.

A maneira como você processa a autorização e recebe um token de atualização depende do ambiente de execução do complemento:

  • Complementos HTTP (ambientes de execução alternativos): para complementos HTTP, o serviço de back-end precisa implementar um fluxo de autorização OAuth 2.0 separado e independente da autorização integrada do complemento para solicitar acesso off-line (access_type=offline) e receber um token de atualização.

    Você pode pedir aos usuários que autorizem essa conexão mostrando um cartão de login ou autorização quando o usuário configurar o acionador no Workspace Studio. Para mais informações sobre como retornar cartões de autorização e processar o fluxo OAuth, consulte Conectar o complemento do Google Workspace a um serviço de terceiros (tratando o Google Workspace como o serviço de terceiros ao qual você se conecta).

    O serviço de back-end precisa armazenar o token de atualização com segurança (por exemplo, no banco de dados do serviço, ao lado do triggerId) e usá-lo para recuperar um novo token de acesso sempre que um evento ocorrer antes de enviar solicitações para o notifyUri do acionador ou o endpoint de API triggers.fire.

  • Complementos do Google Apps Script: os complementos baseados no Google Apps Script que usam acionadores programados (acionados por tempo) para pesquisar eventos podem pular a implementação de um fluxo OAuth independente. Como os acionadores programados são executados diretamente no ambiente de execução do Google Apps Script, o Google Apps Script gerencia e atualiza automaticamente os tokens OAuth usando os escopos declarados no manifesto. Você pode recuperar um token de acesso OAuth usando ScriptApp.getOAuthToken().

Definir o acionador no arquivo de manifesto

Para definir um acionador, adicione-o ao arquivo de manifesto do complemento (appsscript.json) no bloco addOns.studio.flows.workflowElements. Essa configuração é necessária para os ambientes de execução do Apps Script e HTTP (ambientes de execução alternativos). Configure o elemento como um workflowTrigger em vez de um workflowAction (que é usado ao definir uma etapa). Para mais informações, consulte Estrutura do manifesto para complementos do Google Workspace.

No bloco workflowTrigger, especifique:

  • inputs: variáveis que o usuário configura no cartão de configuração (como nome do projeto, filtro de recursos etc.).
  • outputs: variáveis que podem ser retornadas pelo acionador para etapas downstream no fluxo.
  • onConfigFunction: o nome da função de callback que mostra a interface de configuração do usuário.
  • onManageFunction: o nome da função de callback invocada pelo Google para processar a criação e exclusão de assinaturas de acionadores.

O exemplo de código a seguir mostra uma definição de manifesto para um acionador de eventos:

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

Processar o ciclo de vida da assinatura do acionador

Quando um usuário configura e ativa um fluxo que contém o acionador ou se o fluxo está desativado ou excluído, o Google chama o complemento usando a função de callback onManageFunction declarada no manifesto.

O objeto de evento de ciclo de vida

A função de callback recebe um WorkflowEventObject que contém o contexto da ação. Para acionadores, isso inclui:

  • Criação de acionador (event.workflow.triggerCreation): é acionado quando o fluxo é publicado ou ativado.

    • triggerId: uma string UUID exclusiva que identifica essa instância de registro do acionador.

    • notifyUri: O URL exclusivo do endpoint de API REST associado a este registro do acionador (por exemplo, https://workspacestudio.googleapis.com/v1/triggers/YOUR_TRIGGER_ID:fire). Se notifyUri for omitido do payload do evento, construa o URL do endpoint diretamente usando o triggerId: https://workspacestudio.googleapis.com/v1/triggers/{triggerId}:fire.

    • inputs: as entradas de variáveis configuradas pelo usuário no cartão.

  • Exclusão de acionador (event.workflow.triggerDeletion): é acionado quando o acionador é removido do fluxo ou quando todo o fluxo é desativado ou excluído.

    • triggerId: a string UUID exclusiva da instância de assinatura a ser limpa.

Ciclo de vida da assinatura de ambientes de execução alternativos (API HTTP)

Para complementos criados usando ambientes de execução alternativos, as notificações de ciclo de vida da assinatura são entregues usando solicitações POST para o URL do endpoint HTTP configurado do complemento com o nome da ação especificado pela função de callback onManageFunction. O payload corresponde à representação JSON do WorkflowEventObject.

Para mais informações sobre ambientes de execução alternativos, consulte Criar um complemento do Google Workspace usando endpoints HTTP.

Implementar callbacks do ciclo de vida no Apps Script

O exemplo do Apps Script a seguir mostra como configurar a ficha de informações da interface do usuário, processar eventos de ciclo de vida da assinatura usando onManageTrigger e disparar a solicitação de ativação de volta ao Google quando um evento ocorre.

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

Usar a API Workspace Studio

Você pode usar a API Workspace Studio (workspacestudio.googleapis.com) para notificar o Google de eventos de acionadores de maneira programática.

Os endpoints estão no caminho base: https://workspacestudio.googleapis.com/v1.

Notifica um evento de acionador

Aciona um acionador usando o triggers.fire método para iniciar a execução de um fluxo.

  • Método HTTP: POST
  • Caminho: /v1/triggers/{triggerId}:fire (em que {triggerId} é o identificador exclusivo recuperado durante a criação da assinatura do acionador)
  • Escopo do OAuth: https://www.googleapis.com/auth/workspace.studio.trigger

O exemplo de código a seguir mostra como acionar um acionador na solicitação.

Solicitação

{
  "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, obrigatório): o nome do recurso do acionador, formatado como triggers/{triggerId}.
  • outputs (mapa, opcional): um mapa de variáveis de saída do acionador que representam os dados de eventos. Cada valor é um objeto VariableData que oferece suporte a listas tipadas (como stringValues, booleanValues, integerValues).
  • log (objeto, opcional): uma representação de marcação TextFormat mostrada nos registros de atividade de execução do Workspace Studio.
  • requestId (string, opcional): um identificador exclusivo (UUID v4 recomendado) de até 36 caracteres ASCII para garantir a idempotência da API em novas tentativas.

Resposta

A resposta retorna um objeto JSON vazio {} em caso de sucesso.

Cotas da API Workspace Studio

O tráfego enviado ao serviço workspacestudio.googleapis.com é restrito para evitar a sobrecarga do sistema, incentivar o uso aceitável de recursos e proteger o desempenho geral do Google Workspace.

As seguintes cotas são aplicadas:

Tipo da cota Quota
Por minuto por projeto 1.000 solicitações de acionadores
Por minuto por usuário 100 solicitações de acionadores

Os tipos de cota são:

  • Por minuto por projeto: limita o número cumulativo de eventos de acionadores acionados por um único projeto do Google Cloud do desenvolvedor a 1.000 solicitações por minuto em todos os usuários que executam os acionadores.
  • Por minuto por usuário: limita as invocações cumulativas de ativações de um único usuário final em um determinado projeto na nuvem a 100 solicitações por minuto.

Processar erros de cota com base no tempo

Se você exceder essas cotas, a API vai retornar um código do erro HTTP 429 Too Many Requests (ou 429 Resource Exhausted) indicando que a cota de taxa foi excedida.

Para resolver esses erros, seu código precisa detectar a exceção e usar uma estratégia de espera exponencial truncada. A espera exponencial repete as solicitações com falha usando atrasos cada vez mais longos entre as tentativas, incluindo jitter aleatório (recalculando um atraso aleatório em cada iteração) para evitar que vários clientes sincronizem e tentem novamente ao mesmo tempo:

  1. Faça uma solicitação para a API Workspace Studio.
  2. Se a solicitação falhar com um erro 429, aguarde 1 second + random_number_milliseconds e tente novamente.
  3. Se falhar novamente, aguarde 2 seconds + random_number_milliseconds e tente novamente.
  4. Se falhar novamente, aguarde 4 seconds + random_number_milliseconds e tente novamente.
  5. Continue esse loop, dobrando o atraso até um limite maximum_backoff (normalmente 32 ou 64 segundos).
  6. Quando você atingir a duração máxima de espera, tente novamente usando esse atraso constante até atingir o limite máximo de novas tentativas. Em seguida, interrompa e registre o erro.

Práticas recomendadas

Ao projetar e implementar um acionador, considere as seguintes práticas recomendadas:

Emitir eventos únicos em vez de listas em lote

Projete o acionador para emitir um evento individual para cada ocorrência distinta (como um único registro atualizado, uma nova mensagem postada ou uma tarefa atribuída) em vez de emitir um único evento contendo um lote ou uma lista de itens:

  • Consistência com acionadores integrados: no Workspace Studio, os acionadores integrados do Google Workspace (como receber um e-mail no Gmail ou um usuário entrar em um espaço no Google Chat) são acionados em um único evento. A emissão de eventos de item único se alinha a esse comportamento e oferece uma experiência consistente e previsível para os usuários em todos os acionadores.
  • Configuração de fluxo mais simples: as etapas downstream em um fluxo normalmente processam um item por vez. A emissão de eventos de item único permite que os usuários mapeiem variáveis diretamente sem adicionar etapas complexas para iterar matrizes ou analisar listas.
  • Processar mudanças de pesquisa e lote individualmente: se o serviço de back-end pesquisar uma API externa e detectar vários itens alterados durante um único intervalo de pesquisa, acione um evento de acionador individual para cada item em vez de agrupá-los em um evento de lote.
  • Gerenciar taxa de eventos e cotas: como o acionamento de eventos individuais para vários itens alterados pode causar uma explosão repentina de solicitações, verifique se o serviço permanece dentro das cotas da API Workspace Studio (como o limite de 100 solicitações por minuto por usuário). Se um ciclo de pesquisa gerar um grande volume de itens (por exemplo, mais de 100 registros alterados), acelere ou limite os envios de eventos ao longo do tempo para evitar erros 429 Too Many Requests.

Comportamentos principais e casos extremos

Ao integrar acionadores, os desenvolvedores precisam processar comportamentos de erro específicos e recursos de ambiente de execução:

  • Sem suporte à execução de testes: o Workspace Studio não oferece suporte a execuções de teste para acionadores.
  • Idempotência e prevenção de repetição: embora não seja estritamente necessário, você deve incluir um requestId exclusivo (como um UUID) no payload HTTP ou do Apps Script. Fornecer um requestId garante a idempotência, permitindo que a API detecte e ignore notificações duplicadas, impedindo que o fluxo seja executado várias vezes para um único evento.

  • Fluxos desativados e reativados: quando um fluxo que contém o acionador é desativado no Workspace Studio, o Google envia um evento de ciclo de vida triggerDeletion para o callback onManageFunction. Além disso, todas as chamadas para o método FireTrigger associado retornam um 404 Not Found código de retorno de erro (Requested entity was not found.). Seu serviço precisa reagir a erros 404 interrompendo as entregas de notificações de eventos futuros para esse ID de instância do acionador.

    Se um usuário reativar o fluxo mais tarde, o Google vai iniciar um novo ciclo de vida da assinatura invocando o callback onManageFunction com um novo evento triggerCreation que contém um novo triggerId e notifyUri. O triggerId anterior é desativado permanentemente e não é reativado. Portanto, seu serviço não deve pesquisar ou verificar se uma instância de acionador antiga foi reativada. Para mais informações, consulte Processar o ciclo de vida da assinatura do acionador.

  • Exclusão de assinatura idempotente: a função de callback onManageFunction precisa processar as solicitações de exclusão de acionadores do Google de forma idempotente. Se o Google chamar o hook de exclusão várias vezes para o mesmo triggerId (por exemplo, durante novas tentativas devido a perdas de conexão temporárias), a função vai retornar com sucesso.

  • Cotas de fluxo: além das cotas da API Workspace Studio, os fluxos de usuários estão sujeitos a controles de cota internos adicionais. Loops de alta frequência ou volume excessivo de eventos podem exceder os limites de segurança, resultando na desativação automática do fluxo.

  • Permissão negada (403) no acionamento do acionador: se as chamadas para o triggers.fire endpoint retornarem 403 PERMISSION_DENIED com um SERVICE_DISABLED status de erro, verifique se:

    • A API Google Workspace Studio está ativada no seu projeto do Google Cloud.
    • Se você estiver usando o Google Apps Script, seu projeto estará vinculado a um projeto padrão do Cloud em vez do projeto padrão do Apps Script Cloud.
    • O token de acesso OAuth inclui o escopo https://www.googleapis.com/auth/workspace.studio.trigger.