Construir sequências de consulta dinâmicas para chamadas de API REST no Jitterbit Studio

Introdução

A UI de Parâmetros de Requisição do conector HTTP v2 trata o caso mais comum: um conjunto fixo de nomes de parâmetro cujos valores mudam em tempo de execução. O conector codifica os valores em URL automaticamente. Para uma introdução a essa abordagem, consulte Chamar uma API REST usando o conector HTTP v2.

A construção de sequência de consulta baseada em script é necessária quando:

• Os parâmetros são incluídos ou excluídos condicionalmente com base nos dados de origem (por exemplo, adicionar um filtro status apenas quando um valor de status está presente).
• Os nomes de parâmetro variam em tempo de execução (por exemplo, filter[contact_type] para um tipo de registro e filter[account_type] para outro).
• A URL completa é montada a partir de várias partes orientadas por dados.

Este guia cobre três técnicas para construir sequências de consulta em script: concatenação de string para conjuntos de parâmetro condicional, Replace para substituição de modelo fixo e URLEncode para codificar valores que contêm caracteres especiais.

Construir uma sequência de consulta usando concatenação de string

O padrão básico é:

1. Uma etapa de Script que é executada antes da atividade GET do HTTP v2 constrói a URL e a atribui a uma variável global.
2. O campo Path da atividade GET faz referência a essa variável global.

A estrutura da operação é:

Estrutura de parâmetro fixo com nomes dinâmicos

Quando o conjunto de parâmetro depende de uma condição em tempo de execução (como um tipo de registro que determina quais filtros se aplicam), use uma instrução If para construir a URL apropriada para cada caso:

// Record type determines which filter parameters apply
If($record_type == "contact",
    $query_url = "/records?type=contact&owner=" & URLEncode($owner_email),
    // Else: account record
    $query_url = "/records?type=account&region=" & URLEncode($region)
);

Parâmetros opcionais

Quando qualquer combinação de parâmetro pode ou não estar presente, construa uma string params anexando cada parâmetro apenas quando ele tiver um valor. Usar um prefixo & à frente em cada parâmetro evita um separador à direita:

$params = "";
If($start_date != "",
    $params = $params & "&created_after=" & URLEncode($start_date)
);
If($status != "",
    $params = $params & "&status=" & URLEncode($status)
);
If($owner_email != "",
    $params = $params & "&owner=" & URLEncode($owner_email)
);

// Append the query string only when at least one parameter was set.
// Mid(string, 2) strips the leading & from the first parameter.
If($params != "",
    $query_url = "/records?" & Mid($params, 2),
    $query_url = "/records"
);

Mid com uma posição inicial de 2 retorna a string a partir do segundo caractere em diante, removendo o & à esquerda deixado pelo primeiro parâmetro anexado. A verificação If protege o caso vazio: quando nenhum parâmetro é definido, query_url é /records sem ? à direita.

Substituir valores usando Replace

Quando a estrutura de URL é fixa e apenas valores específicos mudam, uma string de modelo com espaços reservados nomeados pode ser mais limpa que a concatenação. Defina a sequência de consulta completa uma vez e, em seguida, chame Replace uma vez por espaço reservado:

$template = "/contacts?status={status}&created_after={date}&owner={owner}";
$query_url = Replace($template, "{status}", URLEncode($filter_status));
$query_url = Replace($query_url, "{date}",  URLEncode($filter_date));
$query_url = Replace($query_url, "{owner}", URLEncode($owner_email));

Replace substitui a primeira ocorrência correspondente da string de pesquisa. Reatribua query_url em cada chamada para encadear as substituições. Escolha nomes de espaço reservado que não apareçam em outro lugar na URL (por exemplo, evite {id} se o caminho já contiver {id} como um parâmetro de caminho HTTP v2).

Codificar valores de parâmetro usando URLEncode

Ao construir URLs em script, chame URLEncode em cada valor de parâmetro. Sem codificação, valores que contêm caracteres reservados quebram silenciosamente a requisição:

• Um caractere de espaço divide a URL na camada HTTP: o servidor recebe um parâmetro truncado ou malformado e normalmente retorna um erro 400 ou nenhum resultado.
• Um & dentro de um valor é interpretado como um separador de parâmetro, dividindo o valor em dois parâmetros separados.
• Outros caracteres que exigem codificação incluem #, %, =, + e ?.

A tabela a seguir mostra exemplos comuns:

Não codifique o nome do parâmetro, apenas o valor. Nomes de parâmetros em APIs REST são convencionalmente ASCII e não requerem codificação.

Referencie a string de consulta em uma atividade HTTP v2

No campo Path da atividade GET, insira a variável global que contém a URL construída (por exemplo, query_url).

O campo Path segue estas regras:

• Um valor que começa com https:// ou http:// é tratado como uma URL completa e substitui a Base URL da conexão.
• Um valor que começa com / é tratado como um sufixo de caminho e é anexado à Base URL.

Use um sufixo de caminho (começando com /) quando o domínio base e as credenciais de conexão são compartilhados com outras atividades. Use uma substituição de URL completa quando o endpoint de destino está em um host diferente da Base URL, ou quando nenhuma Base URL de conexão está definida.

Verifique a integração

1. Implante e execute a operação.

2. Abra o log de operação e confirme que a atividade GET foi concluída com um código de status bem-sucedido.

3. Para inspecionar a URL exata enviada, adicione uma chamada WriteToOperationLog ao final do script pré-operação:

   WriteToOperationLog("query_url: " & $query_url);
   

   A URL construída aparece na entrada do log de operação da etapa de script. Remova a instrução de log após confirmar que a URL está correta.

4. Se a API retornar resultados inesperados ou um erro 400, confirme que URLEncode é aplicado a todos os valores que podem conter espaços ou caracteres especiais. Uma chamada URLEncode ausente em um valor contendo & ou = é uma fonte comum de falhas silenciosas.