Funciones y cláusulas de OData compatibles

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

En este artículo se explica cómo Analytics admite varias funciones de OData. También se enumeran las funciones no admitidas. OData (Open Data Protocol) es un estándar ISO/IEC aprobado, que define los procedimientos recomendados para compilar y consumir API REST. Para obtener más información, consulte la documentación de OData.

Nota:

El servicio Analytics se habilita automáticamente y se admite en producción para todos los servicios de Azure DevOps. La integración de Power BI y el acceso a la fuente OData del servicio Analytics están disponibles con carácter general. Le recomendamos que lo use y nos envíe sus comentarios. Los datos disponibles dependen de la versión. La versión más reciente admitida es v2.0y la versión preliminar más reciente es v4.0-preview. Para obtener más información, consulte Control de versiones de la API de OData.

Cláusulas admitidas

• $apply
• $compute
• $count
• $expand
• $filter
• $orderby
• $select
• $skip
• $top

Cuando se usan varias cláusulas en una consulta, se aplican en el orden especificado anteriormente. Se omite el orden de las cláusulas de la cadena de consulta. Por ejemplo, en la consulta siguiente, los elementos de trabajo se agrupan y agregan por primera vez. A continuación, se filtran los grupos. Después, los grupos filtrados se ordenan. Por último, se devuelven los cinco primeros registros. La consulta devuelve los cinco primeros tipos de elementos de trabajo usados al menos 100 veces.

WorkItems?$filter=Count ge 100&$apply=groupby((WorkItemType), aggregate($count as Count))&$orderby=Count&top=5

Compatibilidad con extensiones de agregación

Toma una secuencia de transformaciones de conjunto, separadas por barras diagonales para expresar que se aplican consecutivamente. El resultado de cada transformación es la entrada para la siguiente transformación. Por ejemplo, en la consulta siguiente, los elementos de trabajo se filtran y, a continuación, se agrupan por tipo de elemento de trabajo y estado. A continuación, los grupos se filtran y agrupan de nuevo.

Nota:

Las extensiones de agregación de OData son relativamente nuevas y aún no son totalmente compatibles con algunas herramientas de cliente.

Workitems?$apply=filter(State ne 'Closed')/groupby((WorkItemType, State), aggregate($count as Count))/filter(Count gt 100)/groupby((State),aggregate(Count with max as MaxCount))  

Se admiten las transformaciones siguientes:

Transformación	Notas
aggregate	Permite la agregación mediante uno de los métodos $countsiguientes, , averagemax, , , minsum
compute	Permite agregar propiedades calculadas
expand	Permite la expansión por propiedades especificadas
filter	Permite filtrar el conjunto de entrada. Admite las mismas expresiones que $filter
groupby	Permite la agrupación por propiedades

Para obtener más información, consulte Datos de seguimiento de trabajos agregados.

Funciones admitidas

Función canónica	Descripción
cast	Devuelve la expresión de la instancia actual que se convierte en el tipo especificado.
contains	Devuelve true si el segundo valor de cadena de parámetro es una subcadena del primer valor de cadena de parámetro; de lo contrario, devuelve false.
endswith	Devuelve true si el primer valor de cadena de parámetro termina con el segundo valor de cadena de parámetro; de lo contrario, devuelve false.
startswith	Devuelve true si el primer valor de cadena de parámetro comienza con el segundo valor de cadena de parámetro; de lo contrario, devuelve false.
length	Devuelve el número de caracteres del valor del parámetro.
indexof	Devuelve la posición de carácter de base cero de la primera aparición del segundo valor de parámetro en el primer valor del parámetro o -1 si el segundo valor del parámetro no se produce en el primer valor de parámetro.
substring	Devuelve una subcadena del primer valor de cadena de parámetro, empezando por el carácter N y terminando en el último carácter (donde N es el segundo valor entero del parámetro).
tolower	Devuelve el valor de cadena del parámetro de entrada con todos los caracteres en mayúsculas convertidos en minúsculas.
toupper	Devuelve el valor de cadena del parámetro de entrada con todos los caracteres en minúsculas convertidos en mayúsculas.
trim	Devuelve el valor de cadena del parámetro de entrada con todos los caracteres de espacio en blanco iniciales y finales.
year	Devuelve el componente year del valor del parámetro Date o DateTimeOffset.
month	Devuelve el componente month del valor del parámetro Date o DateTimeOffset.
day	Devuelve el componente day del valor del parámetro Date o DateTimeOffset.
date	Devuelve la parte de fecha del valor del parámetro DateTimeOffset.
time	Devuelve la parte de hora del valor del parámetro DateTimeOffset.
totaloffsetminutes	Devuelve el número de minutos firmado en la parte de desplazamiento de zona horaria del valor del parámetro DateTimeOffset.
now	Devuelve el punto actual de hora (fecha y hora con zona horaria) como un valor DateTimeOffset.
maxdatetime	Devuelve el último momento posible en el tiempo como un valor DateTimeOffset.
mindatetime	Devuelve el punto más antiguo posible en el tiempo como un valor DateTimeOffset.

Las funciones de OData se usan en una $filter cláusula , pero no en una $select cláusula de la manera en que se usarían en una instrucción SQL.

Por ejemplo, puede especificar:

/WorkItems?$filter=toupper(Title) eq 'HELP' 

Sin embargo, no puede escribir la cadena siguiente:

/WorkItems?$select=WorkItemId,State,toupper(Title)

Características no admitidas

• bottomcount
• bottomsum
• bottompercent
• $crossjoin
• concat
• countdistinct
• from
• isdefined
• $rollup
• $search
• topcount
• topsum
• toppercent

Artículos relacionados

• Consulta de los datos de seguimiento del trabajo
• Agregar datos
• Especificación de OData v4.0
• OData v4.0 Part 2: URL Conventions Plus Errata 02
• Extensión de agregación de OData v4.0