Expresiones de filtrado y clasificación

38 min

Esta página describe las expresiones de filtrado y ordenación en la Main API.

Expresiones de filtrado y ordenación

Este ejemplo describe la entidad player, pero la misma solución se implementa para todas las demás entidades (por ejemplo, grupos, feeds, playlists, etc.).

Ejemplo

La BSN.Cloud Main API actualmente expone los siguientes métodos de administración de player que aceptan expresiones opcionales de filtrado y ordenación:

GET ~/{{version}}/REST/Devices/[?marker={string}][&pageSize={byte}][&filter={expression}][&sort={expression}]

que recupera la lista paginada incluyendo hasta 100 instancias de 'Device' comenzando desde el marcador especificado, coincidiendo con la expresión de filtro especificada y ordenada de acuerdo con la expresión de ordenación especificada.

GET ~/{{version}}/REST/Devices/Regions/{*locationPath}/[?filter={expression}]

que recupera la lista de 'DevicesRegion' proporcionando la información agregada de ubicaciones de instancias de 'Device' que coinciden con la ruta de ubicación y la expresión de filtro especificadas.

GET ~/{{version}}/REST/Devices/Count/[?filter={expression}]

que recupera el número de instancias de 'Device' que coinciden con la expresión de filtro especificada.

PATCH ~/{{version}}/REST/Devices/[?filter={expression}]

(en desarrollo) que aplica los cambios especificados a las instancias de 'Device' que coinciden con la expresión de filtro especificada.

DELETE ~/{{version}}/REST/Devices/[?filter={expression}]

que elimina las instancias de 'Device' que coinciden con la expresión de filtro especificada.

Criterios de expresiones de filtro

Cada expresión de filtro puede contener uno o más criterios combinados mediante operadores AND/OR y opcionalmente agrupados mediante paréntesis.

Cada criterio puede basarse en el nombre de una propiedad, una etiqueta del sistema o una etiqueta personalizada.

Todos los nombres de propiedades se basan en el contrato de datos de la versión objetivo de la Main API

Etiquetas del sistema y personalizadas

Además de las propiedades, cada instancia de entidad 'Player' puede tener un conjunto diferente de etiquetas del sistema y personalizadas especificadas por el cliente, expuestas mediante la propiedad [Dictionary<string, object>] Etiquetas y administradas mediante los siguientes métodos de la BSN.Cloud Main API:

PUT ~/{version}/REST/Devices/{playerId:int}/

PUT ~/{version}/REST/Devices/{serial}/

PATCH ~/{version}/REST/Devices/{playerId:int}/

PATCH ~/{version}/REST/Devices/{serial}/

GET ~/{version}/REST/Devices/{playerId:int}/Tags/

GET ~/{version}/REST/Devices/{serial}/Tags/

POST ~/{version}/REST/Devices/{playerId:int}/Tags/

POST ~/{version}/REST/Devices/{serial}/Tags/

DELETE ~/{version}/REST/Devices/{playerId:int}/Tags/

DELETE ~/{version}/REST/Devices/{serial}/Tags/

Cada etiqueta del sistema y personalizada debe especificarse explícitamente para la instancia de entidad objetivo, pero la lista de etiquetas del sistema disponibles está predefinida por los propietarios del producto y asignada a algunas propiedades, por lo que sus valores siempre deben estar sincronizados. Por ejemplo, la etiqueta del sistema asignada a la propiedad Player Health Status se llama:

string::[Device].<HealthStatus>

Menciones de propiedades y etiquetas en expresiones

Las menciones de propiedades y etiquetas en expresiones son diferentes: las propiedades están envueltas entre corchetes y separadas por puntos, mientras que las etiquetas están envueltas entre signos de menor y mayor y opcionalmente pueden estar precedidas por el nombre de la entidad objetivo entre corchetes, y el tipo de datos está separado por doble punto como puede ver en el ejemplo anterior. Cada propiedad y etiqueta tiene un tipo de datos fuerte; para las propiedades y etiquetas del sistema, se define en el contrato de datos de una versión objetivo de la API y para las etiquetas personalizadas se resuelve ya sea a partir del nombre completamente calificado o del primer valor asignado. Además, existe una solicitud para admitir etiquetas personalizadas sin valores que actúen como etiquetas identificadoras. El tipo de datos define qué operadores y funciones son aplicables a una propiedad o etiqueta determinada en las condiciones.

Las propiedades y etiquetas del tipo de datos booleano normalmente admiten los siguientes operadores:

ES TRUE

ES FALSE

Las propiedades y etiquetas de tipos de datos numérico normalmente admiten los siguientes operadores:

ES {number}

NO ES {number}

ES MAYOR QUE {number}

ES MENOR QUE {number}

ESTÁ EN EL RANGO {number} Y {number}

NO ESTÁ EN EL RANGO {number} Y {number}

ESTÁ EN ({number}, {number}, ...)

NO ESTÁ EN ({number}, {number}, ...)

Las coordenadas GPS también admiten expresiones como:

GPS LOCATION ([Latitude] AND [Longitude]) IN ({latitude}, {longitude}, {distance})

GPS LOCATION ([Latitude] AND [Longitude]) NOT IN ({latitude}, {longitude}, {distance})

Las propiedades y etiquetas del tipo de datos cadena normalmente admiten los siguientes operadores:

ES NULL

NO ES NULL

ES '{expression}'

NO ES '{expression}'

COMIENZA CON '{string}'

TERMINA CON '{string}'

CONTIENE '{string}'

NO CONTIENE '{string}'

CONTIENE TODOS ('{string}', '{string}', ...)

CONTIENE CUALQUIERA ('{string}', '{string}', ...)

ESTÁ EN ('{string}', '{string}', ...)

NO ESTÁ EN ('{string}', '{string}', ...)

Las expresiones utilizadas en los operadores IS y IS NOT pueden incluir los comodines '*', '?', '[' + ']'.

Las propiedades y etiquetas del tipo de datos Fecha y hora (timestamp) normalmente admiten los siguientes operadores:

ES '{DateTime}'

NO ES '{DateTime}'

ES DESPUÉS DE '{DateTime}'

ES ANTES DE '{DateTime}'

EN LOS ÚLTIMOS ({interval}, {range}, '{DateTime}')

donde {interval} es uno de los valores de enumeración { "YEARS", "MONTHS", "DAYS" }

NO EN LOS ÚLTIMOS ({interval}, {range}, '{DateTime}')

donde {interval} es uno de los valores de enumeración { "YEARS", "MONTHS", "DAYS" }

ESTÁ EN EL RANGO '{DateTime}' Y '{DateTime}'

NO ESTÁ EN EL RANGO '{DateTime}' Y '{DateTime}'

ESTÁ EN ('{DateTime}', '{DateTime}')

NO ESTÁ EN ('{DateTime}', '{DateTime}')

El formato del valor '{DateTime}' debe seguir ISO 8601 y normalmente es como '2021-12-20T18:25:01.123Z'.

Las propiedades y etiquetas del tipo de datos Intervalo de tiempo (intervalo de tiempo) normalmente admiten los siguientes operadores:

ES '{TimeSpan}'

NO ES '{TimeSpan}'

ES MAYOR QUE '{TimeSpan}'

ES MENOR QUE '{TimeSpan}'

ESTÁ EN ('{TimeSpan}', '{TimeSpan}')

NO ESTÁ EN ('{TimeSpan}', '{TimeSpan}')

El formato del valor '{TimeSpan}' debe seguir ISO 8601 y normalmente es como '3.18:25:01'.

Las propiedades y etiquetas de los tipos de datos matriz numérica normalmente admiten los siguientes operadores:

ES NULL

NO ES NULL

CONTIENE TODOS ('{number}', '{number}', ...)

CONTIENE CUALQUIERA ('{number}', '{number}', ...)

Las propiedades y etiquetas del tipo de datos matriz de cadenas normalmente admiten los siguientes operadores:

ES NULL

NO ES NULL

CONTIENE TODOS ('{string}', '{string}', ...)

CONTIENE CUALQUIERA ('{string}', '{string}', ...)

Las propiedades y etiquetas del tipo de datos objeto normalmente admiten los siguientes operadores:

ES NULL

NO ES NULL

Las expresiones de ordenación solo pueden contener un nombre de propiedad completamente calificado o una etiqueta con el calificador opcional ASC/DESC, pero deberían admitir más en el futuro.