Cómo establecer parámetros de consulta

Aprende los fundamentos para trabajar con parámetros de consulta en tus Funciones de Conector HTTP de acuerdo con la documentación de la API.

Los parámetros de consulta te permiten refinar y adaptar los resultados de una función de conector. Utiliza los parámetros para ordenar, filtrar, establecer límites, compensar un índice, etc. En este artículo se utilizan los parámetros de la API de Tulip Table, pero otras API pueden tener requisitos de parámetros diferentes. Asegúrate de consultar la documentación para comprobar que estás utilizando la sintaxis y las especificaciones correctas.

Consultas con filtros

Los filtros pueden ser muy útiles para extraer sólo los datos que le interesan. Estos filtros a veces pueden ser un poco complicados con su sintaxis. A continuación se describe cómo se forma cada uno en el ejemplo de una solicitud GET de registros, seguido de un ejemplo completo.

Losnombres de los campos personalizados siempre van precedidos de un identificador de cadena de cinco dígitos. Estos se pueden encontrar más fácilmente después de una solicitud GET all para comprobar el verdadero nombre del campo.

• Ej. "field"="maytq_scrap_count".

Los valores delos argumentos suelen ser sencillos. Si se trata de un valor de texto, asegúrese de ponerlo entre comillas.

• Ej. "arg":15

Haga coincidir el tipo de función que desea utilizar.

• Ej. "functionType": "mayorQue"

Una solicitud completa podría tener este aspecto:

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

Cómo encontrar parámetros de consulta en la documentación

Para localizar los parámetros de consulta disponibles para su solicitud, navegue hasta la documentación de la API. Si estás utilizando la API de Tulip Table, puedes encontrar la documentación en: your-instance.tulip.co/apiDocs. Selecciona la petición que deseas utilizar y desplázate hacia abajo hasta la pestaña Parámetros.

Cada método individual tiene su propio conjunto de parámetros, sin embargo, no todas las solicitudes tienen parámetros asociados. Asegúrate de anotar lo que está disponible en la documentación de antemano.

Sintaxis de los parámetros de consulta

La sintaxis de los parámetros de consulta se basa en un formato de cadena de consulta. Este formato asigna valores a los parámetros especificados, siendo la propia cadena de consulta parte de la URL.

En el Editor de funciones del conector, haz clic en Añadir parámetro para crear un nuevo parámetro de consulta.

Hay dos partes en un parámetro de consulta: una clave y un valor. La clave es el nombre del parámetro y el valor es la información que establece el parámetro para los resultados.

La sintaxis de los parámetros de consulta utiliza Dot Notation, que especifica el tipo exacto de parámetro. Asegúrese de que la escritura coincide con el estándar API del otro sistema.

Aplicar parámetros comunes a funciones de conector

Para establecer un parámetro en su función de conector, identifique primero el parámetro que desea utilizar en la documentación de la API. Los parámetros tienen distintos requisitos para cada uno, así que repasemos cómo son.

:::(Info) (NOTA) A efectos de continuidad, utilizaremos la misma solicitud API Call en cada uno de los ejemplos siguientes. Esta es la solicitud GET que recupera una lista de registros en una tabla tulipán a través de la API de tabla tulipán. Otras API que utilices tendrán especificaciones diferentes para los parámetros, asegúrate de mirar los requisitos de la documentación de la API. :::

Límites

Los límites establecen un tope designado para los resultados devueltos. Tenga en cuenta que algunos límites tienen valores predeterminados, así que asegúrese de consultar la documentación de la API para conocer el valor inicial.

EjemploQueremos obtener no más de 70 registros cuando se ejecute la función de conector. Por suerte, el valor por defecto para el límite en esta petición es 10 y el más alto es 100. La sintaxis del parámetro de consulta debería ser como la siguiente:

Filtros

Los filtros separan y refinan los resultados basándose en la información dada en el parámetro.

Los filtros tienen tres partes, que debe escribir en parámetros individuales:

• Campo - el nombre de la columna en la tabla
• Tipo de función - el tipo de función de comparación
• Argumento - el valor con el que se compararán los resultados

Cada filtro tiene 3 partes y cada filtro completo es un Objeto. Utilizando la notación de puntos para escribir cada clave, especifique el tipo de parámetro ('filtro'), el número de filtro (de 0 a n) y la parte del filtro ('campo', 'tipo de función' o 'arg'). Debe haber un parámetro para las tres partes del filtro.

EjemploQueremos asegurarnos de que los resultados de la función de conector muestren sólo valores de un campo específico (eubmc_value) que sea igual al valor de entrada especificado (consumable) de la función. Dado que éste es nuestro primer filtro en los parámetros de la función, el número de filtro es 0. Esto significa que todas las claves de este filtro empezarán por 'filtro.0'. La sintaxis de este filtro debería ser como la siguiente:

Ordenación

Ordenar resultados prioriza la vista en función de la información del parámetro. Los resultados ordenados determinan cuáles se incluyen en las agregaciones. Puede tener múltiples funciones de ordenación, sin embargo el orden de las opciones determina la prioridad de ordenación.

Las funciones de ordenación tienen dos partes

• sortBy - el campo por el que desea ordenar los resultados
• sortDir - la dirección de la ordenación, ascendente (asc) o descendente (desc)

Cada función de ordenación consta de 3 partes. Utilizando la notación de puntos para escribir cada clave, especifique el tipo de parámetro ('sortOptions'), el número de ordenación (de 0 a n) y el argumento de ordenación ('sortBy' o 'sortDir'). Debe haber un parámetro para las tres partes de la función de ordenación para que funcione.

EjemploQueremos que los resultados de la función conector se ordenen por el campo actualizado más recientemente en orden ascendente. Debido a que esta es nuestra primera función de ordenación, el número de ordenación es 0. Esto significa que ambas claves para esta ordenación comenzarán con 'sortOptions.0'. Para la clave sortBy, el valor es un valor especial ('_updatedAt') derivado de la documentación de la API para ordenar por campos actualizados. La sintaxis de estos parámetros debería ser la siguiente:

Desplazamientos

Los desplazamientos determinan el índice en el que comienza el resultado devuelto. Este parámetro se utiliza para la paginación, no para el orden de los registros, que viene determinado por los parámetros de ordenación. El valor del parámetro debe ser un número entero mayor o igual que 0.

EjemploQueremos ver sólo los registros a partir de la 5ª posición, para no ver los 5 primeros resultados. La sintaxis del parámetro de consulta debe ser como la siguiente:

Agregadores de filtros

Los agregadores de filtros determinan cómo se combinan los filtros en los parámetros. Los dos valores a elegir son 'any' y 'all'. El valor "todos" significa que todos los filtros deben tener un registro para que éste se incluya en los resultados. El valor "cualquiera" significa que al menos uno de los filtros debe coincidir con un registro para que se incluya en los resultados. El valor por defecto es "todos", independientemente de que se haya configurado o no el parámetro.

EjemploTenemos una serie de filtros en los parámetros de consulta, pero sólo necesitamos que uno de ellos sea verdadero para que los registros coincidan con nuestra petición. La sintaxis del parámetro de consulta debería ser la siguiente:

Filtros múltiples

En algunos casos, puede que tenga varios filtros que comprobar en la tabla. En este caso, puede añadir múltiples al objeto filters. Esto podría ser algo como esto

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

Más información

• Visión general de los conectores HTTP
• Cómo crear y configurar una función de conector HTTP
• Cómo utilizar la API de tablas