Consulta de los datos de seguimiento de trabajo mediante OData Analytics

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019

Con Analytics para Azure DevOps, puede construir consultas básicas y filtradas para devolver elementos de trabajo de interés. Puede ejecutar estas consultas directamente en el explorador.

En este artículo, el ámbito de la dirección URL raíz base es un proyecto, como se muestra a continuación:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}

https://{ServerName}:{Port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}

Todas las demás partes de la dirección URL se especifican como una parte adicional de la cadena de consulta.

Requisitos previos

Construcción de una consulta básica

Consulta de un único conjunto de entidades

Para consultar un único conjunto de entidades, como Elementos de trabajo o Áreas o Proyectos, agregue el nombre de la entidad: /Areas/Projects , o /WorkItems . Para obtener una lista completa de conjuntos de entidades, consulte Modelo de datos para Analytics.

Por ejemplo, puede consultar Áreas agregando /Areas . La dirección URL completa es:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/Areas 

Es equivalente a realizar una instrucción select en el conjunto de entidades y devolver todo, todas las columnas y todas las filas. Si tiene un gran número de elementos de trabajo, puede tardar varios segundos. Si tiene más de 10 000 elementos de trabajo, se aplicará la paginación del lado servidor.

Seleccionar columnas o campos específicos

Devuelva datos de campo específicos agregando una $select cláusula .

Por ejemplo, para devolver solo el identificador de elemento de trabajo, el tipo de elemento de trabajo, el título y el estado de los elementos de trabajo, agregue esta cláusula a la consulta:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State

Es equivalente a seleccionar todas las filas de la entidad, pero devolver solo estos campos específicos.

Filtrado de los datos

Puede filtrar los datos proporcionando una cláusula de filtro de consulta. A raíz de la última consulta, agregaría la siguiente cláusula de filtro para devolver solo esos elementos de trabajo para devolver el estado "En curso".

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

Con la consulta completa de OData:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

En su lugar, puede excluir la $select cláusula por completo y filtrar los resultados de la manera siguiente:

/WorkItems?$filter=State eq 'In Progress'

Con la consulta completa de OData:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=State eq 'In Progress'

También puede aplicar varios filtros concatenando dos o más filtros. En este caso, se filtran por tareas en curso:

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

Con la consulta completa de OData:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=WorkItemType eq 'Task' and State eq 'In Progress'

Además, puede aplicar varias funciones, como containsstartswith , y mucho endswith más. Consulte las cláusulas y características admitidas de OData, Funciones admitidas.

Consultas de intervalo de fechas

En el ejemplo siguiente se devuelven elementos de trabajo cuya fecha de cambio es mayor que igual 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 de cambio 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

Filtrado mediante entidades relacionadas

Consultar elementos de trabajo es útil, pero al final querrá filtrar por otros datos, como la ruta de iteración, la ruta de acceso del área o el proyecto. Para ello, debe comprender las propiedades de navegación del modelo de entidad. Puede obtener metadatos mediante la /$metadata dirección URL. Para más información, consulte Exploración de metadatos de OData de Analytics.

Esta es una vista parcial de los metadatos de la entidad Elementos de trabajo:

    <Property ...>
    <Property Name="RequirementType" Type="Edm.String"/>
    <Property Name="RequiresReview" Type="Edm.String"/>
    <Property Name="RequiresTest" Type="Edm.String"/>
    <Property Name="RootCause" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert1" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert2" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert3" Type="Edm.String"/>
    <Property Name="TargetResolveDate" Type="Edm.DateTimeOffset"/>
    <Property Name="TaskType" Type="Edm.String"/>
    <Property Name="UserAcceptanceTest" Type="Edm.String"/>
    <Property Name="Count" Nullable="false" Type="Edm.Int32"/>
    <NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
    <NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
    <NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project"/>
    <NavigationProperty Name="Area" Type="Microsoft.VisualStudio.Services.Analytics.Model.Area"/>
    <NavigationProperty Name="Iteration" Type="Microsoft.VisualStudio.Services.Analytics.Model.Iteration"/>

Las propiedades de navegación aparecen hacia la parte inferior de los metadatos, que incluye Revisions , BoardLocations (metadatos kanban), Project , y AreaIteration .

Filtrar por una propiedad de navegación

¿Cómo se usan las propiedades de navegación para filtrar los resultados?

Use la cláusula siguiente para filtrar elementos de trabajo en función de una iteración específica, por ejemplo Iteración 1:

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

Con la consulta completa de OData:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

En este ejemplo, Iteration es el nombre de la propiedad de navegación y corresponde a la ruta de acceso completa de la IterationPath iteración. Para usar otra entidad como filtro, coloque la propiedad de navegación seguida de una barra diagonal seguida del nombre del campo por el que se va a filtrar.

Devolver datos de entidades relacionadas

¿Cómo se usan las propiedades de navegación para seleccionar campos relacionados?

El nombre de usuario de los campos personalizados basados en una identidad no es accesible directamente mediante una $select instrucción . La consulta siguiente usa una $expand instrucción para recuperar el nombre de usuario:

/WorkItems?$expand=MyIdentityField($select=UserName)

El ejemplo de filtrado anterior para la ruta de acceso de iteración no devuelve la ruta de acceso de iteración en los resultados 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

Devuelve el siguiente JSON:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "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
      }
    }
  ]
}

Como puede ver, la ruta de acceso de iteración se expande en el resultado JSON y se devuelven todos los datos de iteración. Probablemente son más datos de los que desea.

Para devolver menos datos, agregue también $select una instrucción en la iteración:

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

Devuelve el siguiente JSON:

{
  "@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"
      }
    }
  ]
}

En OData, puede $expand anidar 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 $select y . 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 iterationId y IterationPath y que el 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 instrucción y una cláusula, debe usar un punto y $select coma $expand (;) antes de $expand . Cualquier otra cosa producirá un error.

Ordenar resultados

Puede ordenar los resultados de OData mediante la $orderby cláusula . Puede aplicar esta cláusula a cualquier consulta de OData como se muestra a continuación:

/WorkItems?$orderby=WorkItemId

Puede ordenar en orden ascendente o descendente mediante palabras clave asc o desc correspondientemente:

/WorkItems?&$orderby=WorkItemId desc

Además, puede ordenar por varios elementos:

/WorkItems?$orderby=WorkItemType,State

Aplicación de la paginación del lado servidor

Analytics fuerza la paginación cuando los resultados de la consulta superan los 10 000 registros. En ese caso, se obtiene la primera página de datos y el vínculo que se va a seguir para obtener la página siguiente. El vínculo ( @odata.nextLink ) se puede encontrar al final de la salida JSON. Tendrá el aspecto de una consulta original seguida de $skip o $skiptoken . Por ejemplo:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

Pasos siguientes

Artículos relacionados

• Consultar instrucciones
• Características de OData admitidas
• Especificación de OData v4.0
• OData v4.0, parte 2: convenciones de dirección URL más errata 02