Definición de consultas básicas mediante OData Analytics

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

Puede usar Analytics para Azure DevOps para construir consultas de OData para devolver datos que le interesen. Puede ejecutar estas consultas en el explorador o en software cliente como Excel o Power BI.

Este artículo se centra en las consultas para recuperar conjuntos de entidades de seguimiento de trabajos de Azure Boards, pero los principios se aplican a la consulta de otros conjuntos de entidades. Para más información, consulte Construcción de consultas de OData para análisis y referencia de metadatos para Azure Boards Analytics.

En este tutorial se muestra cómo:

Requisitos previos

Obtener un recuento de elementos

Para devolver solo un recuento de elementos o entidades definidos en una organización o proyecto sin incluir otra información, aplique la $apply=aggregate($count as Count) opción de consulta. Las consultas siguientes devuelven el número de proyectos, elementos de trabajo, rutas de acceso de área y usuarios de 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)

Las consultas anteriores devuelven resultados como el ejemplo siguiente para los proyectos de la fabrikam organización:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)",
  "value": [
    {
      "@odata.id": null,
      "Count": 16
    }
  ]
}

Obtener un recuento de elementos y sus datos

Para devolver un conteo de elementos junto con los datos seleccionados para los elementos, especifique la opción de consulta de $count=true en una instrucción select. Las consultas siguientes devuelven un recuento de elementos de trabajo, rutas de acceso 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, Proyecto y Usuario, referencia de metadatos para Azure DevOps Analytics.

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

Por ejemplo, la consulta siguiente solicita el recuento y los nombres de usuario de los usuarios en el proyecto Fabrikam Fiber :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

La consulta devuelve un recuento de 5 con sus nombres de usuario.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Users(UserName)",
  "@odata.count": 5,
  "value": [
    {
      "UserName": "Microsoft.VisualStudio.Services.TFS"
    },
    {
      "UserName": "fabrikamfiber1@hotmail.com"
    },
    {
      "UserName": "Jamal Hartnett"
    },
    {
      "UserName": "fabrikamfiber5@hotmail.com"
    },
    {
      "UserName": "fabrikamfiber2@hotmail.com"
    }
  ]
}

Seleccionar propiedades o campos específicos

Para devolver propiedades específicas o campos de elemento de trabajo, agregue una cláusula $select 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 cláusula a la $select=WorkItemId,WorkItemType,Title,State consulta.

La $select cláusula especifica los nombres de propiedad que corresponden a los campos con nombre. Los nombres de propiedad en las consultas de OData requieren atención tanto al espaciado como al uso de mayúsculas y minúsculas. Aunque los nombres para mostrar de propiedad como id. de elemento de trabajo pueden contener espacios, los nombres de propiedad formales no pueden contener espacios.

Para más información sobre los nombres de propiedad y las etiquetas, consulte Referencia de metadatos para Azure Boards. Para comprender cómo se etiquetan las propiedades de campo personalizadas, consulte Propiedades personalizadas.

En la consulta de ejemplo siguiente se solicitan los identificadores de elemento de trabajo, los títulos y los estados de los tres elementos de trabajo principales del proyecto Fabrikam Fiber.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

Analytics devuelve los datos siguientes.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)",
  "value": [
    {
      "WorkItemId": 31,
      "Title": "About screen",
      "WorkItemType": "Task",
      "State": "New"
    },
    {
      "WorkItemId": 30,
      "Title": "Change background color",
      "WorkItemType": "Task",
      "State": "Active"
    },
    {
      "WorkItemId": 32,
      "Title": "Standardize on form factors",
      "WorkItemType": "Task",
      "State": "Active"
    }
  ]
}

Filtrado de datos

Para filtrar un conjunto de entidades para devolver elementos específicos, agregue una $filter cláusula que especifique los criterios que deben cumplir los elementos. La siguiente cláusula de filtro devuelve solo los tipos de elementos de trabajo de característica que se encuentran en el estado En curso.

/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

La consulta de ejemplo siguiente especifica que se devuelva el identificador de elemento de trabajo, el tipo de elemento de trabajo, el títuloy el estado solo de los elementos de trabajo de características que se encuentran en el estado En curso .

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

Especificar varias cláusulas de filtro

Puede usar and y or especificar varios filtros en una sola $select cláusula. Por ejemplo, la consulta siguiente especifica varios campos de los elementos de trabajo de tipos User Story, Bug o custom type Backlog Work que se encuentran en los estados Nuevo, Confirmado o Activo . Use paréntesis para agrupar cláusulas de filtro según sea necesario.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

La consulta devuelve datos como los siguientes resultados:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,AssignedTo,State)",
  "value": [
    {
      "WorkItemId": 210,
      "Title": "Slow response on form",
      "State": "Active"
    },
    ...
    {
      "WorkItemId": 160,
      "Title": "Game store testing",
      "State": "New"
    }
  ]
}

También puede aplicar varias funciones, como contains, startswith, y endswith en las cláusulas $select. Consulte Funciones admitidas.

Propiedades del área de consulta o de la ruta de iteración

Para buscar las propiedades de AreaSK, IterationSK u otras propiedades de una ruta de acceso de área específica o ruta de acceso de iteración, use las siguientes consultas.

Devolver el AreaSK para una ruta específica de área

La consulta siguiente solicita la AreaSK propiedad definida para la ruta de acceso del Fabrikam Fiber\Production Planning\Web área. Para ver otras propiedades definidas para el conjunto de entidades Areas , consulte Áreas.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Production Planning\Web' &$select=AreaSK

La consulta devuelve los datos siguientes.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    }
  ]
}

Devolver el IterationSK para una ruta de iteración específica

La siguiente consulta devuelve la IterationSK propiedad definida para la Fabrikam Fiber\3Week Sprints\Sprint 3 camino de iteración. Para ver otras propiedades definidas para el conjunto de entidades iteraciones , consulte 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

Filtrar por propiedades de navegación

Las propiedades de navegación representan relaciones entre tipos de entidad. Al especificar una propiedad de navegación como parte de los criterios de filtro, debe especificar la ruta completa de la propiedad de navegación. Por ejemplo, la cláusula siguiente filtra los elementos de trabajo en función de una ruta de iteración especificada para la propiedad de navegación Iteration.

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Iteration es la propiedad de navegación y IterationPath es el campo de interés. Iteration/IterationPath es la ruta de acceso completa de la propiedad IterationPath.

En el siguiente ejemplo, la consulta solicita datos de los cinco elementos de trabajo principales bajo la ruta de acceso de iteración Fabrikam Fiber\3Week Sprints\Sprint 3, especificando la ruta completa para Iteration/IterationPath.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

Expandir datos de entidades relacionadas

La consulta de ejemplo anterior no devuelve Iteration datos, ya que Iteration es una entidad relacionada. Las propiedades de navegación como Identity, Area y Iteration no son accesibles directamente mediante el uso de instrucciones $select. Debe usar $expand declaraciones para retornar datos desde entidades relacionadas.

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 00000&$expand=Iteration

En el ejemplo siguiente se solicita información asociada al identificador 480de elemento de trabajo, incluidos los datos expandidos Iteration .

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

La consulta devuelve los siguientes datos, que incluye todos los campos de la propiedad expandida Iteration .

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        "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": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z"
      }
    }
  ]
}

Usar select en las instrucciones de expand

Si una propiedad expandida devuelve más datos de los que necesita, agregue una $select instrucción sobre la propiedad.

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 00000&$expand=Iteration($select=Name,IterationPath)

Por ejemplo, la consulta de ejemplo siguiente selecciona solo los datos de IterationName y de IterationPath de la propiedad expandida Iteration.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

La consulta devuelve los datos siguientes.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath))",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

En la tabla siguiente se muestra cómo usar las cláusulas $expand y $select para seleccionar varios campos de las propiedades de navegación. Por ejemplo, utiliza $expand=AssignedTo($select=UserName) para devolver la propiedad Assigned to del campo Nombre de Usuario en la propiedad de navegación Identity.

Puede especificar varias propiedades para expandirse en una sola $expand cláusula mediante una lista delimitada por comas.

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Utilizar declaraciones expand anidadas

Puede usar instrucciones OData $expand anidadas. Por ejemplo, la consulta siguiente usa instrucciones anidadas $expand para mostrar el proyecto en el que se encuentra una iteración.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

La consulta devuelve los datos siguientes:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        "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": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

Puede agregar $select instrucciones, por ejemplo, para devolver solo IterationName y IterationPath desde Iteration:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

Esta consulta devuelve los datos siguientes:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath,Project))",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

Los resultados solo muestran los IterationName y IterationPath de Iteration, y Project como un objeto anidado en los resultados de Iteration.

Consulta de un intervalo de fechas

La consulta de ejemplo siguiente devuelve elementos de trabajo cuya última fecha modificada es mayor o igual que el 1 de enero de 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

La consulta de ejemplo siguiente devuelve elementos de trabajo cuya última fecha modificada se produjo durante la semana del 31 de octubre al 7 de noviembre de 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z&ChangedDate le 2025-11-07Z

Ordenar resultados

Especifique la $orderby opción para ordenar los resultados o especificar la secuencia en la que se devolverán los resultados. Puede ordenar en orden ascendente o descendente mediante palabras clave asc o desc. En la tabla siguiente se proporcionan algunos ejemplos.

Paso siguiente

Contenido relacionado

• Construcción de consultas de OData para Analytics
• Referencia de metadatos para Azure Boards Analytics
• Procedimientos recomendados para usar al consultar Analytics
• Características de OData admitidas
• Especificación de OData v4.0
• OData v4.0 Part 2: URL Conventions Plus Errata 02