Como chamar uma API externa a partir do Workspace Studio

Um fluxo de trabalho do Google Workspace Studio pode precisar de dados externos ao Gmail, Drive ou Chat: o status de um pedido, um número de um banco de dados ou uma resposta de uma ferramenta interna. Para recuperar esses dados ou enviar informações para outro serviço, você pode adicionar a etapa. Enviar um webhookIsso cria uma solicitação HTTP para o endereço de uma API que você especificou.

Você não precisa configurar a chamada da função Gemini para fazer essa solicitação. No Workspace Studio, o fluxo executa a etapa do webhook e recebe a resposta. Em seguida, se achar útil, você pode passar essa resposta para outra etapa para resumi-la, extrair dados ou comunicar o resultado.

O que você precisa antes de se conectar a uma API

O primeiro passo é verificar se sua organização pode usar webhooks. A função está localizada em pré-visualização limitada e está desativado por padrão. Um administrador precisa fazer login. Aplicativos > Google Workspace > Workspace Studio > Configurações de Webhook e habilitá-lo para a unidade organizacional correspondente.

Em algumas versões, o administrador também pode limitar as conexões a uma única conexão. Lista de domínios e URLs permitidosSe a etapa aparecer no Studio, mas não conseguir se comunicar com sua API, verifique se o endereço de destino está autorizado. Além disso, por padrão, as ações que envolvem webhooks exigem que o usuário revise e confirme a etapa antes da execução.

A partir do serviço externo, você precisa saber o URL, os métodos HTTP que ele suporta e o formato de dados esperado. Além disso, verifique como ele realiza a autenticação: uma API pública somente leitura tem requisitos diferentes de uma API privada que exige tokens ou cabeçalhos especiais.

Como chamar uma API a partir do Workspace Studio passo a passo

Digitar estúdio.espaço de trabalho.google.com Crie um fluxo de trabalho com o gatilho desejado. Por exemplo, você pode iniciá-lo quando um e-mail que atenda a determinadas condições chegar. Em seguida, siga estas etapas:

1. Imprensa Adicionar etapa e selecione Enviar um webhook.
2. Entre no URL completa da API, incluindo o prefixo https://O endereço deve ser fixo: este campo não suporta variáveis ​​de fluxo.
3. Selecione o método HTTP. PEGAR É utilizado para consultar dados; PUBLICARpara enviá-los ou criar um registro. Eles também estão disponíveis PUT, PATCH e DELETE.
4. Se a API exigir um corpo, escreva-o no campo de conteúdo ou carga útilO Google recomenda o uso de JSON quando o serviço receptor o espera.
5. Faça um execução de testeVerifique o resultado e ative o fluxo assim que tiver confirmado que está funcionando.

Lembre-se que o teste executar a açãoSe você configurar um POST para criar um registro ou um DELETE para excluí-lo, primeiro use um ambiente de teste ou dados que você possa modificar sem problemas.

Exemplo: enviar uma notificação para uma ferramenta externa

Imagine que sua equipe tenha uma API que cria alertas em https://api.ejemplo.com/v1/avisosEste endereço é ilustrativoVocê precisará substituí-lo pelo do seu serviço. Se a documentação indicar que ele aceita POST e um corpo JSON, você poderá configurar a etapa com conteúdo como {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Você também pode inserir um variável de fluxo No corpo do código, por exemplo, inclua o assunto do e-mail que o gerou. Faça isso usando o seletor de variáveis ​​do Studio e verifique o resultado: se o texto inserido contiver aspas ou outros caracteres especiais, o JSON poderá ficar corrompido. Variáveis ​​podem ser usadas no conteúdo, mas não está no campo URL.

Se precisar recuperar dados, escolha GET e insira um URL fixo que já contenha os parâmetros necessários. O Workspace Studio ignorará qualquer conteúdo que você tenha escrito no corpo de uma solicitação GET.

O que fazer com a resposta da API?

A etapa do webhook deixa o resposta do serviço em formato de texto em uma variável disponível para etapas subsequentes. Você pode usá-la para enviar uma notificação, escrever um resumo ou solicitar que uma etapa de IA extraia dados específicos.

Por exemplo, se a API retornar o status de um pedido, a próxima etapa pode comunicar esse status à equipe. Selecione explicitamente a variável que contém a resposta: as etapas subsequentes não recebem automaticamente tudo o que aconteceu anteriormente no fluxo. É recomendável testar o conteúdo retornado antes de escrever instruções que dependam dele.

Se a API exigir autenticação ou uma lógica mais complexa

A configuração básica documentada para Enviar um webhook Inclui a URL, o método e um corpo opcional. Se a sua integração precisar obter um token OAuth, construir uma URL com parâmetros variáveis, adicionar cabeçalhos específicos ou transformar uma resposta antes de prosseguir, verifique se esta etapa atende a esses requisitos.

Quando isso não for suficiente, uma opção é desenvolver um Etapa personalizada para o Workspace Studio por meio de um plugin. Em uma implementação do Google Apps Script, o serviço UrlFetchApp Permite fazer requisições a APIs externas e processar respostas em JSON. Essa solução requer desenvolvimento e configuração adequada de permissões; não é necessária para requisições simples que a etapa nativa já consegue lidar.

Evite colar chaves privadas em campos visíveis do fluxo ou incorporá-las em um URL compartilhado. Antes de enviar dados do Gmail, Chat ou Agenda, verifique quais informações o serviço externo receberá e se ele está autorizado a processá-las.

Como localizar erros em um webhook

Se a conexão falhar, abra a aba. Atividade do fluxo. Lá, você pode visualizar o erro completo e a resposta enviada pelo servidor de destino. Essas informações ajudam a distinguir entre um problema de configuração do Studio e uma solicitação rejeitada pela API.

• A etapa não aparece: Verifique com o administrador se os webhooks estão habilitados para a sua unidade organizacional.
• O URL está bloqueado: Verifique a lista de endereços permitidos, caso sua edição utilize essa restrição.
• Erro 400: Verifique o formato do corpo da requisição e os campos exigidos pela API.
• Erro 401 ou 403: Analise as permissões e o método de autenticação exigidos pelo serviço.
• Erro 429: Verifique se você excedeu o limite de solicitações para a API de destino.
• Erro 500: Verifique o status e os registros do serviço que recebeu a solicitação.

Tenha em mente também as limitações gerais do Workspace Studio: atualmente, ele suporta até 25 fluxos por usuário y 20 etapas por fluxoAlém disso, existe um limite de execução combinado que é redefinido a cada 24 horas. Se vários fluxos pararem de funcionar, revise a atividade deles antes de atribuir a falha à API.

Para a maioria das conexões HTTP simples, o processo é direto: habilite o webhook, configure uma URL fixa e o método correto, teste a requisição e use a resposta nas etapas subsequentes. Se a integração exigir autenticação avançada ou transformação de dados por meio de código, então faz sentido preparar uma etapa personalizada.