Propiedades y Opciones de Consulta

<< Clic para mostrar Tabla de Contenidos >>

Navegación:  Bizagi Studio > Bizagi desde aplicaciones externas > API de Bizagi para aplicaciones externas > Servicios OData > Conceptos básicos >

Propiedades y Opciones de Consulta

Introducción

Bizagi ofrece servicios OData que manejan un conjunto extenso de recursos relacionados con el Diseño de Experiencia, como se mencione en API de Bizagi.

Para estos recursos se puede elegir agregar filtros o navegar la información obtenida con la respuesta basándonos en unas propiedades estándares y opciones de consulta.

 

Propiedades

Para todos los resultados que entregan los servicios de OData, la respuesta exitosa incluye un grupo de propiedades que son precedidas por el símbolo @.

Estas propiedades son:

 

PROPIEDAD

OCURRENCIA

DESCRIPCIÓN

EJEMPLO DE SU VALOR

@odata.context

Aparece una vez por invocación.

Contiene la URL que dirige a la metadata del servicio (en formato XML), que especifica el tipo de data y el campo que se está consultando.

[url_del_proyecto_bizagi]/odata/metadata/$metadata

@odata.count

Aparece una vez por invocación y aplica cuando se hace uso de Paginación de los resultados mientras se consulta un recurso que representa una colección.

Especifica la cantidad de registros obtenidos (un entero), mientras se usa $count=true en la URL.

50

@odata.id

Aparece para cada elemento de una colección.

Contiene la URL de cada elemento en caso de que se quiera navegar a su detalle.

[url_del_proyecto_bizagi]/odata/metadata/stakeholders(f83b2142-e0c2-4d70-8da6-f987f86ff38d)

@odata.nextLink

Aparece una vez por invocación y aplica cuando se hace uso de Paginación de los resultados.

Especifica la URL que se usaría en la siguiente invocación para que tenga en cuenta la "siguiente página" del mismo grupo de resultados (dado que hayan resultados siguientes que aplica para todas las páginas a excepción de la última).

[url_del_proyecto_bizagi]/odata/metadata/stakeholders(e6e38460-2f33-4804-bddf-46058843c314)/relevants?$skip=4&$top=3

@odata.totalCount

Aparece una vez por invocación y aplica cuando se hace uso de Paginación de los resultados.

Esta propiedad no pertenece al estándar, y especifica el número total de resultados del recurso (un entero) sin importar el número traído en la invocación actual (debido a la paginación).

100

 

Filtrar los resultados

Cuando se obtienen resultados múltiples dentro de una respuesta de invocación (p.ej. una colección de valores) por medio de una acción HTTP GET, puede hacer uso de la opción estándar (basada en especificaciones OData) $filter (parámetro de consulta URL), para lograr disminuir los resultados que desea de acuerdo a ciertos criterios.

 

Algunos de los operadores más comunes de las especificaciones OData son soportados por Bizagi y se describen en la taba a continuación:

 

TIPO

OPERADOR

DESCRIPCIÓN

Simple

eq

El operador igual a para comparar cadenas de texto y considerar una coincidencia exacta.

ne

El operador no es igual a para comparar cadenas de texto y considerar lo que no es una coincidencia exacta.

Simple con una notación basada en funciones

Contains

El operador contiene para considerar si una subcadena es contenida dentro de un valor de una cadena de texto.

Complejo

any

El operador cualquiera, para disminuir la información mientras se itera sobre una colección; teniendo en cuenta que un resultado válido son todos los registros que cumplen con el criterio.

all

El operador todos, para disminuir la información mientras se itera sobre una colección; teniendo en cuenta que un resultado válido es cualquiera de los registros que cumplen con el criterio.

 

Tenga en cuenta que toda la información en las respuestas son cadenas de texto (como tipo de dato), y por ello, los operadores y valores deben ir entre apóstrofes (caracteres ' ').

 

Filtrar con operadores simples

Para los operadores simples tales como and, or, eq, ne, puede hacer uso de $filter con la siguiente sintaxis básica:

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_campo] [operador] [valor]

 

Siendo:

[operador]: Puede usar eq / ne.

[valor]: El valor a comparar.

[recurso_campo]: El campo en particular dentro de la respuesta de invocación que contiene los resultados múltiples. Un ejemplo típico en Bizagi sería valores (values).

[servicio_odata]: El nombre del servicio OData que sería data o metadata.

[recurso_odata]: El recuso OData que se está consultando que retorna varios resultados dentro de la respuesta. Un ejemplo en Bizagi sería consultar stakeholders.

[url_del_proyecto_bizagi]: Corresponde a la URL donde los usuarios finales acceden al Portal de trabajo de Bizagi.

Por ejemplo, para proyectos de Bizagi en sus instalaciones, esta URL sería:

https://[su_servidor]/[su_proyecto]/

Mientras que para proyectos Bizagi PaaS, esta URL sería:

https://[ambiente_del_proyecto]-[su_proyecto]-[su_compañia].bizagi.com/

 

Cuando se encadena más de un filtro (usando 'and'/'or'), usted usaría $filter con la siguiente sintaxis (de manera similar puede agregar filtros adicionales):

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_campo] [operador_1] [valor_1] and [operador_2] [valor_2]

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_campo] [operador_1] [valor_1] or [operador_2] [valor_2]

 

Un ejemplo con un operador simple, sería filtrar el recurso casos (cases) al asegurarnos que un caso en específico es obtenido por su identificador:

.../cases?$filter=caseNumber eq '1169'

 

OData_Filter1

 

Otro ejemplo para usar un operador simple podría evaluar qué hay en la colección interna de información del caso.

Este ejemplo filtra los resultados para que traiga únicamente aquellos procesos que no consideran el parámetro del tipo XPath llamado 'Score' (Puntuación).

En otras palabras, aquellos procesos que no exigen que se envíe una puntuación para iniciar un caso nuevo:

.../processes?$filter=parameters/XPath ne 'Score'

 

OData_FilterNE

 

Finalmente, tenemos un ejemplo para encadenar más de un filtro usando and / or.

En este caso obtendremos todas las actividades que se encuentran a tiempo, es decir, con estado verde (green) o expiradas, con estado rojo (red), dejando por fuera aquellas en estado amarillo (yellow):

.../workitems?$filter=Contains(state, 'green') or Contains(state,'red')

 

OData_Filter3

 

Tenga en cuenta que el ejemplo anterior hace uso del operador Contains, el cual hace uso de una notación diferente que se asemeja a como se usaría la función en la mayoría de los lenguajes de programación.

 

Filtrando con operadores complejos

Para operadores complejos como any, all, puede usar  $filter con la siguiente sintaxis básica:

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_collección]/[operador_complejo](p:p/[atributo_colección] [operador_simple] [valor])

 

Siendo:

[operador_complejo]: Puede usar any  / all.

[operador_simple]: Puede usar eq / ne.

[valor]: El valor a comparar (usado por el operador_simple).

[recurso_collección]: La colección en particular dentro de los valores de respuesta de la invocación, que contiene varios resultados para iterear. Un ejemplo típico en Bizagi sería parámetros (parameters).

[servicio_odata]: El nombre del servicio OData que sería data o metadata.

[recurso_odata]: El recuso OData que se está consultando que retorna varios resultados dentro de la respuesta. Un ejemplo en Bizagi sería consultar stakeholders.

[url_del_proyecto_bizagi]: Corresponde a la URL donde los usuarios finales acceden al Portal de trabajo de Bizagi.

Por ejemplo, para proyectos de Bizagi en sus instalaciones, esta URL sería:

https://[su_servidor]/[su_proyecto]/

Mientras que para proyectos Bizagi PaaS, esta URL sería:

https://[ambiente_del_proyecto]-[su_proyecto]-[su_compañia].bizagi.com/

 

Nuestro primer ejemplo con el operador any, será para buscar procesos donde haya al menos un parámetro del tipo colección ('Collection'):

...processes?$filter=parameters/any(p: p/type eq 'Collection')

 

OData_FilterComplex

 

 

Similarmente, para encadenar más de un filtro (usando 'and'/'or') usted deberá usar $filter con la siguiente sintaxis (de manera similar puede agregar filtros adicionales):

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_collección]/[operador_complejo](p:p/[atributo_coleccion1] [operador_simple_1] [valor1]

and p/[atributo_coleccion2] [operador_simple_2] [valor2)

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_collección]/[operador_complejo](p:p/[atributo_coleccion1] [operador_simple_1] [valor1]

or p/[atributo_coleccion2] [operador_simple_2] [valor2])

 

Paginación de los resultados

Siempre que obtenga resultados por medio de una acción HTTP GET, puede confiar en el uso de los estándares de opciones de consulta $top y $skip para implementar la paginación, especialmente si el servicio retorna una gran cantidad de resultados.

Por lo tanto, para implementar una consulta que maneja paginación, use estos parámetros que se describen a continuación:

 

PARÁMETRO

DESCRIPCIÓN

EJEMPLO

$top

Sólo retorna un número fijo de los primeros resultados e ignora el resto.

Se utiliza de la manera $top=n donde n determina la cantidad de los primeros resultados a traer.

La siguiente invocación traerá los primeros 5 Stakeholder en un proyecto:

[url_del_proyecto_bizagi]/odata/metadata/stakeholders?$top=5

 

Más adelante mostramos un ejemplo más detallado.

$skip

Ignora una número de primeros resultados, para que los resultados obtenidos vayan de ese punto en adelante.

Se aplica de la manera $skip=n donde n determina el punto de inicio para traer los resultados.

la siguiente invocación traerá los Stakeholders a partir del sexto:

[url_del_proyecto_bizagi]/odata/metadata/stakeholders?$skip=5

 

Más adelante mostramos un ejemplo más detallado.

$count

Hace que el servicio incluya información sobre la cantidad de registros obtenidos.

Para usarlo se configura de la siguiente manera $count=true.

La siguiente invocación traerá solamente los primeros cinco Stakeholders en un proyecto, mientras se incluye la propiedad @odata.count con el número de resultados en esta invocación:

[url_del_proyecto_bizagi]/odata/metadata/stakeholders?$top=5&$count=true

 

Note que Bizagi automáticamente incluye en la respuesta las propiedades @odata.totalCount y @odata.nextLink.

El siguiente es el ejemplo de la respuesta que se tiene cuando se consulta en la URL en los ejemplos anteriores usando la paginación de los resultados:

{

 "@odata.context": "[url_del_proyecto_bizagi]/odata/metadata/$metadata#stakeholders",

 "@odata.totalCount": 16,

 "valor": [

   {

     "@odata.id": "[url_del_proyecto_bizagi]/odata/metadata/stakeholders(e6e38460-2f33-4804-bddf-46058843c314)",

     "id": "e6e38460-2f33-4804-bddf-46058843c314",

     "name": "Client",

     "displayName": "Client",

     "iconName": "bz-icon-ctg bz-icon-ctg-helicopter"

   }

 ],

 "@odata.nextLink": "[url_del_proyecto_bizagi]/odata/metadata/stakeholders?$top=1&$skip=1"

}

 

 

Ejemplo $top y $skip

Tenemos la siguiente URL que nos retorna una lista con n resultados

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]

 

Siendo:

[servicio_odata]:  El nombre del servicio OData, sea data o metadata.

[recurso_odata]: El nombre del recurso (URI) que está siendo consultado. Ejemplo: stuff, searches, relevants, processes, stakeholders.

[url_del_proyecto_bizagi]: Corresponde a la URL donde los usuarios finales acceden al Portal de trabajo de Bizagi.

Por ejemplo, para proyectos de Bizagi en sus instalaciones, esta URL sería:

https://[su_servidor]/[su_proyecto]/oauth2/server/token

Mientras que para proyectos Bizagi PaaS, esta URL sería:

https://[ambiente_del_proyecto]-[su_proyecto]-[su_compañia].bizagi.com/oauth2/server/token

 

Ahora, al agregar parámetros tales como $top y $skip, se puede manejar de una mejor manera una gran cantidad de resultados

Por ejemplo, mientras se hace uso de la URL especificada anteriormente, esta nueva invocación obtiene 50 resultados empezando por el resultado 1001:

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$top=50&$skip=1000

 

note_pin

Tenga en cuenta que como URLs y servicios estándar, los parámetros de consulta son agregados a la URL base seguidos por el símbolo ?  y múltiples parámetros son separados por medio del símbolo &.

 

Expansión de los resultados

Cuando obtenga resultados por medio de una acción HTTP GET, puede confiar en el uso de la opción estándar (según especificaciones OData) $expand (parámetro de consulta URL), para lograr extraer información adicional (de los recursos hijo) en la misma invocación.

Por lo tanto y para implementar una consulta que extrae tal información en la misma invocación, haga uso de los parámetros descritos a continuación:

 

Esto quiere decir, que usted puede usar $expand con la siguiente sintaxis:

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata_padre]?$expand=[recurso_odata_hijo]

 

Ejemplo $expand

Comencemos con la siguiente consulta que obtiene la información del Stakeholder.

 

OData_Expand0

 

Tomando como un ejemplo, la información del Stakeholder Doctor como se muesta en al figura anterior, se puede notar que los detalles que se encontraron para ese Stakeholder (consultado por ID) no incluye por defecto información de Mis Cosas del Doctor como se muestra a continuación:

 

OData_Expand1

 

Note que para la simplicidad del ejemplo, no resaltamos la información de contexto (contexts) dado que no es relevante.

 

Sabemos que podemos obtener la información de Mis Cosas, dado que es una recurso que se encuentra disponible ((/stuff)) atado a un stakeholder (en este caso el Doctor).

Observe que la colección Mis Cosas para el Doctor en este ejemplo consiste solamente en el equipo médico (medical equipment), como se muestra a continuación:

 

OData_Expand2

 

Ahora, podemos confiar en la opción $expand para traer la información de Mis cosas cuando consultamos la información del Stakeholder Doctor, como se realizó inicialmente.

Esto uniría los detalles del stakeholder junto con las colecciones de Mis Cosas en una sola respuesta:

 

OData_Expand3