Procedimientos recomendados de análisis

Servicios de Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Analytics es la plataforma de informes de Azure DevOps, que permite obtener información de los datos y tomar decisiones controladas por datos. Analytics está optimizado para el acceso rápido a la lectura y las agregaciones basadas en servidor, y ofrece varias herramientas para visualizar y analizar tus datos. En este artículo, se comparten algunos procedimientos recomendados para usar Analytics en Azure DevOps.

• Si es desarrollador de extensiones, asegúrese de revisar las directrices de consulta de OData Analytics.

Familiarícese con los metadatos de Analytics.

Consulte los metadatos de Analytics para familiarizarse con los tipos de entidad, los conjuntos de entidades, las propiedades y las listas enumeradas. Para más información, consulte Consultar el servicio Analytics, metadatos de Analytics OData, y referencia de entidades y propiedades de Azure Boards.

Estructurar la consulta para devolver los datos que necesita

Para consultar el conjunto de datos mínimo que necesita para crear el informe, siga estos procedimientos:

• Elija el conjunto de entidades que admita el informe que desea crear.
• Especificar elementos de consulta en el orden en que se ejecutan
• Limitar las columnas que solicita en la consulta
• Creación de consultas en versión preliminar
• Limitar las consultas a los proyectos a los que tiene acceso

Elija el conjunto de entidades para soportar el informe.

Aunque se admiten varios EntitySets en el modelo de datos de Analytics, solo se usan algunos para generar informes. EntitySets usados para construir informes se dividen en tres categorías:

• Actual: contiene información sobre la configuración actual de EntityTypes contenido dentro de EntitySet.
• Instantánea: Entidades compuestas que combinan datos históricos y contextualizados temporalmente. Las entidades de instantánea están diseñadas para ser utilizadas en el apoyo de informes de agregación.
• Revisión: contiene información histórica. Por ejemplo, WorkItemRevision mantiene datos sobre el historial de elementos de trabajo.

Aquí tienes una referencia rápida sobre cómo especificar EntityTypes para admitir informes. Para obtener una descripción de cada uno de estos EntityTypes, consulte Modelo de datos para Analytics.

Especificar elementos de consulta en el orden en que se ejecutan

El orden recomendado para los distintos elementos de consulta es especificarlos en el orden siguiente, que es el orden en el que se evalúan. Para obtener una descripción de cada parte de consulta, consulte Consulta del servicio Analytics, Opciones de consulta.

1. $apply
2. $filter
3. $orderby
4. $expand
5. $select
6. $skip
7. $top

Todas las consultas deben contener una cláusula $apply o $select, de lo contrario, podría recibir un mensaje de advertencia.

Limitar las columnas que solicita en la consulta

Especifica las columnas de datos que se van a devolver mediante la cláusula $select. Con la personalización, los elementos de trabajo pueden tener numerosos campos asociados a ellos. Cuantos más propiedades o campos a los que hace referencia una consulta, más caro es procesar. Tenga en cuenta el informe que desea generar y asegúrese de que solo solicita los campos que necesita.

Por ejemplo, para devolver los campos Id., Tipo de elemento de trabajo, Título y Estado de un conjunto filtrado de elementos de trabajo, especifique la siguiente $select cláusula: $select=WorkItemId, WorkItemType, Title, State.

Para buscar la lista de propiedades y sus nombres de campo correspondientes, consulte Referencia de entidades y propiedades para Azure Boards.

Creación de consultas en versión preliminar

Las consultas en versión preliminar son consultas que devuelven un único registro o un pequeño subconjunto de registros. Al crear una consulta en versión preliminar, puede refinar la consulta para asegurarse de que está solicitando los datos que necesita. Al comenzar con una consulta mínima, puede desarrollar su consulta para asegurarse de que está especificando los registros que quiere y los datos de columna que necesita.

Mediante el apply=aggregate($count as Count), puede identificar el número de registros que solicita. Por ejemplo, la sintaxis siguiente consulta el número de elementos de trabajo para el proyecto Fabrikam Fiber .

https://analytics.dev.azure.com/content-learn/Content/_odata/v4.0-preview/WorkItems? $apply=aggregate($count as Count)

La respuesta devuelve un total de 1415 elementos de trabajo.

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

Limitar las consultas a los proyectos a los que tiene acceso

Las consultas de ámbito de proyecto devuelven información sobre un solo proyecto, mientras que las consultas de ámbito de la organización están diseñadas para devolver información que cruza los límites del proyecto. Las consultas con ámbito de la organización requieren permisos de usuario más amplios o restricciones de ámbito cuidadosas para asegurarse de que la consulta no está bloqueada debido a la falta de permisos de proyecto.

Si tiene acceso a uno o varios proyectos, pero no a todos los proyectos, y envía una consulta con ámbito de organización, recibirá un mensaje de error.

"VS403496: The query results include data in one or more projects for which you do not have access. Add one or more projects filters to specify the project(s) you have access to in 'WorkItems' entity. If you're using $expand or navigation properties, project filter is required for those entities. More information can be found here: https://go.microsoft.com/fwlink/?LinkId=786441."

Para obtener más información, consulte Consultas de ámbito de proyecto y organización.

Revisión de los mensajes de advertencia y error

Analytics revisa cada consulta que recibe por incumplimiento de sus normas. Devuelve mensajes de advertencia cuando detecta una infracción. Se recomienda revisar estos mensajes para corregir o mejorar la estructura de consulta.

Contenido relacionado

• ¿Qué es el servicio Analytics?
• Construcción de consultas de OData para Analytics
• Metadatos de Analytics OData
• Directrices de consulta de OData Analytics