Etapa Solicitação REST

Descrição

A etapa Solicitação REST chama uma API REST como uma etapa de um fluxo de trabalho. É uma etapa única, no estilo do Postman, para todo o ciclo “construir → enviar → inspecionar”: escolha um endpoint (digitado à mão ou importado de uma coleção do Postman, de uma especificação OpenAPI/Swagger ou de uma captura HAR), defina cabeçalhos, parâmetros de consulta e um corpo, dispare uma solicitação de teste para ver a resposta real e depois salve a etapa.

Você escolhe para onde a resposta vai. Por padrão, ela é analisada em uma tabela. Como alternativa, a etapa pode capturar a resposta em variáveis do fluxo de trabalho, para que uma etapa posterior possa ramificar de acordo com o código de status ou ler um valor do corpo.

Se você fechar ou recarregar o navegador antes de salvar, o editor mantém um rascunho local nesse navegador. Reabra a mesma etapa e escolha Restaurar quando solicitado para recuperar as configurações da solicitação não salvas.

Antes de começar

Em geral, você vai querer uma conexão do tipo REST, que contém a URL base e a autenticação do serviço. A etapa também pode chamar diretamente uma URL totalmente qualificada, sem uma conexão. Consulte Conexões REST.

Adicionar uma etapa Solicitação REST

Abra o fluxo de trabalho e adicione uma etapa onde quiser.
Escolha REST Request (unified) como o tipo de etapa (nas etapas REST). O editor abre com uma guia Solicitação, uma guia Resposta e uma guia Seleção de dados da tabela.

Construir a solicitação

Na guia Solicitação:

Origem do endpoint

Escolha como você fornecerá o endpoint, e o PlaidCloud preenche a solicitação para você:

Manual — digite você mesmo o método e a URL.
Da definição de API da conexão — use a definição OpenAPI/Swagger armazenada na conexão escolhida, para não repeti-la em cada etapa. Consulte Reutilizar a definição de API de uma conexão abaixo.
Coleção do Postman (arquivo) / Coleção do Postman (URL) — importe de uma coleção do Postman.
OpenAPI / Swagger (URL) / OpenAPI / Swagger (arquivo) — importe de uma especificação de API.
Arquivo HAR compactado (arquivo) — importe uma solicitação capturada do log de rede do seu navegador.

Para uma origem importada, escolha Carregar catálogo para listar os endpoints disponíveis e depois escolha um em Endpoint. A etapa preenche o método, a URL, os cabeçalhos, os parâmetros de consulta e o corpo, usando o exemplo ou o valor padrão de cada parâmetro; um parâmetro opcional sem nenhum dos dois começa desativado. Se a solicitação já contiver algo que você digitou, a etapa pergunta antes de substituir. Pressione Ctrl+Z (Cmd+Z no Mac) quando não estiver digitando em um campo, ou escolha Desfazer substituição, para restaurar a solicitação anterior.

Um catálogo grande é fácil de restringir: digite em Filtrar por método, caminho ou nome… para listar apenas os endpoints correspondentes. O catálogo mostra quantos endpoints contém (12 de 340 enquanto filtrado) e quando foi carregado, e a etapa avisa quando uma definição muito grande foi cortada no limite de pré-visualização.

Colar uma coleção ou especificação em vez de escolher um arquivo

As três origens baseadas em arquivo — coleção do Postman, OpenAPI/Swagger e arquivo HAR — oferecem um botão Colar… ao lado do seletor de arquivo. Use-o quando tiver o conteúdo em mãos, mas não o tiver salvo no Document: cole o JSON e escolha Usar este. O catálogo é carregado imediatamente, portanto não é necessário clicar em Carregar catálogo depois.

O conteúdo colado é usado no lugar do seletor de arquivo e dura enquanto a etapa permanecer aberta — ele não é salvo com a etapa, então cole-o novamente se reabrir a etapa e quiser recarregar o catálogo a partir dele. Se você escolher um arquivo para essa mesma origem, o arquivo prevalece e o conteúdo colado é descartado — a etapa avisa quando isso acontece.

Você também pode soltar um arquivo .json sobre o seletor de origem. A etapa verifica o conteúdo em relação à origem escolhida e informa o que está errado, como uma coleção do Postman colada onde se espera uma especificação OpenAPI ou um arquivo que não é JSON, e cada origem tem um link How do I get a …? que explica como exportar uma coleção do Postman, uma especificação OpenAPI ou um arquivo HAR.

Reutilizar a definição de API de uma conexão

Os conectores criados para um serviço específico já conhecem seus endpoints. As conexões REST genéricas e MuleSoft não conhecem — elas podem apontar para qualquer API — por isso permitem anexar a definição da API à própria conexão.

Defina-a uma vez na conexão (consulte Conexão REST genérica) e, depois, em qualquer etapa que use essa conexão:

Escolha a conexão em Conexão.
Defina Origem do endpoint como Da definição de API da conexão.
Escolha Carregar catálogo e escolha seu endpoint.

Toda etapa que compartilha essa conexão oferece a mesma lista de endpoints, e atualizar a definição na conexão atualiza todas elas.

Resumo da conexão e ambiente

Sob o seletor de Conexão, uma linha de resumo mostra o que a etapa usará: o tipo de autenticação, o host e quantos cabeçalhos padrão a conexão envia a cada solicitação. Escolha o botão de atualizar ao lado do seletor depois de alterar a conexão para recarregar sua autenticação, host e cabeçalhos padrão sem reabrir a etapa. Quando a conexão define ambientes, o seletor de Ambiente escolhe em qual deles a etapa é executada.

Conexão, método e endpoint

Conexão — a conexão REST com a qual autenticar. Deixe-a sem definição para chamar diretamente uma URL totalmente qualificada. Use o atalho de edição ao lado do seletor para ver ou editar a conexão selecionada sem sair do editor de solicitações.
Método — GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS.
Endpoint — o caminho (quando uma conexão está definida) ou uma URL completa.

Cabeçalhos, parâmetros de consulta e corpo

Cabeçalhos e Parâmetros de consulta são tabelas editáveis de linhas nome/valor, cada uma com uma chave Em e uma descrição. Adicione linhas com Adicionar e remova-as com Remover.
Corpo contém a carga da solicitação (JSON, formulário ou bruta) em um editor de código.

Formatar JSON indenta o corpo, e Validar JSON o verifica e informa a linha e a coluna de qualquer erro. Ambos leem cada variável {{…}} como um valor, de modo que suas variáveis permanecem exatamente como escritas. Referência de variáveis… lista todas as variáveis que você pode usar na solicitação, e Inserir {{…}} coloca uma variável no cursor.

Enquanto você edita, a etapa sinaliza problemas sob a solicitação:

Um nome de cabeçalho ou de parâmetro de consulta que aparece duas vezes, em que um valor seria perdido.
Um nome de cabeçalho que parece digitado errado, com uma sugestão Did you mean…, como Authorisation em vez de Authorization.
Um segredo, como um valor de Authorization ou X-API-Key, digitado em texto simples. Mantenha-o em uma variável de projeto e escreva {{project_var.NAME}} para que o segredo não seja armazenado na etapa.
Um corpo JSON sem um cabeçalho Content-Type: application/json, que alguns servidores recusam com HTTP 415.
Uma URL com um esquema digitado errado, uma barra dupla no caminho, uma barra final ou espaços soltos.

Substituição de variáveis

Em qualquer lugar do endpoint, dos cabeçalhos, dos valores de consulta ou do corpo, você pode injetar uma variável durante a execução colocando seu nome entre chaves duplas: {{name}}. Você também pode escrever {{var.name}} para uma variável de execução de fluxo de trabalho ou {{project_var.name}} para uma variável de projeto — o prefixo é opcional e ambos resolvem o mesmo nome.

O editor destaca os tokens {{...}} detectados no endpoint, nas tabelas de cabeçalhos e de consulta e no editor do corpo, para que as substituições sejam fáceis de identificar antes de testar ou salvar.

Somente chaves duplas são substituídas, portanto uma única { ou } em um corpo JSON é deixada exatamente como escrita — você pode misturar variáveis livremente no JSON, por exemplo {"id": "{{var.order_id}}", "qty": 1}. O nome de uma variável desconhecida faz a etapa falhar, para que um erro de digitação apareça imediatamente.

Quando o fluxo de trabalho é iniciado por um sensor ou webhook, quatro variáveis de gatilho também estão disponíveis: {{trigger_sensor_id}}, {{trigger_sensor_type}}, {{trigger_fired_at}} e {{trigger_payload_json}} (a carga recebida como uma string JSON — analise-a em uma etapa posterior para chegar aos campos aninhados). Em uma execução manual ou agendada, elas resolvem para uma string vazia.

Testar a solicitação

Enviar solicitação de teste dispara a solicitação com suas configurações atuais e mostra a resposta real em linha, para que você confirme que a chamada funciona antes de salvar. Pressione Ctrl+Enter (Cmd+Enter no Mac) para enviar de qualquer lugar do formulário. Uma linha de status mostra o status HTTP e o tempo de resposta, e um cronômetro avança enquanto a solicitação está em andamento. (Isso envia uma única solicitação; a paginação só é executada quando a etapa é executada.)
Testar paginação segue a paginação configurada e informa quantos registros retornam ao longo das páginas (até um limite de pré-visualização), para que você confirme que o modo de paginação e o encadeamento de seus parâmetros/caminhos estão corretos antes de uma execução completa. Apenas páginas suficientes são disparadas para atingir o limite.
Copiar como curl copia um comando curl equivalente para a área de transferência, para compartilhamento ou depuração (com os segredos mascarados).
Importar de curl faz o inverso: cole um comando curl — por exemplo, o “Copy as cURL” de um navegador — e seu método, URL, cabeçalhos e corpo substituem a solicitação atual. A autenticação básica (-u) se torna um cabeçalho Authorization; opções sem suporte são informadas, em vez de descartadas silenciosamente. Use Desfazer substituição para restaurar os valores anteriores.

A resposta abre em um visualizador com as visões Formatado e Compacto. Os últimos cinco resultados de teste são mantidos enquanto a etapa está aberta, e você pode escolher um para vê-lo novamente ou executá-lo de novo. Quando a resposta contém uma lista de registros, Sugerir define o Caminho dos itens como a primeira lista que encontrar.

O grupo Pré-visualização da solicitação mostra a solicitação exatamente como uma execução a enviaria, com as variáveis resolvidas e os segredos mascarados, sem enviar nada. Escolha Atualizar pré-visualização depois de editar.

Se você alterar os campos da solicitação de saída e salvar antes de um Enviar solicitação de teste bem-sucedido, o PlaidCloud pergunta Salvar sem um teste bem-sucedido? e você escolhe Salvar mesmo assim ou volta. No modo de distribuição, use Testar linha 1 para testar a primeira linha do direcionador antes de salvar.

Direcionar a resposta

Na guia Resposta, defina o Destino da resposta:

Tabela (padrão)

A resposta é analisada na Tabela de destino, que é obrigatória neste modo. Escolha uma tabela existente ou crie uma pelo seletor; visões não são oferecidas. O grupo Paginação e análise controla como:

Formato da linha — Objeto (o padrão) quando cada registro é um objeto JSON, ou Matriz quando cada registro é uma lista de valores. Matriz não está disponível com Uma solicitação por linha da tabela. Caminho dos itens indica onde os registros estão dentro da resposta.

Modo de paginação — Sem paginação (o padrão), Paginação por deslocamento, Paginação por número de página, Paginação por URL da próxima página, Paginação por cursor ou Paginação por cabeçalho Link (RFC 5988). Parâmetros do modo e Caminhos do modo indicam quais parâmetros e campos da resposta conduzem a paginação, e só ficam disponíveis quando um modo de paginação é escolhido. Escolher um modo preenche ambos com seus padrões, que você pode editar.

Modo	Padrão dos parâmetros do modo	Padrão dos caminhos do modo	Como pagina
Deslocamento	`{"offset": "offset", "limit": "limit"}`	`{"has_more": ["has_more"]}`	Envia os parâmetros de consulta de deslocamento e limite e continua lendo enquanto o `has_more` da resposta for verdadeiro.
Número de página	`{"offset": "page"}`	`{"has_more": ["has_more"]}`	Envia o número da página no parâmetro `page` e não envia limite.
URL da próxima página	`{}`	`{"next": ["next"]}`	Solicita a URL encontrada no caminho `next` de cada resposta. Uma URL relativa é lida em relação à página de onde veio.
Cursor	`{"cursor": "after"}`	`{"has_more": ["has_more"], "cursor": ["next_cursor"]}`	Envia o cursor da resposta anterior no parâmetro `after`. Adicione `"send_as": "header"` ou `"send_as": "body_field"` aos Parâmetros do modo para enviá-lo como um cabeçalho de solicitação ou um campo do corpo. Para ler o cursor de um cabeçalho de resposta, como o cabeçalho `x-ms-continuation` que o Azure Cosmos DB envia, coloque `"token_header": "x-ms-continuation"` nos Caminhos do modo no lugar de `has_more` e `cursor`; a última página é a que não tem o cabeçalho.
Cabeçalho Link	`{"rel": "next"}`	`{}`	Segue a relação do cabeçalho de resposta `Link` nomeada por `rel`.

Deslocamento e Número de página aceitam mais chaves em Parâmetros do modo: start é o primeiro deslocamento ou número de página (padrão 0), stop_on_empty para na primeira página sem registros no caminho dos itens, de modo que a resposta não precisa de um campo has_more, e send_limit indica se o parâmetro limit é enviado (padrão verdadeiro para Deslocamento, falso para Número de página).

Despejar JSON bruto em vez de analisar as linhas — armazena a carga bruta em vez de analisá-la em colunas.
Novas tentativas (0 a 100) e Tempo limite (s) (1 a 600) — como a solicitação se comporta em caso de falha e por quanto tempo ela pode ser executada. Uma execução espera até o tempo limite definido; Enviar solicitação de teste, Testar linha 1 e Testar paginação esperam no máximo 300 s. As novas tentativas cobrem falhas de conexão, erros de servidor (5xx) e limitação de taxa (HTTP 429) para métodos idempotentes (GET, HEAD, OPTIONS, DELETE). Um POST, PUT ou PATCH é repetido somente após uma resposta de limitação de taxa (HTTP 429), que indica que o servidor não fez nada com ele, e nunca após um erro de servidor, de modo que o corpo de uma solicitação não idempotente nunca é enviado duas vezes depois que o servidor pode ter agido sobre ele; quando a API retorna um cabeçalho Retry-After, a etapa espera o intervalo solicitado (limitado a 2 minutos) antes de tentar novamente.

A guia Seleção de dados da tabela mapeia os campos da resposta para as colunas da tabela de destino. Inspecionar origem → Populate preenche o mapeamento a partir de uma resposta real: ela envia a solicitação da etapa por meio da conexão, como uma execução faria. Exige uma conexão e pergunta antes quando o método é diferente de GET, HEAD ou OPTIONS. Resumir e Distintos não são oferecidos aqui, porque a etapa grava a resposta analisada diretamente na tabela de destino.

Variáveis do fluxo de trabalho

Defina Destino como Variáveis do fluxo de trabalho e informe um Prefixo da variável (um nome simples, como my_call). A etapa dispara uma solicitação e grava quatro variáveis de fluxo de trabalho:

Variável	Conteúdo
`{prefix}_status`	Código de status HTTP (por exemplo, `200`).
`{prefix}_body`	Corpo da resposta como string (as respostas JSON são armazenadas como texto JSON).
`{prefix}_headers`	Cabeçalhos da resposta como texto JSON.
`{prefix}_elapsed_ms`	Quanto tempo a solicitação levou, em milissegundos.

Referencie-as nas etapas seguintes como qualquer variável de fluxo de trabalho — por exemplo, {my_call_status}. Esse é o bloco de construção para padrões do tipo “disparar uma solicitação e depois ramificar de acordo com o resultado”.

Enviar uma solicitação por linha da tabela

Por padrão, a etapa envia uma solicitação. Para chamar uma API uma vez por linha de uma tabela — por exemplo, consultar cada ID de cliente de uma tabela ou fazer POST de cada linha como um registro — defina Enviar (na guia Solicitação) como Uma solicitação por linha da tabela. Isso revela os campos da tabela de direcionadores:

Tabela de direcionadores — escolha a tabela cujas linhas conduzem as solicitações. Escolha-a entre as tabelas do fluxo de trabalho com o seletor ou digite o nome de uma tabela. As colunas de cada linha ficam disponíveis como tokens {{row.column}}.
Filtro do direcionador (opcional) — uma cláusula SQL WHERE que limita quais linhas são usadas.
Colunas-chave (opcional) — colunas do direcionador, separadas por vírgulas, a serem levadas para cada linha de saída, de modo que os resultados possam ser unidos de volta ao direcionador.
Limite de linhas e Simultaneidade — o número máximo de linhas a processar e quantas solicitações são executadas ao mesmo tempo.
Máx. solic./s (opcional) — limita a rapidez com que as solicitações são iniciadas em todos os workers, para que uma rajada não ultrapasse o limite de taxa da API (0 = sem limite). O valor pode ser fracionário: 0,5 inicia uma solicitação a cada dois segundos. Um valor acima de 1000 é executado como 1000, com um aviso. Isso é independente de Simultaneidade: a simultaneidade limita quantas são executadas ao mesmo tempo, enquanto Máx. solic./s regula a frequência com que uma nova é iniciada.
Add Idempotency-Key header (opcional) — para uma única solicitação POST, PUT ou PATCH por linha (sem paginação), envia um cabeçalho Idempotency-Key estável derivado de cada linha, de modo que executar a etapa novamente não duplique registros em uma API compatível com idempotência (a mesma linha sempre envia a mesma chave, então a API elimina a repetição). É ignorado, com um aviso, para GET/HEAD/DELETE ou quando um modo de paginação está ativado. Uma solicitação que já define seu próprio Idempotency-Key o mantém.
Resposta — como cada resposta se torna linhas. Registros analisados (padrão) grava cada registro da resposta como uma linha. Texto (uma linha por solicitação) grava uma linha por solicitação com as colunas DownloadData e DownloadHeaders; uma solicitação com falha é descartada. Texto bruto, erros como linhas também grava uma linha por solicitação, mas mantém o corpo exatamente como o servidor o enviou, adiciona uma coluna DownloadStatus e mantém um erro HTTP ou de transporte como uma linha, com seu corpo de erro e status. As credenciais são mascaradas no corpo, nos cabeçalhos e no texto de erro de cada linha bruta, e um redirecionamento para uma origem diferente não é seguido em uma solicitação que carrega credenciais. A paginação não se aplica aos modos de texto. Em Texto (uma linha por solicitação), Keep error response (keep_error_response) grava na linha o corpo de uma resposta HTTP 400 ou superior, como faz para um sucesso, em vez de fazer a linha falhar, e Adicionar DownloadStatus, DownloadReason e DownloadUrl à saída (response_meta) adiciona as colunas DownloadStatus, DownloadReason e DownloadUrl com o status, o motivo e a URL final da resposta. Ambos vêm desativados por padrão. O formulário da etapa tem a opção Adicionar DownloadStatus, DownloadReason e DownloadUrl à saída; defina keep_error_response com um assistente de IA ou pela API REST.
Continue on error — quando ativado, uma linha que falha é registrada e a etapa termina com um aviso, em vez de ser interrompida na primeira falha. O log de execução nomeia as primeiras linhas com falha (por suas colunas-chave) e o erro que cada uma encontrou, para que você saiba quais linhas falharam e por quê.

Use tokens {{row.column}} em qualquer lugar do endpoint, da consulta, dos cabeçalhos ou do corpo para substituir os valores dessa linha — por exemplo, GET /customers/{{row.customer_id}}. Um valor em um parâmetro de consulta é codificado como URL uma vez, de modo que o servidor recebe A 1 e a/b como digitados. As versões anteriores o codificavam duas vezes, e o servidor recebia A%201 e a%2Fb. Se uma etapa POST, PUT ou PATCH tiver Add Idempotency-Key header ativado e um valor de linha que precise de codificação em sua consulta, sua chave muda uma vez após a atualização, porque a solicitação mudou. Uma nova execução que atravesse a atualização pode enviar uma solicitação repetida para cada linha desse tipo. Valores formados apenas por letras, dígitos e -._~ não mudam. Os registros de resposta de cada linha são analisados na tabela de destino (com as colunas-chave, se houver, no início); com Despejar JSON bruto em vez de analisar as linhas ativado, você obtém uma linha por solicitação.

O menu Inserir {{row.column}} lista as colunas da tabela de direcionadores selecionada, para que você coloque um token no estilo {{row.customer_id}} no endpoint ou no corpo — o campo que você editou por último — em vez de digitar os nomes das colunas à mão. Enquanto você edita, o formulário também lista os tokens {{row.column}} que você usou e destaca em vermelho os que não são uma coluna da tabela de direcionadores, para que erros de digitação sejam detectados antes de você executar a etapa.

Testar linha 1 lê a primeira linha do direcionador (respeitando o filtro do direcionador), substitui seus valores no endpoint, na consulta, nos cabeçalhos e no corpo e dispara essa única solicitação — para que você confirme que a distribuição está configurada corretamente antes de executá-la em todas as linhas. A resposta é mostrada em linha, como em Enviar solicitação de teste, junto com os valores da linha do direcionador que foram usados. Preview Row 1 também resolve os valores {{row.column}} da primeira linha do direcionador e mostra a solicitação resolvida sem dispará-la.

Executar a etapa

A etapa Solicitação REST é executada como qualquer outra — como parte de uma execução completa ou isoladamente (consulte Executar uma única etapa em um fluxo de trabalho). No modo de tabela, ela grava a resposta analisada (ou bruta) na tabela de destino; no modo de variável, define as quatro variáveis para que as etapas posteriores as leiam.

Próximos passos

Referência da etapa Solicitação REST — lista concisa de campos
Gerenciar variáveis de fluxo de trabalho — leia e defina variáveis entre etapas
Conexões REST — configure conexões de API autenticadas