Gatilho de REST API

Versão de lançamento: Xanadu

Atualizado 1 de ago. de 2024

4 min. de leitura

Inicie um fluxo a partir de uma chamada de API de entrada ou webhook de um sistema externo. Configure as condições de início do gatilho sem precisar escrever ou manter código personalizado.

Por exemplo, você pode criar um fluxo que inicia quando um sistema de acompanhamento de tíquete de TI de terceiros envia uma solicitação de entrada para a instância. Você pode analisar os dados da solicitação REST de entrada em um objeto de dados complexo e usar os valores para abrir um incidente em sua instância.

Depois de ativar o fluxo, o endpoint criado aparece no explorador de APIs no namespace que você criou. Você pode usar esta página para ajudar a definir o webhook em seu sistema de terceiros e para testar seu fluxo.

Para saber mais sobre gatilhos de fluxo, consulte Workflow Studio tipos de gatilho.

Nota:

Use o gatilho de REST API para iniciar fluxos de chamadas REST de sistemas externos. Para iniciar um fluxo a partir de um script ou chamada de API da mesma instância, use um subfluxo, snippet de código ou Workflow Studio API. Confira Acesso de API a Workflow Studio e Criar snippets de código para fluxos, subfluxos e ações.

Cápsulas de dados disponíveis

Dependendo de como você configura o endpoint, os Flow Designers têm acesso a essas cápsulas de dados do gatilho:

Parâmetros de caminho: Um objeto que contém parâmetros de caminho na solicitação de entrada.
Parâmetros de consulta: Um objeto que contém parâmetros de consulta na solicitação de entrada.
Solicitar Cabeçalhos: Um objeto que contém cabeçalhos na solicitação de entrada.
Corpo da Solicitação: Objeto de dados complexo que define a estrutura do corpo da solicitação de entrada. Para obter mais informações sobre objetos complexos, consulte Complex data.

Ao configurar o gatilho, defina a aparência dos dados de entrada. Você pode usar as cápsulas de dados associadas nas ações em seu fluxo. Quando o sistema recebe uma solicitação de entrada que inicia o fluxo, ele usa os valores de tempo de execução enviados na solicitação.

Criar um fluxo usando o gatilho de REST API

Crie um fluxo que inicia quando um sistema de terceiros envia uma solicitação REST para sua instância.

Antes de Iniciar

Função necessária: flow_designer ou admin.

Nota:

Este recurso exige uma assinatura Integration Hub corporativa. Para obter mais informações, consulte Solicitação Integration Hub.

Procedimento

Abra Workflow Studio e crie um fluxo.

Consulte Criar um fluxo.

Lembre-se de que o escopo do fluxo está incluído no endpoint REST criado.
Na seção GATILHO, selecione o gatilho REST API - Assíncrono.
No campo Método HTTP, defina o método HTTP para o endpoint.
As opções incluem:
- POST
- GET
- DELETE
- PUT
- PATCH
Crie todos os parâmetros de caminho necessários para o endpoint e adicione-os ao caminho relativo no campo Caminho.
O caminho relativo para o endpoint está no formato /api/<flow-application-scope> /<flow-name> /<path-parameters> .
Você pode clicar em Copiar para copiar o caminho completo para o endpoint. Use este caminho ao configurar o endpoint para a chamada REST em seu sistema de terceiros.
1. Crie variáveis na seção Parâmetros de caminho.
2. Arraste a cápsula de dados que representa o parâmetro de caminho para a entrada vazia no campo Caminho.
  
  Este campo aceita somente cápsulas de dados da seção Parâmetros de caminho.
Selecione Requer autenticação para exigir cabeçalhos de autenticação na solicitação REST de entrada.
Se Requer autenticação estiver selecionado, adicione as funções necessárias para autorizar a solicitação no campo Funções necessárias.
No campo Corpo da seção Conteúdo da solicitação, crie um objeto de dados complexo que define a estrutura do corpo da solicitação de entrada.

Para obter mais informações sobre como criar um objeto complexo, consulte Dados complexos.

Nota:
A seção Solicitar conteúdo aparece somente quando o Método HTTP é POST, PUT ou PATCH.

Este corpo de exemplo encontra o campo Descrição em uma carga útil de entrada que contém informações de tíquete de um sistema de acompanhamento de tíquete de terceiros.
No campo Cabeçalhos, defina os cabeçalhos a serem enviados na solicitação de entrada.
Você pode selecionar Obrigatório para exigir que a solicitação de entrada os inclua.
No campo Parâmetros de consulta, defina os parâmetros de consulta a serem enviados na solicitação de entrada.
Você pode selecionar Obrigatório para exigir que a solicitação de entrada os inclua.
Adicione ações ao fluxo que são executadas quando o endpoint é chamado.

Você pode usar as cápsulas de dados do gatilho de REST API em suas ações de fluxo.

Esta ação cria um registro de incidente e mapeia os campos Descrição e Grupo de atribuição da carga de entrada para o incidente.
Teste e ative o fluxo.
Para obter mais informações, consulte Testar um fluxo e Ativar um fluxo.
Depois de ativado, o endpoint é exibido no Explorador de REST API. Você pode usar esta página para testar ainda mais o endpoint ou configurar a solicitação do sistema de terceiros.

Configure a solicitação REST do seu sistema de terceiros.

Por exemplo, você pode enviar esta solicitação cURL para acionar o fluxo definido nas etapas anteriores.

curl "https:your-instance.servicenow.com/api/now/create_incident_from_external_event/assignment_group/287ebd7da9fe198100f92cc8d1d2154e" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
fields: {
   description: \"Major outage with data loss\"
   }
}" \
--user 'username':'password'

Resultado

O fluxo é executado e a solicitação REST retorna o ID de execução.

{
  "result": {
    "executionId": "ndoxeRhshDSezldeGfbYlviFSeFnBjCO"
  }
}

O que Fazer Depois

Copie o ID de execução no resultado e navegue até a guia Execuções no Flow Designer. Você pode filtrar por ID de execução para localizar os detalhes da execução e exibir o status da execução.

Para solucionar problemas, você pode depurar a consulta REST ou verificar os detalhes de execução do fluxo. Consulte Depurar consultas REST e Detalhes de execução de fluxo.