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 >

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

 

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,

 "value": [

   {

     "@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 Cloud, 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 &.