Ir para o conteúdo

Filtrar resultados de consulta de banco de dados usando parâmetros de solicitação de API no Jitterbit Studio

Introdução

Quando uma operação é publicada como uma API personalizada, os chamadores podem passar valores pela URL como parâmetros de consulta. Este guia mostra como ler esses valores usando variáveis Jitterbit de API e usá-los para filtrar resultados em uma cláusula WHERE de uma atividade Database Query, retornando os registros correspondentes como resposta da API.

Esse padrão é útil para criar endpoints de consulta de dados em que o chamador controla quais registros são retornados: por exemplo, um endpoint GET que busca um cliente por ID, recupera pedidos para um intervalo de datas específico ou retorna produtos filtrados por categoria.

Este guia pressupõe o seguinte:

Padrão de design

flowchart LR A[API client] -->|"GET /customers?CustomerID=123"| B[Custom API] B --> C[Validation script] C --> D[Database Query activity] D --> E[Transformation] E --> F[Response script] F -->|JSON response| A

Parte 1: Adicionar um script de validação de parâmetro

Os parâmetros de URL enviados para a API estão disponíveis como variáveis Jitterbit no formato $jitterbit.api.request.parameters.<name>, em que <name> corresponde à chave do parâmetro na URL. Por exemplo, se um chamador enviar GET /customers?CustomerID=123, então $jitterbit.api.request.parameters.CustomerID contém 123.

Adicione um componente Script como primeira etapa da operação. Este script lê o valor do parâmetro, o armazena em uma variável global mais curta para uso na consulta e retorna um erro 400 se o parâmetro estiver ausente ou vazio:

<trans>
$customer_id = $jitterbit.api.request.parameters.CustomerID;

If(IsNull($customer_id) || Length($customer_id) == 0,
  $err = Dict();
  $err["error"] = "Missing required parameter: CustomerID";
  $jitterbit.api.response = JSONStringify($err);
  $jitterbit.api.response.status_code = 400;
  RaiseError("Missing required parameter");
);
</trans>

IsNull e Length juntas protegem contra um valor ausente e um valor vazio. RaiseError interrompe a execução imediatamente e dispara a ação de erro configurada da operação.

Nota

Configure a ação On Fail da operação para executar uma operação que retorne $jitterbit.api.response ao chamador. Sem uma ação de falha, a resposta 400 definida acima não será entregue. Para detalhes, consulte Configurar tratamento de erros em operações.

Substitua CustomerID pelo nome do parâmetro de URL conforme documentado para sua API. Os nomes dos parâmetros diferenciam maiúsculas de minúsculas.

Parte 2: Configurar a atividade Database Query

Adicione uma atividade Database Query após o script de validação e configure-a para filtrar registros usando o valor do parâmetro capturado. A variável customer_id definida pelo script de validação está disponível para a atividade em tempo de execução.

Usando o assistente

Na Etapa 2: Adicionar condições da configuração da atividade:

  1. Em Selecionar campos, selecione os campos a retornar (por exemplo, CustomerID, Name e Email).

  2. Em cláusula WHERE, use os menus suspensos para selecionar o campo e o operador da condição de filtro.

  3. No campo Valor, insira a variável usando a sintaxe de colchetes:

    [customer_id]

    O ícone de variável no campo indica que variáveis globais, variáveis de projeto e variáveis Jitterbit são todas aceitas aqui. Comece a digitar um colchete de abertura ([) ou clique no ícone para ver as variáveis disponíveis.

  4. Clique em Adicionar para anexar a condição à cláusula WHERE.

  5. Clique em Testar consulta para validar a consulta no banco de dados.

    Dica

    Como customer_id é uma variável global definida apenas em tempo de execução, Testar consulta falhará se nenhum valor estiver presente. Defina um valor padrão em customer_id neste campo (consulte Definir um valor padrão) para que Testar consulta tenha um valor a substituir, sem precisar codificar e remover um valor de amostra no script de validação.

  6. Clique em Next, revise o esquema de dados e clique em FINISHED.

Usando SQL manual

Para conexões JDBC, clique em Skip Wizard / Write SQL Statement na primeira etapa e insira a consulta diretamente. Variáveis entre colchetes são substituídas pelos seus valores em tempo de execução antes da consulta ser executada:

SELECT CustomerID, Name, Email
FROM Customers
WHERE CustomerID = '[customer_id]'

Para colunas numéricas, omita as aspas ao redor:

SELECT OrderID, Total, Status
FROM Orders
WHERE CustomerID = [customer_id]

Parte 3: Retornar os resultados como resposta da API

Adicione uma Transformation após a atividade Query do banco de dados para mapear os campos de resultado para variáveis de saída. Após a transformação, adicione um componente Script à frente para serializar os resultados e definir $jitterbit.api.response:

<trans>
$result = Dict();
$result["CustomerID"] = $out_CustomerID;
$result["Name"] = $out_Name;
$result["Email"] = $out_Email;
$jitterbit.api.response = JSONStringify($result);
$jitterbit.api.response.status_code = 200;
</trans>

Substitua $out_CustomerID, $out_Name e $out_Email pelas variáveis globais para as quais a transformação mapeia os campos de resultado da consulta. Para consultas que podem retornar vários registros, colete-os em um array na transformação e serialize o array.

Se $jitterbit.api.response não for definido antes da conclusão da operação, o API Manager retornará uma resposta vazia 200 OK. Para a lista completa de variáveis disponíveis para controlar a resposta da API, consulte Variáveis Jitterbit de API.

Verificar a integração

  1. Implante o projeto.

  2. Envie uma solicitação de teste para o endpoint publicado com um valor de parâmetro válido:

    GET https://<host>/<service-root>/<version>/<path>?CustomerID=123

    Confirme que o corpo da resposta contém o registro esperado.

  3. Envie uma solicitação com o parâmetro omitido:

    GET https://<host>/<service-root>/<version>/<path>

    Confirme que o endpoint retorna uma resposta 400 com a mensagem de erro do script de validação.

  4. Envie uma solicitação com um valor de parâmetro que não corresponda a nenhum registro. Confirme que a resposta reflete um resultado vazio ou um erro apropriado, dependendo de como a transformação trata uma consulta com zero linhas.

  5. Se alguma etapa retornar um resultado inesperado, abra os logs de operação no Studio e os logs de API no API Manager para diagnosticar o problema.