Construa strings de consulta dinâmicas para chamadas de API REST no Jitterbit Studio

Introdução

A interface de usuário de Parâmetros de Solicitação do conector HTTP v2 lida com o caso mais comum: um conjunto fixo de nomes de parâmetros cujos valores mudam em tempo de execução. O conector codifica automaticamente os valores em URL. Para uma introdução a essa abordagem, veja Chamar uma API REST usando o conector HTTP v2.

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

• Parâmetros são incluídos ou excluídos condicionalmente com base nos dados de origem (por exemplo, adicionando um filtro status apenas quando um valor de status está presente).
• Os nomes dos parâmetros 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 baseadas em dados.

Este guia cobre três técnicas para construir strings de consulta em script: concatenação de strings para conjuntos de parâmetros condicionais, Replace para substituição de modelo fixo e URLEncode para codificação de valores que contêm caracteres especiais.

Construa uma string de consulta usando concatenação de strings

O padrão básico é:

1. Um passo de Script que é executado antes da atividade GET do HTTP v2 constrói a URL e a atribui a uma variável global.
2. O campo Caminho 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âmetros depende de uma condição em tempo de execução (como um tipo de registro que determina quais filtros se aplicam), use uma declaraçã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âmetros pode ou não estar presente, construa uma string params anexando cada parâmetro apenas quando ele tiver um valor. Usar um prefixo & em cada parâmetro evita um separador final:

$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, removendo o & inicial deixado pelo primeiro parâmetro anexado. A verificação If protege o caso vazio: quando nenhum parâmetro está definido, query_url é /records sem um ? final.

Substituir valores usando Replace

Quando a estrutura da URL é fixa e apenas valores específicos mudam, uma string de modelo com espaços reservados nomeados pode ser mais limpa do que a concatenação. Defina a string 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ços reservados 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âmetros 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 solicitação:

• Um caractere de espaço divide a URL na camada HTTP: o servidor recebe um parâmetro truncado ou malformado e geralmente retorna um erro 400 ou nenhum resultado.
• Um & dentro de um valor é interpretado como um separador de parâmetros, dividindo o valor em dois parâmetros separados.
• Outros caracteres que requerem 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.

Referenciar a string de consulta em uma atividade HTTP v2

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

O campo Caminho 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 forem compartilhados com outras atividades. Use uma substituição de URL completa quando o endpoint de destino estiver em um host diferente da Base URL, ou quando nenhuma Base URL de conexão estiver definida.

Verificar a integração

1. Implantar e executar a operação.

2. Abra o log da 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 no final do script de pré-operação:

   WriteToOperationLog("query_url: " & $query_url);
   

   A URL construída aparece na entrada do log da operação para a etapa do script. Remova a declaraçã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 foi aplicado a todos os valores que podem conter espaços ou caracteres especiais. Uma chamada URLEncode ausente em um valor que contém & ou = é uma fonte comum de falhas silenciosas.