Passo Pedido REST

Descrição

O passo Pedido REST chama uma API REST como um passo de um fluxo de trabalho. É um único passo ao estilo do Postman para todo o ciclo «construir → enviar → inspecionar»: escolha um endpoint (escrito à mão ou importado de uma coleção Postman, de uma especificação OpenAPI/Swagger ou de uma captura HAR), defina cabeçalhos, parâmetros de consulta e um corpo, envie um pedido de teste para ver a resposta em direto e guarde o passo.

Escolhe para onde vai a resposta. Por predefinição, é analisada para uma tabela. Em alternativa, o passo pode capturar a resposta em variáveis do fluxo de trabalho, para que um passo posterior possa ramificar consoante o código de estado ou ler um valor do corpo.

Se fechar ou recarregar o navegador antes de guardar, o editor mantém um rascunho local nesse navegador. Reabra o mesmo passo e escolha Restaurar quando lhe for pedido, para recuperar as definições do pedido não guardadas.

Antes de começar

Normalmente vai querer uma ligação do tipo REST, que contém o URL de base e a autenticação do serviço. O passo também pode chamar diretamente um URL totalmente qualificado, sem ligação. Consulte Ligações REST.

Adicionar um passo Pedido REST

Abra o fluxo de trabalho e adicione um passo no local pretendido.
Escolha Pedido REST (unificado) como tipo de passo (nos passos REST). O editor abre com um separador Pedido, um separador Resposta e um separador Seleção de dados da tabela.

Construir o pedido

No separador Pedido:

Origem dos pontos finais

Escolha como vai indicar o endpoint e o PlaidCloud preenche o pedido por si:

Manual — escreva o método e o URL.
A partir da definição da API da ligação — utilize a definição OpenAPI/Swagger guardada na ligação que escolheu, para não a repetir em cada passo. Consulte Reutilizar a definição da API de uma ligação abaixo.
Coleção Postman (ficheiro) / Coleção Postman (URL) — importe de uma coleção Postman.
OpenAPI / Swagger (URL) / OpenAPI / Swagger (ficheiro) — importe de uma especificação de API.
Arquivo HAR (ficheiro) — importe um pedido capturado do registo 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. O passo preenche o método, o URL, os cabeçalhos, os parâmetros de consulta e o corpo, utilizando o exemplo ou o valor predefinido de cada parâmetro; um parâmetro opcional sem nenhum dos dois começa desativado. Se o pedido já contiver algo que introduziu, o passo pergunta antes de o substituir. Prima Ctrl+Z (Cmd+Z num Mac) quando não estiver a escrever num campo, ou escolha Anular substituição, para repor o pedido anterior.

É fácil restringir um catálogo grande: escreva 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 o passo indica quando uma definição muito grande foi cortada no seu limite de pré-visualização.

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

As três origens baseadas em ficheiro — coleção Postman, OpenAPI/Swagger e arquivo HAR — oferecem cada uma um botão Colar… junto ao seletor de ficheiros. Utilize-o quando tiver o conteúdo à mão mas não o tiver guardado em Documentos: cole o JSON e escolha Utilizar este. O catálogo é carregado de imediato, pelo que não é necessário clicar depois em Carregar catálogo.

O conteúdo colado é utilizado em vez do seletor de ficheiros e dura enquanto o passo se mantiver aberto — não é guardado com o passo, pelo que deve colá-lo novamente se reabrir o passo e quiser recarregar o catálogo a partir dele. Se escolher um ficheiro para essa mesma origem, o ficheiro prevalece e o conteúdo colado é descartado — o passo avisa-o quando isso acontece.

Também pode largar um ficheiro .json sobre o seletor de origem. O passo verifica o conteúdo em relação à origem que escolheu e indica o que está errado, como uma coleção Postman colada onde se espera uma especificação OpenAPI ou um ficheiro que não é JSON, e cada origem tem uma ligação How do I get a …? que explica como exportar uma coleção Postman, uma especificação OpenAPI ou um ficheiro HAR.

Reutilizar a definição da API de uma ligação

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

Defina-a uma vez na ligação (consulte Ligação REST genérica) e depois, em qualquer passo que utilize essa ligação:

Escolha a ligação em Ligação.
Defina Origem dos pontos finais como A partir da definição da API da ligação.
Escolha Carregar catálogo e escolha o seu endpoint.

Todos os passos que partilham essa ligação oferecem a mesma lista de endpoints, e atualizar a definição na ligação atualiza-os a todos.

Resumo da ligação e ambiente

Por baixo do seletor de Ligação, uma linha de resumo mostra o que o passo vai utilizar: o tipo de autenticação, o anfitrião e quantos cabeçalhos predefinidos a ligação envia em cada pedido. Escolha o botão de atualização junto ao seletor depois de alterar a ligação, para recarregar a autenticação, o anfitrião e os cabeçalhos predefinidos sem reabrir o passo. Quando a ligação define ambientes, o seletor de Ambiente escolhe aquele em que o passo é executado.

Ligação, método e endpoint

Ligação — a ligação REST com que autenticar. Deixe-a por definir para chamar diretamente um URL totalmente qualificado. Utilize o atalho de edição junto ao seletor para ver ou editar a ligação selecionada sem sair do editor de pedidos.
Método — GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS.
Endpoint — o caminho (quando há uma ligação definida) ou um URL completo.

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 um interruptor Em e uma descrição. Adicione linhas com Adicionar e remova-as com Remover.
Corpo contém a carga do pedido (JSON, formulário ou texto em bruto) num editor de código.

Formatar JSON indenta o corpo e Validar JSON verifica-o e indica a linha e a coluna de qualquer erro. Ambos tratam cada variável {{…}} como um valor, pelo que as suas variáveis ficam exatamente como foram escritas. Referência de variáveis… lista todas as variáveis que pode utilizar no pedido e Inserir {{…}} coloca uma variável no cursor.

Enquanto edita, o passo assinala problemas por baixo do pedido:

Um nome de cabeçalho ou de parâmetro de consulta que aparece duas vezes, em que um valor se perderia.
Um nome de cabeçalho que parece mal escrito, com uma sugestão Did you mean…, como Authorisation em vez de Authorization.
Um segredo, como um valor de Authorization ou X-API-Key, escrito em texto simples. Guarde-o numa variável de projeto e escreva {{project_var.NAME}} para que o segredo não fique guardado no passo.
Um corpo JSON sem cabeçalho Content-Type: application/json, que alguns servidores recusam com HTTP 415.
Um URL com um esquema mal escrito, uma barra dupla no caminho, uma barra final ou espaços perdidos.

Substituição de variáveis

Em qualquer parte do endpoint, dos cabeçalhos, dos valores de consulta ou do corpo, pode injetar uma variável em tempo de execução colocando o seu nome entre chavetas duplas: {{name}}. Também pode escrever {{var.name}} para uma variável da execução do fluxo de trabalho ou {{project_var.name}} para uma variável de projeto — o prefixo é opcional e ambos resolvem o mesmo nome.

O editor realça os tokens {{...}} detetados 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 guardar.

Apenas as chavetas duplas são substituídas, pelo que uma { ou } isolada num corpo JSON fica exatamente como foi escrita — pode misturar livremente variáveis em JSON, por exemplo {"id": "{{var.order_id}}", "qty": 1}. O nome de uma variável desconhecida faz o passo falhar, para que um erro de escrita surja de imediato.

Quando o fluxo de trabalho é iniciado por um sensor ou webhook, ficam também disponíveis quatro variáveis de acionamento: {{trigger_sensor_id}}, {{trigger_sensor_type}}, {{trigger_fired_at}} e {{trigger_payload_json}} (a carga de entrada como cadeia JSON — analise-a num passo posterior para aceder aos campos aninhados). Numa execução manual ou agendada, estas resolvem-se numa cadeia vazia.

Testar o pedido

Enviar pedido de teste envia o pedido com as definições atuais e mostra a resposta em direto na própria página, para que possa confirmar que a chamada funciona antes de guardar. Prima Ctrl+Enter (Cmd+Enter num Mac) para enviar a partir de qualquer ponto do formulário. Uma linha de estado mostra o estado HTTP e o tempo de resposta, e um temporizador conta enquanto o pedido está em curso. (Isto envia um único pedido; a paginação só é executada quando o passo é executado.)
Testar paginação segue a paginação configurada e indica quantos registos são devolvidos ao longo das páginas (até um limite de pré-visualização), para que possa confirmar que o modo de paginação e os respetivos parâmetros/caminhos se encadeiam corretamente antes de uma execução completa. Só são enviadas as páginas suficientes para atingir o limite.
Copiar como curl copia para a área de transferência um comando curl equivalente, para partilha 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 o respetivo método, URL, cabeçalhos e corpo substituem o pedido atual. A autenticação básica (-u) torna-se um cabeçalho Authorization; as opções não suportadas são comunicadas em vez de descartadas em silêncio. Utilize Anular substituição para restaurar os valores anteriores.

A resposta abre num visualizador com as vistas Formatado e Compacto. Os últimos cinco resultados de teste são mantidos enquanto o passo estiver aberto, e pode escolher um para o ver de novo ou voltar a executá-lo. Quando a resposta contém uma lista de registos, Sugerir define Caminho dos itens como a primeira lista que encontrar.

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

Se alterar os campos do pedido de saída e guardar antes de um Enviar pedido de teste bem-sucedido, o PlaidCloud pergunta Guardar sem um teste bem-sucedido? e escolhe Guardar mesmo assim ou volta atrás. No modo de distribuição, utilize Testar linha 1 para testar a primeira linha da tabela de indutores antes de guardar.

Encaminhar a resposta

No separador Resposta, defina o Destino da resposta:

Tabela (predefinição)

A resposta é analisada para a Tabela de destino, que é obrigatória neste modo. Escolha uma tabela existente ou crie uma a partir do seletor; as vistas não são oferecidas. O grupo Paginação e análise controla a forma:

Formato da linha — Objeto (a predefinição) quando cada registo é um objeto JSON, ou Matriz quando cada registo é uma lista de valores. A matriz não está disponível com Um pedido por linha da tabela. Caminho dos itens indica onde estão os registos dentro da resposta.

Modo de paginação — Sem paginação (a predefinição), Paginação por deslocamento, Paginação por número de página, Paginação por URL da página seguinte, Paginação por cursor ou Paginação por cabeçalho Link (RFC 5988). Parâmetros do modo e Caminhos do modo indicam que parâmetros e campos da resposta conduzem a paginação, e só estão disponíveis quando se escolhe um modo de paginação. Escolher um modo preenche ambos com as respetivas predefinições, que pode editar.

Modo	Predefinição dos parâmetros do modo	Predefiniçã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 a ler 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 página seguinte	`{}`	`{"next": ["next"]}`	Pede o URL encontrado no caminho `next` de cada resposta. Um URL relativo é lido 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`. Acrescente `"send_as": "header"` ou `"send_as": "body_field"` aos Parâmetros do modo para o enviar como cabeçalho do pedido ou como campo do corpo. Para ler o cursor de um cabeçalho da 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` indicada por `rel`.

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

Despejar o JSON em bruto em vez de analisar linhas — guarde a carga em bruto em vez de a analisar para colunas.
Novas tentativas (0 a 100) e Tempo limite (s) (1 a 600) — como o pedido se comporta perante falhas e durante quanto tempo pode ser executado. Uma execução aguarda até ao tempo limite que definiu; Enviar pedido de teste, Testar linha 1 e Testar paginação aguardam no máximo 300 s. As novas tentativas abrangem falhas de ligação, erros do servidor (5xx) e limitação de taxa (HTTP 429) para métodos idempotentes (GET, HEAD, OPTIONS, DELETE). Um POST, PUT ou PATCH só é repetido 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 do servidor, pelo que o corpo de um pedido não idempotente nunca é enviado duas vezes depois de o servidor poder ter agido sobre ele; quando a API devolve um cabeçalho Retry-After, o passo aguarda o intervalo que ele pede (limitado a 2 minutos) antes de repetir.

O separador 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 em direto: envia o pedido do passo através da respetiva ligação, tal como uma execução. Requer uma ligação e pergunta primeiro quando o método não é GET, HEAD nem OPTIONS. Resumir e Distinto não são oferecidos aqui, porque o passo escreve a resposta analisada diretamente na tabela de destino.

Variáveis do fluxo de trabalho

Defina Destino como Variáveis do fluxo de trabalho e indique um Prefixo da variável (um nome simples, como my_call). O passo envia um pedido e escreve quatro variáveis do fluxo de trabalho:

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

Referencie-as a jusante como qualquer variável do fluxo de trabalho — por exemplo {my_call_status}. Este é o bloco de construção para os padrões «enviar um pedido e depois ramificar consoante o resultado».

Enviar um pedido por linha da tabela

Por predefinição, o passo envia um pedido. Para chamar uma API uma vez por cada linha de uma tabela — por exemplo, consultar cada id de cliente de uma tabela, ou enviar cada linha por POST como um registo —, defina Enviar (no separador Pedido) como Um pedido por linha da tabela. Isto revela os campos da tabela de indutores:

Tabela de indutores — escolha a tabela cujas linhas conduzem os pedidos. Escolha-a entre as tabelas do fluxo de trabalho com o seletor ou escreva o nome de uma tabela. As colunas de cada linha ficam disponíveis como tokens {{row.column}}.
Filtro do driver (opcional) — uma cláusula SQL WHERE que limita as linhas utilizadas.
Colunas-chave (opcional) — colunas da tabela de indutores, separadas por vírgulas, a transportar para todas as linhas de saída, para que os resultados se possam unir de novo à tabela de indutores.
Limite de linhas e Simultaneidade — o número máximo de linhas a processar e quantos pedidos são executados ao mesmo tempo.
Máx. pedidos/seg. (opcional) — limite a rapidez com que os pedidos começam em todos os trabalhadores, 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 um pedido a cada dois segundos. Um valor acima de 1000 é executado como 1000, com um aviso. É independente da Simultaneidade: a simultaneidade limita quantos são executados ao mesmo tempo, enquanto o Máx. pedidos/seg. regula a frequência com que um novo começa.
Add Idempotency-Key header (opcional) — para um único pedido POST, PUT ou PATCH (sem paginação) por linha, envia um cabeçalho Idempotency-Key estável derivado de cada linha, para que voltar a executar o passo não crie registos em duplicado numa API que suporte idempotência (a mesma linha envia sempre a mesma chave, pelo que a API elimina a repetição). É ignorado, com um aviso, para GET/HEAD/DELETE ou quando um modo de paginação está ativo. Um pedido que já defina a sua própria Idempotency-Key mantém-na.
Resposta — como cada resposta se torna linhas. Registos analisados (predefinição) escreve cada registo da resposta como uma linha. Texto (uma linha por pedido) escreve uma linha por pedido com as colunas DownloadData e DownloadHeaders; um pedido falhado é descartado. Texto em bruto, erros como linhas também escreve uma linha por pedido, mas mantém o corpo exatamente como o servidor o enviou, acrescenta uma coluna DownloadStatus e mantém um erro HTTP ou de transporte como uma linha com o respetivo corpo de erro e estado. As credenciais são mascaradas no corpo, nos cabeçalhos e no texto de erro de cada linha em bruto, e um redirecionamento para uma origem diferente não é seguido num pedido que transporte credenciais. A paginação não se aplica aos modos de texto. Em Texto (uma linha por pedido), Keep error response (keep_error_response) escreve na linha o corpo de uma resposta HTTP 400 ou superior tal como faz para um sucesso, em vez de fazer a linha falhar, e Adicionar DownloadStatus, DownloadReason e DownloadUrl à saída (response_meta) acrescenta as colunas DownloadStatus, DownloadReason e DownloadUrl com o estado, o motivo e o URL final da resposta. Ambos estão desativados por predefinição. O formulário do passo tem a opção Adicionar DownloadStatus, DownloadReason e DownloadUrl à saída; defina keep_error_response com um assistente de IA ou com a API REST.
Continue on error — quando ativo, uma linha que falha é registada e o passo termina com um aviso em vez de abortar na primeira falha. O registo de execução nomeia as primeiras linhas falhadas (pelas respetivas colunas-chave) e o erro de cada uma, para que possa perceber que linhas falharam e porquê.

Utilize os tokens {{row.column}} em qualquer parte 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 num parâmetro de consulta é codificado como URL uma só vez, pelo que o servidor recebe A 1 e a/b como foram escritos. As versões anteriores codificavam-no duas vezes e o servidor recebia A%201 e a%2Fb. Se um passo POST, PUT ou PATCH tiver Add Idempotency-Key header ativo e um valor de linha que precise de codificação na consulta, a respetiva chave muda uma vez após a atualização, porque o pedido mudou. Uma nova execução que atravesse a atualização pode enviar um pedido repetido por cada uma dessas linhas. Os valores compostos apenas por letras, dígitos e -._~ não se alteram. Os registos da resposta de cada linha são analisados para a tabela de destino (com as colunas-chave eventuais antepostas); com Dump raw JSON ativo, obtém antes uma linha por pedido.

O menu Inserir {{row.column}} lista as colunas da tabela de indutores selecionada, para que possa colocar um token do tipo {{row.customer_id}} no endpoint ou no corpo — o campo que editou por último — em vez de escrever os nomes das colunas à mão. Enquanto edita, o formulário também lista os tokens {{row.column}} que utilizou e realça a vermelho os que não são uma coluna da tabela de indutores, para que os erros de escrita sejam detetados antes de executar o passo.

Testar linha 1 lê a primeira linha da tabela de indutores (respeitando o filtro), substitui os seus valores no endpoint, na consulta, nos cabeçalhos e no corpo, e envia esse pedido — para que possa confirmar que a distribuição está bem ligada antes de a executar sobre todas as linhas. A resposta é mostrada na própria página como em Enviar pedido de teste, juntamente com os valores da linha de indutores utilizados. Preview Row 1 resolve igualmente os valores {{row.column}} da primeira linha da tabela de indutores e mostra o pedido resolvido sem o enviar.

Executar o passo

O passo Pedido REST é executado como qualquer outro — numa execução completa ou isoladamente (consulte Executar um único passo num fluxo de trabalho). No modo de tabela, escreve a resposta analisada (ou em bruto) na tabela de destino; no modo de variáveis, define as quatro variáveis para os passos posteriores lerem.

Passos seguintes

Referência do passo Pedido REST — lista concisa de campos
Gerir variáveis de fluxo de trabalho — ler e definir variáveis entre passos
Ligações REST — configurar ligações de API autenticadas