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 então os registros correspondentes como resposta da API.

Esse padrão é útil para criar endpoints de consulta de dados onde 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 assume o seguinte:

• Uma conexão de banco de dados está configurada e acessível no projeto.
• A operação é publicada como uma API personalizada com o tipo de resposta definido como Variable. Para as etapas de configuração, consulte Expor uma operação do Studio como uma API REST.

Padrão de design

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 conterá 123.

Adicione um componente Script como a primeira etapa da operação. Esse 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.

Substitua CustomerID pelo nome do parâmetro de URL conforme documentado para sua API. Os nomes de 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 de 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

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

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

2. Em WHERE clause, use os menus suspensos para selecionar o campo e o operador para a condição de filtro.

3. No campo Value, 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 Add para anexar a condição à cláusula WHERE.

5. Clique em Test Query para validar a consulta em relação ao banco de dados.

   Dica

   Como customer_id é uma variável global definida apenas em tempo de execução, Test Query falhará se nenhum valor estiver presente. Defina um valor padrão em customer_id neste campo (consulte Definir um valor padrão) para que Test Query 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 digite a consulta diretamente. Variáveis entre colchetes são substituídas pelos seus valores de 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 envolventes:

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 retorna uma resposta 200 OK vazia. Para obter a lista completa de variáveis disponíveis para controlar a resposta da API, consulte Variáveis Jitterbit da 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 sem linhas.

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