Construcción de consultas de OData para Analytics en Azure DevOps

  • Artículo

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

Analytics, la plataforma de informes de Azure DevOps, puede responder a preguntas cuantitativas sobre el estado pasado o presente de los proyectos. Analytics admite consultas de OData de sus metadatos y datos de conjunto de entidades. Al ejercer consultas sencillas desde el explorador web, puede familiarizarse con el modelo de datos y el proceso de consulta.

En este artículo aprenderá lo siguiente:

  • Cómo construir una consulta de OData de Analytics para la nube o el entorno local
  • Consulta de metadatos de Analytics
  • Consulta de OData de Analytics para un conjunto de entidades
  • Qué opciones de consulta se admiten y la secuencia recomendada
  • Cuando se aplica la paginación del lado servidor

Puede consultar Analytics desde cualquier explorador web compatible. Para otras herramientas que puede usar para consultar Analytics, consulte Herramientas de consulta de análisis.

Nota:

OData, un protocolo de nivel de aplicación para interactuar con los datos a través de interfaces RESTful (donde REST=Transferencia de estado representacional) admite la descripción de los modelos de datos, así como la edición y consulta de datos según esos modelos. El modelo de datos de entidad (EDM) o los metadatos describen la información disponible en Analytics, incluidas las entidades, los tipos de entidad, las propiedades, las relaciones y las enumeraciones que se usan para consultar los datos para compilar informes. Para obtener información general sobre OData, consulte Bienvenido a 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 las actividades de habilitación de características y servicios y seguimiento de datos generales, consulte Permisos y requisitos previos para acceder a Analytics.

Componentes de dirección URL para consultar los metadatos

Analytics expone el modelo de entidad en la dirección URL de metadatos, formada anexando $metadata a la dirección URL raíz del servicio. Analytics proporciona raíces de servicio para un proyecto o toda una organización en Azure DevOps.

Puede buscar cualquiera de los siguientes elementos de datos consultando los metadatos.

  • Tipos de entidad y conjuntos de entidades
  • Propiedades y propiedades de navegación
  • Claves suplentes
  • Listas enumeradas
  • EntitySet
  • Contenedores
  • Funciones de filtro (Org.OData.Capabilities.V1.FilterFunctions)
  • Agregaciones admitidas (Org.OData.Aggregation.V1.ApplySupported)
  • Compatibilidad con Batch (Org.OData.Capabilities.V1.BatchSupportType)

La dirección URL que use depende de si está consultando datos para Azure DevOps Services (nube) o una instancia local de Azure DevOps Server.

Para consultar los metadatos de una organización o proyecto hospedado en la nube, escriba la sintaxis de la dirección URL como se muestra a continuación en un explorador web. Reemplace {OrganizationName} y {ProjectName} por el nombre de la organización y el nombre del proyecto que desea consultar. Para devolver todos los metadatos de la organización, no especifique el nombre del proyecto.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

Nota:

La versión más reciente de OData de Analytics es v4.0-preview. Puede usar esta versión para todas las consultas en el servicio hospedado. Para más información sobre las versiones de Analytics y los datos disponibles, consulte Modelo de datos para Analytics.

Este es un ejemplo de la organización fabrikam hospedada en Azure DevOps Services.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

Interpretación de la respuesta de metadatos

Analytics devuelve un archivo XML del modelo de datos. Use la función de búsqueda del explorador para buscar información específica de la entidad de interés.

Sugerencia

Dependiendo del explorador que use, es posible que este archivo tenga o no un formato legible. Si no tiene formato, puede encontrar un formateador XML en línea gratuito a través de una búsqueda del explorador web.

Los dos esquemas principales definidos en los metadatos de Analytics son Microsoft.VisualStudio.Services.Analytics.Model, que define los tipos de entidad y los tipos enumerados y sus miembros, y el Default esquema, que define los contenedores de entidades y conjuntos de entidades y las funciones de agregación personalizadas, transformación y filtro de OData admitidos. Para obtener más información, consulte Análisis de metadatos de OData.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Todos los tipos de entidad están asociados a propiedades y propiedades de navegación. Puede filtrar las consultas de conjuntos de entidades mediante ambos tipos de propiedades. Estos se muestran en los metadatos EntityType de en como o NavigationalPropertyProperty . Las entidades relacionadas se usan para especificar filtros adicionales, como rutas de acceso de iteración, rutas de acceso de área o Teams.

El siguiente fragmento de código proporciona una vista parcial de los metadatos de la WorkItem entidad. Las propiedades corresponden a un campo de elemento de trabajo, así como a datos específicos capturados por Analytics, como LeadTimeDays y CycleTimeDays. Las propiedades de navegación corresponden a otros conjuntos de entidades o a datos específicos de Analytics capturados para el tipo de entidad, como Revisions, Links, Childreny Parent.

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

Componentes de dirección URL para consultar entidades

Para consultar los datos de Analytics y compilar informes, normalmente se consulta un conjunto de entidades. Para obtener información general sobre las entidades admitidas, consulte Análisis de metadatos de OData.

La siguiente dirección URL se usa para consultar un elemento específico EntitySet, como WorkItems, WorkItemSnapshoty PipelineRuns.

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

Este es un ejemplo de la organización fabrikam que devuelve el recuento de elementos de trabajo definidos para el proyecto Fabrikam Fiber.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

El ejemplo devuelve 1399 elementos de trabajo.

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

Nota:

Si no incluye una $select cláusula o $apply , recibirá una advertencia, como "VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060." It's 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 registros, puede tardar varios segundos. Si tiene más de 10 000 elementos de trabajo, se aplica la paginación controlada por servidor.

Para evitar que se produzcan límites de uso, incluya siempre una $select cláusula o $apply .

Para obtener información sobre propiedades y relaciones de metadatos de entidad, consulte los siguientes artículos:

Ejemplo: Consulta de un conjunto de entidades específico

Para consultar un conjunto de entidades específico, como WorkItems, Areaso Projects, agregue el nombre del conjunto de entidades: /WorkItems, /Areaso /Projects. Para obtener una lista completa de conjuntos de entidades, consulte Modelo de datos para Analytics.

Por ejemplo, puede obtener una lista de proyectos definidos para su organización consultando /Projects y seleccionando devolver la ProjectName propiedad . Para la organización fabrikam, la dirección URL es como se muestra a continuación.

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analytics devuelve los nombres de proyecto de esos proyectos definidos para la organización fabrikam .

{
@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

Opciones de consulta

Una opción de consulta es un conjunto de parámetros de cadena de consulta aplicados a un recurso que puede ayudar a controlar la cantidad de datos que se devuelven para el recurso en la dirección URL.

Las opciones de consulta deben especificarse en el orden indicado en la tabla siguiente.

Opción de consulta Notas
$apply Conjunto de transformaciones que se pueden aplicar a una consulta, como: filter, groupby, aggregate, , computeexpand,concat
Para obtener ejemplos, consulte Agregar datos de seguimiento de trabajo mediante Analytics.
$compute Función de OData admitida que puede especificar para definir propiedades calculadas que se pueden usar en una $selectexpresión o $orderby .$filter
$filter Use para filtrar la lista de recursos que se devuelven. La expresión especificada con $filter se evalúa para cada recurso de la colección y solo los elementos en los que la expresión se evalúa como true se incluyen en la respuesta. Los recursos para los que la expresión se evalúa como false o null, o qué propiedades de referencia no están disponibles debido a los permisos, se omiten de la respuesta.
Para obtener ejemplos, consulte Consulta de datos de seguimiento de trabajos mediante Analytics .
$orderby Use para especificar la secuencia en la que se deben devolver los registros.
Para obtener ejemplos, consulte Consulta de datos de seguimiento de trabajos mediante Analytics.
$top/$skip Use para limitar el número de registros devueltos.
Para obtener ejemplos, consulte Consultas con ámbito de proyecto y organización.
$select/$expand Use $select para especificar las columnas que necesita para compilar el informe. Use $expand para anidar otras opciones de consulta. Cada expandItem se evalúa en relación con la entidad que contiene la propiedad de navegación o secuencia que se va a expandir.

Lista separada por punto y coma de opciones de consulta, entre paréntesis, al nombre de la propiedad de navegación. Las opciones de consulta del sistema permitidas son $filter, $select, $top$skip$count$orderby, , $searchy .$expand
Para obtener ejemplos, consulte Consulta de datos de seguimiento de trabajos mediante Analytics.
$skiptoken Use para omitir un número especificado de registros.
$count o $count=true Escriba $count para devolver solo el número de registros. Escriba $count=truepara devolver un recuento del registro y los datos consultados.
Para obtener ejemplos, consulte Agregar datos de seguimiento de trabajo mediante Analytics.

Sugerencia

Evite mezclar $apply y $filter cláusulas en una sola consulta. Para filtrar la consulta, tiene dos opciones: (1) usar una $filter cláusula o (2) usar una $apply=filter() cláusula de combinación. Cada una de estas opciones funciona bien por sí sola, pero combinarlas puede provocar algunos resultados inesperados.

Aplicar paginación del lado servidor

Analytics fuerza la paginación cuando los resultados de la consulta superan los 10000 registros. En ese caso, obtendrá la primera página de datos y el vínculo que se va a seguir para obtener la página siguiente. Vínculo (@odata.nextLink) se puede encontrar al final de la salida JSON. Tendrá un aspecto similar a 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"
}

Nota:

Al extraer datos en herramientas de cliente como Power BI Desktop o Excel, las herramientas seguirán automáticamente el vínculo siguiente y cargarán todos los registros necesarios.

Pasos siguientes

Construcción de consultas básicas mediante OData Analytics