Como definir parâmetros de consulta

Aprenda os fundamentos do trabalho com parâmetros de consulta em suas HTTP Connector Functions de acordo com a documentação da API.

Os parâmetros de consulta permitem que você refine e adapte os resultados de uma Connector Function. Use os parâmetros para classificar, filtrar, definir limites, compensar um índice e muito mais. Este artigo usa os parâmetros da API da Tabela Tulip, mas outras APIs podem ter requisitos de parâmetros diferentes. Verifique a documentação para garantir que esteja usando a sintaxe e as especificações corretas.

Consulta com filtros

Os filtros podem ser muito úteis para extrair apenas os dados nos quais você está interessado. Às vezes, esses filtros podem ser um pouco complicados com sua sintaxe. A seguir, descrevemos como cada um deles é formado no exemplo de uma solicitação GET para registros, seguido de um exemplo completo.

Os nomes decampo para campos personalizados são sempre prefixados com um identificador de cadeia de cinco dígitos. Eles podem ser encontrados mais facilmente após uma solicitação GET all para verificar o nome verdadeiro do campo.

• Ex. "field"="maytq_scrap_count"

Os valoresde argumento geralmente são diretos. Se for um valor de texto, certifique-se de colocá-lo entre aspas.

• Ex. "arg":15

Corresponda ao tipo de função que você gostaria de usar.

• Ex. "functionType": "greaterThan"

Uma solicitação completa para isso pode se parecer com o seguinte:

https://brian.tulip.co/api/v3/tables/W2HPvyCZrjMMHTiip/records?limit=100&sortBy=\_sequenceNumber&sortDir=asc&filters=[{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"}]&filterAggregator=any

Como localizar parâmetros de consulta na documentação

Para localizar os parâmetros de consulta disponíveis para sua solicitação, navegue até a documentação da API. Se estiver usando a API de tabela da Tulip, você poderá encontrar a documentação em: your-instance.tulip.co/apiDocs.Selecione a solicitação que deseja usar e role para baixo até a guia Parameters (Parâmetros ).

Cada método individual tem seus próprios parâmetros definidos, mas nem todas as solicitações têm parâmetros associados. Certifique-se de observar previamente o que está disponível na documentação.

Sintaxe de parâmetros de consulta

A sintaxe dos parâmetros de consulta se baseia em um formato de cadeia de caracteres de consulta. Esse formato atribui valores a parâmetros especificados, sendo que a própria cadeia de consulta faz parte do URL.

No Connector Function Editor, clique em Add Parameter para criar um novo parâmetro de consulta.

Há duas partes em um parâmetro de consulta: uma chave e um valor. A chave é o nome do parâmetro e o valor é a informação que define o parâmetro para os resultados.

A sintaxe dos parâmetros de consulta usa Dot Notation, que especifica o tipo exato de parâmetro. Certifique-se de que o caso de escrita corresponda ao padrão de API do outro sistema.

Aplicar parâmetros comuns a funções de conector

Para definir um parâmetro em sua função de conector, primeiro identifique o parâmetro que deseja usar na documentação da API. Os parâmetros têm requisitos variados para cada um, portanto, vamos ver como eles se parecem.

:::(Info) (OBSERVAÇÃO) Para fins de continuidade, usaremos a mesma solicitação API Call em cada um dos exemplos abaixo. Essa é a solicitação GET que recupera uma lista de registros em uma tabela de tulipas por meio da API da tabela de tulipas. Outras APIs que você usa terão especificações diferentes para os parâmetros; não deixe de consultar os requisitos da documentação da API:

Limites

Os limites definem um limite designado para os resultados retornados. Observe que alguns limites têm configurações padrão, portanto, verifique a documentação da API para entender o valor inicial.

ExemploNãoqueremos obter mais de 70 registros quando a função de conector for executada. Felizmente, o valor padrão para o limite nessa solicitação é 10 e o mais alto é 100. A sintaxe do parâmetro de consulta deve ser parecida com a seguinte:

Filtros

Os filtros separam e refinam os resultados com base nas informações fornecidas pelo parâmetro.

Os filtros têm três partes, que você deve escrever em parâmetros individuais:

• Field (Campo) - o nome da coluna na tabela
• Function Type (Tipo de função) - o tipo de função de comparação
• Argumento - o valor com o qual comparar os resultados

Cada filtro tem 3 partes e cada filtro completo é um objeto. Usando a notação de pontos para escrever cada chave, especifique o tipo de parâmetro ('filter'), o número do filtro (0 a n) e a parte do filtro ('field', 'functionType' ou 'arg'). Deve haver um parâmetro para todas as três partes do filtro.

ExemploQueremosgarantir que os resultados da função de conector mostrem apenas valores de um campo específico (eubmc_value) que seja igual ao valor de entrada especificado (consumível) da função. Como esse é o nosso primeiro filtro nos parâmetros da função, o número do filtro é 0. Isso significa que todas as chaves desse filtro começarão com 'filter.0'. A sintaxe desse filtro deve ser parecida com a seguinte:

Classificação

A classificação dos resultados prioriza a exibição com base nas informações do parâmetro. Os resultados classificados determinam quais são incluídos nas agregações. Você pode ter várias funções de classificação, mas a ordem das opções determina a prioridade de classificação.

As funções de classificação têm duas partes:

• sortBy - o campo pelo qual você deseja classificar os resultados
• sortDir - a direção da classificação, seja ascendente (asc) ou descendente (desc)

Cada função de classificação tem 3 partes. Usando a notação de ponto para escrever cada chave, especifique o tipo de parâmetro ('sortOptions'), o número de classificação (0 a n) e o argumento de classificação ('sortBy' ou 'sortDir'). Deve haver um parâmetro para todas as três partes da função de classificação para que ela funcione.

ExemploQueremosque os resultados da função de conector sejam classificados pelo campo atualizado mais recentemente em uma ordem crescente. Como essa é nossa primeira função de classificação, o número de classificação é 0, o que significa que ambas as chaves dessa classificação começarão com 'sortOptions.0'. Para a chave sortBy, o valor é um valor especial ('_updatedAt') derivado da documentação da API para classificar os campos atualizados. A sintaxe desses parâmetros deve ser parecida com a seguinte:

Offsets

Os deslocamentos determinam o índice no qual o resultado retornado deve começar. Esse parâmetro é usado para paginação, não para a ordem dos registros, que é determinada pelos parâmetros de classificação. O valor do parâmetro deve ser um número inteiro maior ou igual a 0.

ExemploQueremosexibir somente os registros a partir da 5ª posição, para não vermos os 5 primeiros resultados. A sintaxe do parâmetro de consulta deve ser parecida com a seguinte:

Agregadores de filtros

Os agregadores de filtros determinam como os filtros nos parâmetros são combinados. Os dois valores a serem escolhidos são "any" e "all". O valor "all" significa que todos os filtros devem ter um registro para que o registro seja incluído nos resultados. O valor "any" significa que pelo menos um dos filtros deve corresponder a um registro para que ele seja incluído nos resultados. O valor padrão é "all" (todos), independentemente de você definir ou não o parâmetro.

ExemploTemosuma série de filtros nos parâmetros de consulta, mas só precisamos que um desses filtros seja verdadeiro para que os registros correspondam à nossa solicitação. A sintaxe do parâmetro de consulta deve ser parecida com a seguinte:

Vários filtros

Em alguns casos, você pode ter vários filtros para verificar na tabela. Nesse caso, você pode adicionar vários ao objeto filters. Isso pode ser parecido com o seguinte:

filters=[{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"},{"field": "maytq\_scrap\_reason", "arg": "scratch", "functionType": "equal"}]

Leitura adicional

• Uma visão geral dos conectores HTTP
• Como criar e configurar uma função de conector HTTP
• Como usar a API de tabela