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.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.

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.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.

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.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.

Requisitos previos

  • Para ver los datos de Analytics y consultar el servicio, debe ser miembro de un proyecto con acceso básico o superior. De forma predeterminada, a todos los miembros del proyecto se les conceden permisos para consultar Analytics y definir vistas de Analytics.
  • Para obtener información sobre otros requisitos previos relacionados con la habilitación de servicios y características y las actividades generales de seguimiento de datos, 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\InternetArea. 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, startswithy 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 comman.

$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

Pasos siguientes