Definición de consultas básicas mediante OData Analytics
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019
Con Analytics para Azure DevOps, puede construir consultas básicas y filtradas para devolver datos de interés. Puede ejecutar estas consultas directamente en el explorador o en Power BI.
En este artículo se crea información proporcionada en Construcción de consultas de OData para análisis y referencia de metadatos para Azure Boards Analytics. Además, las consultas de este artículo se centran en recuperar conjuntos de entidades de seguimiento de trabajo; sin embargo, los principios se aplican para consultar otros conjuntos de entidades.
En este artículo aprenderá a definir consultas que devuelven los datos siguientes:
- Recuento de elementos (sin otros datos)
- Recuento de elementos y datos
- Propiedades definidas para áreas o rutas de acceso de iteración
- Columnas o campos seleccionados
- Datos filtrados
- Devolver datos para los campos Identidad, Ruta de acceso de área e Ruta de acceso de iteración
- Filtrar por una propiedad de navegación
- Consulta de un intervalo de fechas
- Anidar instrucciones expand
- Ordenar resultados, opción orderby
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.0
y 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.
Nota:
El servicio Analytics se instala y admite automáticamente en producción para todas las colecciones de proyectos nuevas para Azure DevOps Server 2020 y versiones posteriores. 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. Si ha actualizado desde Azure DevOps Server 2019, puede instalar el servicio Analytics durante la actualización.
Los datos disponibles dependen de la versión. La versión más reciente admitida es v2.0
y 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.
Nota:
El servicio Analytics está en versión preliminar para Azure DevOps Server 2019. Puede habilitarlo o instalarlo para una colección de proyectos. La integración y el acceso de Power BI a la fuente OData del servicio Analytics se encuentran en versión preliminar. 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.0
y 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.
Requisitos previos
- Access: sea miembro de un proyecto con al menos acceso básico .
- Permisos: de forma predeterminada, los miembros del proyecto tienen permiso para consultar Analytics y crear vistas.
- Para obtener más información sobre otros requisitos previos relacionados con las actividades de habilitación de servicios y características y seguimiento de datos generales, consulte Permisos y requisitos previos para acceder a Analytics.
Nota:
En este artículo, la dirección URL de consulta de OData se define para Azure DevOps Services. Para construir una consulta similar para un servidor local, consulte las instrucciones proporcionadas en Construcción de consultas de OData para Analytics. Le recomendamos que ajuste las consultas proporcionadas para su organización y proyecto para familiarizarse con la consulta de OData mediante el explorador.
Devolver un recuento de elementos (ningún otro dato)
Para obtener información sobre el número de elementos o entidades definidos en una organización o proyecto, especifique $apply=aggregate($count as Count)
la opción de consulta. Por ejemplo, las siguientes consultas devuelven el número de proyectos, elementos de trabajo, rutas de acceso de área y usuarios definidos para una organización.
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)
Sugerencia
Se produce un error en las consultas entre proyectos cuando el usuario que ejecuta la consulta no tiene acceso a todos los proyectos. Obtenga más información sobre los requisitos en Consultas con ámbito de proyecto y organización.
Recuento de proyectos
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value
0
@odata.id null
Count 28
Recuento de elementos de trabajo
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value
0
@odata.id null
Count 1166
Recuento de áreas
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 70
Número de usuarios
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 16
Devolver un recuento de elementos y datos
Para devolver un recuento de elementos junto con los datos seleccionados para los elementos, especifique la $count=true
opción de consulta. Por ejemplo, las siguientes consultas devuelven un recuento de elementos de trabajo, rutas de área y usuarios definidos para un proyecto junto con las propiedades especificadas. Para obtener propiedades válidas, consulte Referencia de metadatos para Azure Boards Analytics y fecha de calendario, Project y Referencia de metadatos de usuario para Azure DevOps Analytics.
Sugerencia
Si no especifica las propiedades que se van a devolver, Analytics devolverá todas las propiedades definidas para el tipo de entidad especificado.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail
Propiedades de áreas o iteraciones
Para buscar la AreaSK
propiedad o IterationSK
, u otra propiedad de una ruta de acceso de área o ruta de acceso de iteración, use las siguientes consultas.
Devolver el AreaSK para una ruta de acceso de área específica
La consulta siguiente especifica que se devuelva la AreaSK
propiedad definida para la ruta de acceso fabrikam Fiber\Service Delivery\Internet Area. Para especificar otras propiedades definidas para el Areas
conjunto de entidades, consulte Referencia de metadatos para Azure Boards Analytics, Áreas.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK
La consulta devuelve los datos siguientes.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
"value": [
{
"AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
}
]
}
Devolver iteraciónSK para una ruta de acceso de iteración específica
La consulta siguiente especifica que se devuelva la IterationSK
propiedad definida para la ruta de acceso de iteración Fabrikam Fiber\Release 1\Sprint 3. Para especificar otras propiedades definidas para el Iterations
conjunto de entidades, consulte Referencia de metadatos para Azure Boards Analytics, Iteraciones.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK
La consulta devuelve los datos siguientes.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
"value": [
{
"IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
}
]
}
Devolver propiedades o campos específicos
Para devolver propiedades específicas o campos de elemento de trabajo, agregue una $select
cláusula que especifique los nombres de propiedad.
Por ejemplo, para devolver el identificador de elemento de trabajo, el tipo de elemento de trabajo, el título y el estado de los elementos de trabajo, agregue la siguiente cláusula a la consulta. Esta cláusula especifica las propiedades que corresponden a los campos con nombre.
Nota:
Los nombres de propiedad no contienen ningún espacio. Se producirá un error en la consulta si agrega espacios. Las consultas de OData requieren atención tanto al espaciado como al uso de mayúsculas y minúsculas. Para comprender cómo se etiquetan las propiedades de campo personalizadas, consulte Referencia de metadatos para Azure Boards, Propiedades personalizadas.
Aquí se especifica para devolver los tres elementos de trabajo principales.
https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3
Analytics devuelve los datos siguientes.
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value
0
WorkItemId 462
Title "Test case"
WorkItemType "Test Case"
State "Design"
1
WorkItemId 491
Title "Change color settings"
WorkItemType "Shared Steps"
State "Active"
2
WorkItemId 461
Title "Test impediment"
WorkItemType "Impediment"
State "Open"
.
Filtrado de los datos
Para filtrar un conjunto de entidades para devolver elementos seleccionados, especifique una $filter
cláusula que especifique los criterios que deben cumplir los elementos. Basándonos en la última consulta, aquí se agrega una cláusula filter para devolver solo los tipos de elementos de trabajo de características que se encuentran en el estado En curso .
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'
https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'&$select=WorkItemId,Title,AssignedTo,State
Analytics devuelve los datos siguientes.
@odata.context "https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value
0
WorkItemId 380
Title "Refresh web look, feel, performance factors"
State "In Progress"
1
WorkItemId 480
Title "Customer Phone - Phase 1"
State "In Progress"
2
WorkItemId 493
Title "Change initial view"
State "In Progress"
3
WorkItemId 479
Title "Customer Web - Phase 1"
State "In Progress"
4
WorkItemId 551
Title "Mobile feedback"
State "In Progress"
Especificar varias cláusulas de filtro
Puede usar AND
y OR
especificar varias cláusulas de filtro.
Por ejemplo, la siguiente consulta especifica que se devuelvan elementos de trabajo de tipo Caso de usuario, Error y Trabajo pendiente (un tipo de elemento de trabajo personalizado) que se encuentran en los estados Nuevo, Confirmado o Activo . Use paréntesis para agrupar cláusulas de filtro según sea necesario.
Además, puede aplicar varias funciones como contains
, startswith
y endswith
mucho más. Consulte las cláusulas y características de OData compatibles, Funciones admitidas.
Devolver datos para los campos Identidad, Ruta de acceso de área e Ruta de acceso de iteración
Las propiedades select están asociadas a las propiedades de navegación y no son accesibles directamente mediante la $select
instrucción . Debe usar una $expand
instrucción para devolver los datos de interés. Estas propiedades suelen estar asociadas a varias propiedades propias. Por ejemplo, con campos Identidad, puede especificar para devolver el nombre de usuario o el correo electrónico del usuario.
En la tabla siguiente se proporcionan ejemplos de cómo expandir varias de estas propiedades.
Campos de tipo | Propiedad a la que se hace referencia | Cláusulas de ejemplo que se van a incluir |
---|---|---|
DateTime | DateSK |
$expand=CreatedDate($select=Date) o$expand=CreatedDate($select=WeekStartingDate) |
Identidad | UserSK |
$expand=AssignedTo($select=UserName) o$expand=AssignedTo($select=UserEmail) |
Área | AreaSK |
$expand=Area($select=AreaName) o$expand=Area($select=AreaPath) |
Iteración | IterationSK |
$expand=Iteration($select=IterationName) o$expand=Iteration($select=IterationPath) o$expand=Iteration($select=StartDate) |
Proyecto | ProjectSK |
$expand=Project($select=ProjectName) |
Team | TeamSK |
$expand=Teams($select=TeamName) |
Para especificar varias propiedades que deben expandirse, debe especificarlas en una sola cláusula expand dentro de una lista delimitada por comas.
$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)
Filtrar por una propiedad de navegación
Al especificar una propiedad de navegación como parte de los criterios de filtro, debe especificarla en el formato necesario.
Por ejemplo, la cláusula siguiente especifica filtrar los elementos de trabajo en función de la iteración 1 definida para el proyecto.
/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
En este ejemplo, Iteration
es el nombre de la propiedad de navegación y IterationPath
corresponde a la ruta de acceso completa de la iteración. Para usar otra entidad como filtro, coloque la propiedad de navegación seguida de una barra diagonal seguida del nombre del campo en el que filtrar.
Y esta es la consulta completa de OData:
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
Este es otro ejemplo en el que se devuelven los cinco elementos de trabajo principales en fabrikam Fiber\Service Delivery\Voice Area Path.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value
0
WorkItemId 361
Title "Hello World Web Site"
WorkItemType "Product Backlog Item"
State "Removed"
1
WorkItemId 362
Title "Resume"
WorkItemType "Product Backlog Item"
State "New"
2
WorkItemId 363
Title "Welcome back page"
WorkItemType "Product Backlog Item"
State "Done"
3
WorkItemId 365
Title "Pause"
WorkItemType "Feature"
State "New"
4
WorkItemId 374
Title "Fix performance issues"
WorkItemType "Task"
State "To Do"
Sugerencia
No se puede usar la propiedad de navegación directamente en una $select
instrucción . En su lugar, debe usar $expand
.
El ejemplo de filtrado anterior para la ruta de acceso de iteración no devuelve la ruta de acceso de iteración porque está contenida en una entidad relacionada. Para devolver datos en una entidad relacionada, agregue una $expand
instrucción :
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration
Y este es un ejemplo que devuelve información asignada al identificador de elemento de trabajo 480.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value
0
WorkItemId 480
Title "Customer Phone - Phase 1"
WorkItemType "Feature"
State "In Progress"
Iteration
ProjectSK "56af920d-393b-4236-9a07-24439ccaa85c"
IterationSK "c7063041-ff3a-4d7f-bb46-c433c7030d59"
IterationId "c7063041-ff3a-4d7f-bb46-c433c7030d59"
IterationName "Sprint 1"
Number 55297
IterationPath "Fabrikam Fiber\\Release 1\\Sprint 1"
StartDate "2022-01-17T00:00:00-08:00"
EndDate "2022-02-04T23:59:59.999-08:00"
IterationLevel1 "Fabrikam Fiber"
IterationLevel2 "Release 1"
IterationLevel3 "Sprint 1"
IterationLevel4 null
IterationLevel5 null
IterationLevel6 null
IterationLevel7 null
IterationLevel8 null
IterationLevel9 null
IterationLevel10 null
IterationLevel11 null
IterationLevel12 null
IterationLevel13 null
IterationLevel14 null
Depth 2
IsEnded true
AnalyticsUpdatedDate "2022-01-18T22:18:58.17Z"
Como puede ver, la ruta de acceso de iteración se expande en el resultado y se devuelven todos los datos de iteración. Probablemente sea más datos de los que quiere.
Para devolver menos datos, agregue una $select
instrucción a la iteración también:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)
A continuación, devuelve los siguientes datos.
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
"value":[
{
"WorkItemId":10000,
"WorkItemType":"Task",
"Title":"Some title",
"State":"Completed",
"Iteration":{
"Name":"Sprint 55",
"IterationPath":"Fabrikam\\Sprints\\Sprint 55"
}
}
]
}
Consulta de un intervalo de fechas
En el ejemplo siguiente se devuelven elementos de trabajo cuya fecha modificada es mayor que el 1 de enero de 2021.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z
En el ejemplo siguiente se devuelven elementos de trabajo cuya fecha modificada se produce durante la semana del 26 de abril al 30 de abril de 2021.
https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z
Anidar instrucciones expand
En OData, puede anidar $expand
instrucciones. Por ejemplo, puede escribir la instrucción de consulta anterior para mostrar el proyecto del que forma parte la iteración:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)
Devuelve el siguiente json:
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
"value":[
{
"WorkItemId":10000,
"Revision":3,
"Watermark":283397,
"Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
"WorkItemType":"Task",
"ChangedDate":"2014-07-10T19:29:58.41Z",
"CreatedDate":"2014-04-19T22:44:58.31Z",
"State":"Completed",
"Reason":"Completed",
"Priority":2,
"CompletedWork":10.0,
"OriginalEstimate":20.0,
"Count":1,
"Iteration":{
"IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
"Name":"Sprint 55",
"Number":13021,
"IterationPath":"Fabrikam\\Sprints\\Sprint 55",
"StartDate":"2013-09-23T00:00:00Z",
"EndDate":"2013-10-11T00:00:00Z",
"IterationLevel1":"Fabrikam",
"IterationLevel2":" Sprints",
"IterationLevel3":"Sprint 55",
"Level":2,
"IsDeleted":false,
"Project":{
"ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
"ProjectName":"Fabrikam",
"IsDeleted":false
}
}
}
]
}
También puede combinar $expand
instrucciones y $select
. Por ejemplo, puede cambiar la consulta anterior para devolver solo el nombre de iteración y la ruta de acceso de iteración:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)
Devuelve el siguiente json:
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
"value":[
{
"WorkItemId":10000,
"Revision":3,
"Watermark":283397,
"Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
"ChangedDate":"2014-07-10T19:29:58.41Z",
"CreatedDate":"2014-04-19T22:44:58.31Z",
"State":"Completed",
"Reason":"Completed",
"Priority":2,
"CompletedWork":10.0,
"OriginalEstimate":20.0,
"Count":1,
"Iteration":{
"IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
"Project":{
"ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
"ProjectName":"Fabrikam",
"IsDeleted":false
}
}
}
]
}
Observe que el resultado aquí muestra solo el IterationId y IterationPath y que Project es un objeto anidado dentro del resultado JSON. Otro elemento clave que se debe tener en cuenta es la propia dirección URL. Al usar una $select
instrucción y una $expand
cláusula , debe usar un punto y coma (;) antes de $expand
. Cualquier otra cosa producirá un error.
Ordenar resultados, orderby
opción
Especifique la $orderby
opción para ordenar los resultados o especificar la secuencia en la que se devuelven los resultados. Puede ordenar en orden ascendente o descendente mediante palabras clave asc
o desc
, respectivamente. Se muestran algunos ejemplos
Sort by | Cláusula que se va a incluir |
---|---|
Id. de elemento de trabajo | /WorkItems?$orderby=WorkItemId |
Id. de elemento de trabajo descendente | /WorkItems?$orderby=WorkItemId desc |
Tipo de elemento de trabajo y Estado | /WorkItems?$orderby=WorkItemType,State |