Pular para o conteúdo

Passo Pedido REST

O passo Pedido REST chama uma API REST como um passo de um fluxo de trabalho. É um passo único, 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 tempo real e depois guarde o passo.

Escolhe para onde vai a resposta. Por predefinição, é analisada para uma tabela. Em alternativa, o passo pode capturar a resposta para 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. Volte a abrir o mesmo passo e escolha Restaurar quando lhe for pedido para recuperar as definições do pedido não guardadas.

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

  1. Abra o fluxo de trabalho e adicione um passo onde pretender.
  2. 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.

No separador Pedido:

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

  • Manual — escreva você mesmo o método e o URL.
  • A partir da definição da API da ligação — use a definição OpenAPI/Swagger guardada na ligação que escolheu, para não a repetir em cada passo. Veja 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 a partir 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, usando 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 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.

Um catálogo grande é fácil de restringir: 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 assinala 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

Seção intitulada “Colar uma coleção ou especificação em vez de escolher um ficheiro”

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

O conteúdo colado é usado em vez do seletor de ficheiros e dura enquanto o passo se mantiver aberto — não é guardado com o passo, por isso cole-o novamente se voltar a abrir 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 informa-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 esperava 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.

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 permitem anexar a definição da API à própria ligação.

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

  1. Escolha a ligação em Ligação.
  2. Defina Origem dos pontos finais como A partir da definição da API da ligação.
  3. Escolha Carregar catálogo e selecione 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.

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

  • Ligação — a ligação REST com que autenticar. Deixe-a por definir para chamar diretamente um URL totalmente qualificado. Use 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 está definida uma ligação) ou um URL completo.
  • Cabeçalhos e Parâmetros de consulta são tabelas editáveis de linhas nome/valor, cada uma com um comutador 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 leem 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 usar 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 Authorization ou X-API-Key, escrito em texto simples. Guarde-o numa variável do projeto e escreva {{project_var.NAME}} para que o segredo não fique armazenado 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 indevidos.

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 envolvendo o seu nome em chavetas duplas: {{name}}. Também pode escrever {{var.name}} para uma variável de execução do fluxo de trabalho ou {{project_var.name}} para uma variável do 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 ver antes de testar ou guardar.

Apenas as chavetas duplas são substituídas, pelo que uma { ou } simples num corpo JSON fica exatamente como foi escrita — pode misturar variáveis livremente 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 recebida como uma cadeia JSON — analise-a num passo posterior para aceder a campos aninhados). Numa execução manual ou agendada, estas resolvem para uma cadeia vazia.

  • Enviar pedido de teste envia o pedido com as suas definições atuais e mostra a resposta em tempo real, 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 um comando curl equivalente para a área de transferência para partilha ou depuração (com os segredos ocultados).
  • 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. Use Anular substituição para repor os valores anteriores.

A resposta abre num visualizador com vistas Formatado e Compacto. Os últimos cinco resultados de teste são mantidos enquanto o passo está aberto, e pode escolher um para o ver novamente 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 ocultados, 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, use Testar linha 1 para testar a primeira linha do indutor antes de guardar.

No separador Resposta, defina o Destino da resposta:

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 como:

  • Formato da linha — Objeto (o predefinido) quando cada registo é um objeto JSON, ou Matriz quando cada registo é uma lista de valores. 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 (o predefinido), 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 é escolhido um modo de paginação. Escolher um modo preenche ambos com os respetivos valores predefinidos, 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. Adicione "send_as": "header" ou "send_as": "body_field" a 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" em 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.

    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 (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 em 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 espera até ao tempo limite que definir; Enviar pedido de teste, Testar linha 1 e Testar paginação esperam no máximo 300 s. As novas tentativas cobrem 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 espera 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 tempo real: envia o pedido do passo através da sua ligação, como uma execução faria. Precisa de uma ligação e pergunta primeiro quando o método é qualquer outro que não GET, HEAD ou OPTIONS. Resumir e Distinto não são oferecidos aqui, porque o passo escreve a resposta analisada diretamente na tabela de destino.

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}. É o bloco de construção dos padrões “enviar um pedido e depois ramificar consoante o resultado”.

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 como um registo por POST —, 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 usadas.
  • Colunas-chave (opcional) — colunas do indutor separadas por vírgulas a transportar para cada linha de saída, para que os resultados se juntem de novo ao indutor.
  • Limite de linhas e Simultaneidade — o número máximo de linhas a processar e quantos pedidos são executados em simultâneo.
  • Máx. pedidos/seg. (opcional) — limita a rapidez com que os pedidos são iniciados em todos os trabalhadores, para que um pico não ultrapasse o limite de taxa da API (0 = sem limite). O valor pode ser uma fração: 0,5 inicia um pedido a cada dois segundos. Um valor superior a 1000 é executado como 1000 com um aviso. É independente de Simultaneidade: a simultaneidade limita quantos são executados em simultâneo, enquanto Máx. pedidos/seg. regula a frequência com que um novo é iniciado.
  • 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 o seu próprio Idempotency-Key mantém-no.
  • Resposta — como cada resposta se torna em 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 ocultadas 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 transporta 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 falhar a linha, 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. Ambas estão desativadas 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 saber que linhas falharam e porquê.

Use 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 tal 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 sua 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 linha desse tipo. Os valores compostos apenas por letras, dígitos e -._~ não mudam. Os registos de resposta de cada linha são analisados para a tabela de destino (com as colunas-chave eventuais antepostas); com Despejar o JSON em bruto ativo, obtém uma linha por pedido.

O menu Inserir {{row.column}} lista as colunas da tabela de indutores selecionada, para que possa colocar um token do estilo {{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 usou 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 do indutor (respeitando o filtro do indutor), 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 do indutor que foram usados. Preview Row 1 resolve igualmente os valores {{row.column}} da primeira linha do indutor e mostra o pedido resolvido sem o enviar.

O passo Pedido REST é executado como qualquer outro — como parte de uma execução completa ou isoladamente (veja Executar um 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.