Instrucciones de consulta para Analytics con OData

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

Los desarrolladores de extensiones pueden beneficiarse siguiendo las directrices proporcionadas en este artículo para diseñar consultas de OData eficaces en Analytics para Azure DevOps. Seguir estas directrices le ayudará a garantizar que las consultas tienen un buen rendimiento para el tiempo de ejecución y el consumo de recursos. Las consultas que no cumplen estas directrices pueden dar lugar a un rendimiento deficiente, con tiempos de espera de informe largos, consultas que superan el consumo de recursos permitido o bloqueos del servicio.

Las directrices se organizan como recomendaciones sencillas precedida de los términos DO, CONSIDER, AVOID y DON'T. Las reglas restrictivas aplicadas por Analytics contienen el prefijo [BLOCKED]. Con estas directrices, debe comprender las diferencias entre las distintas soluciones. En determinadas circunstancias, es posible que tenga requisitos de datos que le obligan a infringir una o varias directrices. Estos casos deben ser poco frecuentes. Se recomienda tener una razón clara y atractiva para estas decisiones.

https://{servername}:{port}/tfs/{OrganizationName}/{ProjectName}/_odata/{version}/

Mensajes de error y advertencia

✔️ las advertencias de respuesta de OData

Cada consulta que ejecute se comprueba con un conjunto de reglas predefinidas. Las infracciones se devuelven en la respuesta de OData que sigue a @vsts.warnings . Revise estas advertencias a medida que proporcionan información actual y contextual sobre cómo mejorar la consulta.

{
  "@odata.context": "https://{OrganizationName}.tfsallin.net/_odata/v1.0/$metadata#WorkItems",
  "@vsts.warnings": [
    "The specified query does not include a $select or $apply clause which is recommended for all queries."
  ],
  ...
}

✔️ revisar los mensajes de error de OData

Las consultas que infrinjan una regla de error de OData producirán una respuesta con error con un código de estado 400 (solicitud no correcta). Los mensajes asociados no aparecen dentro de la @vsts.warnings propiedad . En su lugar, generarán un mensaje de error en la message propiedad en la respuesta JSON.

{
  "error": {
  "code": "0",
  "message": "The query specified in the URI is not valid. The Snapshot tables in Analytics are intended to be used only in an aggregation."
  }
}

Restricciones

Qué hacer

• ✔️ DO limita la consulta a los proyectos a los que tiene acceso
• ✔️ do especifica el filtro de proyecto dentro de la cláusula si la expansión podría incluir datos en otros proyectos potencialmente inaccesibles.
• ✔️ DO espere o detenga la operación si la consulta supera los límites de uso
• ✔️ DO espere o detenga la operación si se produce un error en la consulta con un tiempo de espera
• ✔️ incluir o columna en la cláusula al agregar sobre tablas de DateValuegroupby instantáneas
• ✔️ DO direcciona explícitamente entidades con cláusulas de filtro
• ✔️ do usar conjunto de entidades para cargar todas las revisiones de un elemento de trabajo determinado
• ✔️ uso del punto de conexión por lotes para consultas largas
• ✔️ DO especifica zona horaria al filtrar por columnas de fecha

Tenga en cuenta que:

• ✔️ CONSIDERAR la posibilidad de realizar consultas mediante el punto de conexión con ámbito de proyecto

Bloqueado

• ❌ [BLOCKED] NO use entidades de instantánea para nada que no sea agregaciones
• ❌ [BLOCKED] NO use claves de entidad en las rutas de acceso de recursos para el direccionamiento de entidades
• ❌ [BLOQUEADO] NO se expande en la WorkItem entidad
• ❌ [BLOCKED] NO agrupar en columnas distintas
• ❌ [BLOCKED] NO use agregación
• ❌ [BLOQUEADO] NO use el punto de conexión por lotes para enviar varias consultas
• ❌ [BLOCKED] NO use consultas que den como resultado más de 800 columnas

Evite

• ❌ EVITAR agregaciones que pueden dar lugar a desbordamiento aritmético
• ❌ EVITAR la creación de consultas largas

✔️ DO limita la consulta a los proyectos a los que tiene acceso

Si la consulta tiene como destino los datos de un proyecto al que no tiene acceso, la consulta devolverá un mensaje "acceso Project denegado". Para asegurarse de que tiene acceso, asegúrese de que el permiso Ver análisis está establecido en Permitir para todos los proyectos que consulte. Para más información, consulte Permisos necesarios para acceder a Analytics.

Este es el mensaje que verá si no tiene acceso a un proyecto:

Los resultados de la consulta incluyen datos de uno o varios proyectos a los que no tiene acceso. Agregue uno o varios filtros de proyectos para especificar los proyectos a los que tiene acceso en la entidad "WorkItems". Si usa propiedades de $expand o de navegación, se requiere el filtro de proyecto para esas entidades.

Para solucionar este problema, puede agregar explícitamente un filtro de proyecto o usar el punto de conexión con ámbito de proyecto, como se explica más adelante en este artículo.

Por ejemplo, la consulta siguiente captura elementos de trabajo que pertenecen a proyectos denominados {projectSK1} y {projectSK2} .

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK1} or ProjectSK eq {projectSK2}
  &$select=WorkItemId, Title

✔️ do especifica el filtro de proyecto dentro de la cláusula si la expansión podría incluir datos en otros proyectos $expand potencialmente inaccesibles.

Al expandir las propiedades de navegación, existe la posibilidad de que termine haciendo referencia a datos de otros proyectos inaccesibles. Si hace referencia a datos inaccesibles, recibirá el mismo mensaje de error enumerado anteriormente: "Los resultados de la consulta incluyen datos en uno o variosproyectos...". De forma similar, puede resolver este problema agregando filtros de proyecto explícitos para controlar los datos expandido.

Puede hacerlo en la cláusula regular para $filter propiedades de navegación simples. Por ejemplo, la consulta siguiente solicita explícitamente dónde existen el vínculo y WorkItemLinks su destino en el mismo proyecto.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemLinks?
  $filter=ProjectSK eq {projectSK} and TargetWorkItem/ProjectSK eq {projectSK}
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($select=WorkItemId, Title)

En su lugar, puede mover el filtro para $filter expandir la opción de la cláusula $expand . Sin embargo, cambia la semántica de la consulta. Por ejemplo, la consulta siguiente obtiene todos los vínculos de un proyecto determinado y expande condicionalmente el destino solo si existe en el mismo proyecto. Aunque es válido, este enfoque puede causar confusión, ya que puede ser difícil determinar si una propiedad no se expande porque es o porque se null filtró. Use esta solución solo si realmente necesita este comportamiento concreto.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemLinks?
  $filter=ProjectSK eq {projectSK}
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($filter=ProjectSK eq {projectSK}; $select=WorkItemId, Title)

Verá que la opción expandir es útil cuando se usa la $filter propiedad expandir colección, como Children en el conjunto de WorkItems entidades. Por ejemplo, la consulta siguiente devuelve todos los elementos de trabajo de un proyecto determinado junto con todos sus elementos secundarios que pertenecen al mismo proyecto.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK}
  &$select=WorkItemId, Title
  &$expand=Children($filter=ProjectSK eq {projectSK}; $select=WorkItemId, Title)

Deberá especificar el filtro si expande una de las siguientes propiedades:

• WorkItems conjunto de entidades: Parent , Children
• WorkItemLinks conjunto de entidades: TargetWorkItem .

✔️ CONSIDERAR la posibilidad de realizar consultas mediante el punto de conexión con ámbito de proyecto

Si está interesado en los datos de un solo proyecto, se recomienda usar el punto de conexión de OData con ámbito de proyecto ( /{ProjectName}/_odata/v1.0 ). Evita los problemas descritos en las dos secciones anteriores y filtra implícitamente los datos al proyecto, al conjunto de entidades al que se hace referencia y a todas las propiedades de navegación expandidas.

Con esta simplificación, las consultas de la sección anterior se podrían volver a escribir en el formulario siguiente. No solo ha desaparecido el filtro de la cláusula expand, sino que tampoco es necesario el filtro en el conjunto de entidades principal.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItemLinks?
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($select=WorkItemId, Title)

La consulta de elementos secundarios de elemento de trabajo también es mucho más corta y más sencilla.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItems?
  &$select=WorkItemId, Title
  &$expand=Children($select=WorkItemId, Title)

Esta solución solo se puede aplicar cuando el foco son los datos de un solo proyecto. Para los informes entre proyectos, debe usar las estrategias de filtrado descritas en las secciones anteriores.

✔️ DO esperar o detener la operación si la consulta supera los límites de uso

Si ejecuta muchas consultas o las consultas requieren muchos recursos para ejecutarse, es posible que supere los límites de servicio y se bloquee temporalmente. Si supera los límites de servicio, detenga la operación, ya que lo más probable es que la siguiente consulta que envíe no tenga el mismo mensaje de error.

La solicitud se bloqueó debido a que se superó el uso del recurso "{resource}" en el espacio de nombres "{namespace}".

Para obtener más información sobre la limitación de velocidad, vea Límites de velocidad. Para obtener información sobre cómo diseñar consultas OData eficaces, consulte Instrucciones de rendimiento más adelante en este artículo.

✔️ do espere o detenga la operación si se produce un error en la consulta con un tiempo de espera

De forma similar a superar los límites de uso, debe esperar o detener la operación si la consulta se encuentra con un tiempo de espera agotado. Podría indicar un problema transitorio, por lo que puede volver a intentarlo una vez para ver si el problema se resuelve. Sin embargo, los tiempos de espera persistentes indican que la consulta probablemente sea demasiado costosa para ejecutarse. Los reintentos adicionales solo darán lugar a que se superen los límites de uso y se le bloqueará.

TF400733: La solicitud se ha cancelado: La solicitud ha superado el tiempo de espera de la solicitud. Inténtelo de nuevo.

Los tiempos de espera indican que una consulta requiere optimización. Para obtener información sobre cómo diseñar consultas OData eficaces, consulte Instrucciones de rendimiento más adelante en este artículo.

❌ [BLOCKED] NO use entidades de instantáneas para nada que no sea agregaciones

Los conjuntos de entidades de instantánea Snapshot con el sufijo son especiales porque se modela como Snapshot Puede usarlas para obtener un estado de entidades como estaban al final de cada día en el pasado. Por ejemplo, si ha consultado y filtrado por un único , obtenería un registro para cada día desde que se creó WorkItemSnapshotWorkItemId el elemento de trabajo. Cargar directamente todos estos datos sería costoso y lo más probable es que supere los límites de uso y se bloquee. Sin embargo, se permiten y se recomiendan las agregaciones en estas entidades. De hecho, los conjuntos de entidades de instantáneas se diseñaron pensando en escenarios de agregación.

Por ejemplo, la consulta siguiente obtiene el número de elementos de trabajo por fecha para observar cómo ha crecido en enero de 2017.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemSnapshot?
  $apply=
    filter(DateSK ge 20170101 and DateSK le 20170131)/
    groupby((DateSK), aggregate($count as Count))

Para obtener más información sobre las agregaciones, vea Datos agregados.

✔️ incluir o columna en la cláusula DateSK al agregar sobre tablas de DateValuegroupby instantáneas

Puesto que todas las entidades de instantánea se modela como tablas de instantáneas diarias, siempre debe incluir una de las propiedades de día ( o ) en la cláusula de DateValue agrupación. De lo contrario, el resultado puede aparecer inflado incorrectamente.

Por ejemplo, si solo se agrupa por propiedad y se agrega con count, todos los números de elementos de trabajo asignados a personas se multiplicarán por el número de días en los que cada asignación estaba WorkItemSnapshotAssignedTo activa. Aunque es posible que tenga una situación en la que sea el resultado que desea, estos casos son poco frecuentes.

❌ [BLOCKED] NO use claves de entidad en las rutas de acceso de recursos para el direccionamiento de entidades

La sintaxis de OData proporciona una manera de acceder a una entidad determinada mediante la inclusión de sus claves directamente en los segmentos de dirección URL. Para obtener más información, vea OData Versión 4.0. Parte 2: Convenciones de dirección URL: 4.3 Direccionamiento de entidades. Aunque OData permite este tipo de direccionamiento, Analytics lo bloquea. La inclusión dentro de una consulta produce el siguiente error.

La consulta especificada en el URI no es válida. Analytics no admite la navegación de clave o propiedad como WorkItems(Id) o WorkItem(Id)/AssignedTo. Si recibe ese error en PowerBI, vuelva a escribir la consulta para evitar un plegado incorrecto que cause un problema de N+1.

Como se muestra en los mensajes de error, ciertas herramientas de cliente pueden usar el direccionamiento directo de entidades. En lugar de cargar todos los datos en una sola solicitud, estos clientes pueden optar por consultar cada entidad de forma independiente. Esta práctica no se recomienda, ya que puede dar lugar a un gran número de solicitudes. En su lugar, se recomienda usar el direccionamiento de entidad explícito como se explica en la sección siguiente.

✔️ DO direcciona explícitamente entidades con cláusulas de filtro

Si desea capturar datos para una sola entidad, debe usar el mismo enfoque que para una colección de entidades y definir explícitamente filtros en la $filter cláusula .

Por ejemplo, la consulta siguiente obtiene un único elemento de trabajo por su identificador.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=WorkItemId eq {id}
  &$select=WorkItemId, Title

Si no está seguro de qué propiedades debe incluir en este tipo de filtro, puede buscarla en los metadatos. Consulte Exploración de los metadatos de OData de Analytics. Las propiedades están en Key el elemento de EntityType . Por ejemplo, WorkItemId y son columnas de clave para la RevisionWorkItemRevision entidad.

<EntityType Name="WorkItemRevision">
  <Key>
    <PropertyRef Name="WorkItemId"/>
    <PropertyRef Name="Revision"/>
  </Key>
  [...]
</EntityType>

❌ [BLOCKED] NO se expande Revisions en la WorkItem entidad

El modelo de datos de Analytics no permite ciertos tipos de expansiones. Una de ellas, que puede ser sorprendente para algunos, es la Revisions propiedad de colección en la WorkItem entidad. Si intenta expandir esta propiedad, recibirá el siguiente mensaje de error.

La consulta especificada en el URI no es válida. La propiedad "Revisions" no se puede usar en la $expand de consulta.

Esta restricción se ha puesto en marcha para animar a todos los usuarios a usar la solución recomendada, que es la captura de revisiones de como se explica WorkItemRevisions en la sección siguiente.

✔️ usar conjunto WorkItemRevisions de entidades para cargar todas las revisiones de un elemento de trabajo determinado

Use WorkItemRevisions cada vez que desee capturar el historial completo de un elemento de trabajo o una colección de elementos de trabajo.

Por ejemplo, la consulta siguiente devuelve todas las revisiones de un elemento de trabajo con el {id} identificador .

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemRevisions?
  $filter=WorkItemId eq {id}
  &$select=WorkItemId, Title

Si le interesa el historial completo de todos los elementos de trabajo que coinciden con determinados criterios, puede expresarlo mediante un filtro en la WorkItem propiedad de navegación. Por ejemplo, la consulta siguiente obtiene todas las revisiones de todos los elementos de trabajo actualmente activos.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemRevisions?
  $filter=WorkItem/State eq 'Active'
  &$select=WorkItemId, Title

❌ [BLOCKED] NO agrupar en columnas distintas

Use una operación de agrupación para reducir el número de registros. El uso de columnas groupby distintas en la cláusula indica un problema y la consulta producirá un error inmediatamente. Si accidentalmente se encuentra con esta situación, recibirá el siguiente mensaje de error.

No se recomienda una o varias de las columnas especificadas en la cláusula groupby de esta consulta.

Para resolver este problema, quite la columna distinta de la groupby cláusula .

❌ [BLOCKED] NO use la countdistinct agregación

Analytics no admite la countdistinct función, aunque OData sí. Aunque tenemos previsto agregar compatibilidad en el futuro, actualmente no está disponible. Una consulta que contiene esta función devolverá el siguiente mensaje de error.

No se admiten las consultas que aplican un recuento distinto con una agregación.

❌ evitar agregaciones que pueden dar lugar a desbordamiento aritmético

En raras ocasiones, una consulta de agregación puede tener problemas con el desbordamiento aritmético. Por ejemplo, puede ocurrir cuando se suman algunas propiedades numéricas que no están diseñadas para sumar, como en las StackRank entidades de elemento de trabajo. Dado que la extensión OData para agregación de datos estándar no proporciona una manera de convertir una propiedad a un tipo diferente, la única manera de resolver este problema es quitar la propiedad problemática de la agregación.

✔️ uso del punto de conexión por lotes para consultas largas

Puede incurrir en problemas con consultas largas. En concreto, pueden producirse problemas cuando:

• Puede consultar un proyecto con muchos campos personalizados.
• La consulta se construye mediante programación.

El límite actual de consultas de OData enviadas con HTTP GET es de 3000 caracteres. Si lo supera, volverá a recibir una respuesta"404 No encontrado".

HTTP/1.1 404 Not Found
Content-Length: 0

Para resolver este problema, use el punto de conexión por lotes de OData como se explica en la especificación OData Versión 4.0. Parte 1: Protocolo : 11.7 Solicitudes por lotes. La funcionalidad de Batch se diseñó principalmente para agrupar varias operaciones en una carga de solicitud única, pero también puede usarla como solución alternativa para la limitación de longitud HTTP de consulta. Al enviar una solicitud, puede pasar una consulta de una longitud arbitraria y el servicio la HTTP POST interpretará correctamente.

❌ [BLOCKED] NO use el punto de conexión por lotes para enviar varias consultas

Se restringe el uso del punto de conexión por lotes para que no controle un lote de varias solicitudes. Una única solicitud todavía puede tener una sola consulta. Si intenta enviar un lote de varias consultas, se producirá un error en la operación con el siguiente mensaje de error. La única solución es dividir las consultas en varias solicitudes.

Analytics no admite el procesamiento de varias operaciones que contiene el mensaje por lotes actual. Analytics usa el lote de OData para admitir solicitudes POST, pero requiere que limite la operación a una sola solicitud.

❌ [BLOCKED] NO use consultas que resulten en más de 800 columnas

Se restringen las consultas que tienen como resultado más de 800 columnas. Si no es lo suficientemente selectivo en las columnas que devuelve la consulta, puede recibir el siguiente mensaje de error.

VS403670: la consulta especificada reejeje las columnas "N", que es superior al límite permitido de 800 columnas. Use opciones de $select explícitas (incluidas las $expand) para limitar el número de columnas.

Agregue una $select a la consulta y para $expand operaciones en la consulta, para evitar superar este límite.

❌ EVITAR la creación de consultas largas

Se recomienda evaluar el enfoque cada vez que cree una consulta larga. Aunque hay muchos escenarios que necesitan una consulta larga (por ejemplo, filtros complejos o una larga lista de propiedades), normalmente proporcionan un indicador temprano de un diseño poco avanzado.

Cuando la consulta contiene muchas claves de entidad en la consulta (por ejemplo, ), probablemente WorkItemId eq {id 1} or WorkItemId eq {id 2} or ... pueda volver a escribirla. En lugar de pasar los identificadores, intente definir otros criterios que seleccionarán el mismo conjunto de entidades. A veces es posible que deba modificar el proceso (por ejemplo, agregar un nuevo campo o etiqueta), pero normalmente merece la pena. Las consultas que usan filtros más abstractos son más fáciles de mantener y tienen un mayor potencial para funcionar mejor.

Otro escenario que tiende a generar consultas largas se produce cuando se incluyen muchas fechas individuales (por ejemplo, DateSK eq {dateSK 1} or DateSK eq {dateSK 2} or ... ). Busque otro patrón que pueda usar para crear un filtro más abstracto. Por ejemplo, la consulta siguiente devuelve todos los elementos de trabajo que se crearon el lunes.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedOn/DayOfWeek eq 2
  &$select=WorkItemId, Title, State

✔️ DO especifica la zona horaria al filtrar por columnas de fecha

La zona horaria ( ) expone toda la información de fecha y hora con un desplazamiento que coincide con la configuración de zona horaria Edm.DateTimeOffsetEdm.DateTimeOffset Estos datos son precisos y fáciles de interpretar al mismo tiempo. Otra consecuencia no obvia es que todos los filtros también tienen que pasar la información de zona horaria. Si lo omite, verá el siguiente mensaje de error.

La consulta especificada en el URI no es válida. No se especificó ningún desplazamiento de fecha y hora. Use cualquiera de estos formatos YYYY-MM-ddZ para especificar todo desde medianoche o yyyy-MM-ddThh:mm-hh:mm (representación estándar ISO 8601 de fechas y horas) para especificar el desplazamiento.

Para solucionar este problema, agregue la información de zona horaria. Por ejemplo, suponiendo que la organización esté configurada para mostrar datos en la zona horaria "(UTC-08:00) Hora del Pacífico (EE. UU.) Canadá), la consulta siguiente obtiene todos los elementos de trabajo creados desde principios de 2017.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDate ge 2017-01-01T00:00:00-08:00
  &$select=WorkItemId, Title, State

La misma solución funciona para zonas horarias con desplazamientos positivos; sin embargo, el carácter más ( ) tiene un significado especial en el URI y debe + controlarlo correctamente. Si especifica 2017-01-01T00:00:00+08:00 (con un carácter) como punto + de partida, verá el siguiente error.

La consulta especificada en el URI no es válida. Error de sintaxis en la posición 31 de "CreatedDate ge 2017-01-01T0000 08:00".

Para solucionarlo, reemplace el + carácter por su versión codificada, %2B . Por ejemplo, suponiendo que la organización está configurada para mostrar datos en la zona horaria "(UTC+08:00) Utc, C gmt, Hong Kong, Urumqi", la consulta siguiente devuelve todos los elementos de trabajo creados desde principios de 2017.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDate ge 2017-01-01T00:00:00%2B08:00
  &$select=WorkItemId, Title, State

Un enfoque alternativo es usar las propiedades clave suplentes de fecha, ya que no mantienen la información de zona horaria. Por ejemplo, la consulta siguiente devuelve todos los elementos de trabajo creados desde principios de 2017, independientemente de la configuración de la organización.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge 20170101
  &$select=WorkItemId, Title, State

Directrices de rendimiento

Qué hacer

• ✔️ DO mide el efecto de implementar una guía de rendimiento
• ✔️ USAR extensiones de agregación
• ✔️ DO especifica columnas en la cláusula
• ✔️ DO especifica columnas en la opción de expansión dentro de la $expand cláusula
• ✔️ DO define un filtro en al consultar datos de elementos de trabajo históricos ( WorkItemRevisions o conjuntos WorkItemSnapshot de entidades)
• ✔️ usar instantáneas semanales o mensuales para consultas de tendencias que abarcan un largo período de tiempo
• ✔️ do usar la propiedad de colección en elementos de trabajo al filtrar por etiquetas
• ✔️ la propiedad DO si desea mostrar todas las etiquetas de un elemento de trabajo como texto
• ✔️ uso de la paginación controlada por el servidor
• ✔️ usar la opción de consulta para limitar el número de registros

No lo haga

• ❌ no usar las funciones y para realizar una comparación que no diferencia toupper entre mayúsculas y minúsculas
• ❌ no use la expansión sin enlazar con
• ❌ no usar y consultar opciones para $skip implementar la paginación controlada por el cliente

Tenga en cuenta que:

• ✔️ la posibilidad de escribir una consulta para devolver un pequeño número de registros
• ✔️ CONSIDERAR la limitación del número de propiedades seleccionadas al mínimo
• ✔️ CONSIDERE la posibilidad de filtrar las propiedades de clave suplente de fecha (sufijo)
• ✔️ CONSIDERE la posibilidad de filtrar por columnas de clave suplentes
• ✔️ CONSIDERAR la posibilidad de pasar preferencias en el encabezado

Evite

• ❌ USAR las propiedades Children , o en las Revisions$filter$expand cláusulas o

✔️ DO mide el efecto de implementar una guía de rendimiento

Al igual que con las recomendaciones de rendimiento, no debe implementarlas a la vista. En su lugar, capture siempre la línea base y mida el efecto de los cambios que realice. Todas las directrices se crearon en función de las interacciones con los clientes de Analytics que tenían requisitos y desafíos específicos. Estas recomendaciones se consideraron generales y potencialmente útiles para cualquier persona que diseña consultas similares. Sin embargo, en raras ocasiones, seguir las instrucciones podría no tener ningún efecto o incluso un efecto negativo en el rendimiento. Debe medir la diferencia para observarla. En caso de que esto suceda, proporcione comentarios en el portal Community desarrolladores.

Hay muchas opciones para medir el rendimiento. La más sencilla es ejecutar dos versiones de la misma consulta directamente en el explorador. Observe el tiempo que tarda en usar las herramientas de desarrollo. Por ejemplo, puede usar el panel Reden Microsoft Edge Herramientas de desarrollo F12). Otra opción es capturar esta información mediante fiddler Web Debugger Tool.

Sea cual sea su enfoque, ejecute ambas consultas varias veces. Por ejemplo, ejecute las consultas 30 veces cada una para tener un conjunto de muestras lo suficientemente grande. A continuación, averiguar las características de rendimiento. Analytics sigue la arquitectura multiinquilino. Por lo tanto, la duración de las consultas podría verse afectada por otras operaciones que se producen al mismo tiempo.

✔️ USAR extensiones de agregación

Con diferencia, lo mejor que puede hacer para mejorar el rendimiento de las consultas es usar la extensión de agregación OData para la agregación de datos. Con la extensión de agregación, pida al servicio que resuma el lado servidor de datos y devuelva una respuesta mucho más pequeña de lo que puede capturar aplicando la misma función del lado cliente. Por último, Analytics está optimizado para este tipo de consultas, por lo que debe usarlo.

Para obtener más información, vea Agregar datos.

✔️ DO especifica columnas en la $select cláusula

Especifique las columnas que le importan en la $select cláusula . Analytics se basa en una tecnología de índice de almacén de columnas. Esto significa que los datos son almacenamiento y el procesamiento de consultas se basa en columnas. Al reducir el conjunto de propiedades, se hace referencia a en la cláusula para reducir el número de columnas que se deben examinar y mejorar el rendimiento $select general de la consulta.

Por ejemplo, la consulta siguiente especifica las columnas de los elementos de trabajo.

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

✔️ DO especifica columnas en la opción $select de expansión dentro de la $expand cláusula

De forma similar a las $select directrices de la cláusula , especifique las propiedades de la $select opción de expansión dentro de la $expand cláusula . Es fácil olvidarlo, pero si lo omite, la respuesta contendrá todas las propiedades del objeto expandido.

Por ejemplo, la consulta siguiente especifica las columnas para el elemento de trabajo y su elemento primario.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $select=WorkItemId, Title, State
  &$expand=Parent($select=WorkItemId, Title, State)

✔️ DO define un filtro en al consultar datos de elementos de trabajo RevisedDateSK históricos ( WorkItemRevisions o conjuntos WorkItemSnapshot de entidades)

Cuando se consultan datos históricos, lo más probable es que esté interesado en el período más reciente (por ejemplo, 30 días, 90 días). Debido a cómo se implementan las entidades de elementos de trabajo, hay una manera cómoda de escribir estas consultas para obtener un rendimiento excelente. Cada vez que se actualiza un elemento de trabajo, se crea una nueva revisión y se registra esta acción en el campo , lo que la hace perfecta para System.RevisedDate los filtros de historial.

En Analytics, la fecha revisada se representa mediante RevisedDate las propiedades ( ) y ( Edm.DateTimeOffsetRevisedDateSKEdm.Int32 ). Para obtener el mejor rendimiento, use el último. Es la clave suplente de fecha y representa la fecha en que se creó una revisión o tiene para las revisiones activas incompletas. Si desea todas las fechas desde {startDate} inclusive, agregue el filtro siguiente a la consulta.

RevisedDateSK eq null or RevisedDateSK gt {startDateSK}

Por ejemplo, la consulta siguiente devuelve el número de elementos de trabajo para cada día desde principios de 2017. Tenga en cuenta que, aparte del filtro obvio de DateSK la columna, hay un segundo filtro en RevisedDateSK . Aunque puede parecer redundante, ayuda al motor de consultas a filtrar las revisiones que no están en el ámbito y mejora significativamente el rendimiento de las consultas.

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0/WorkItemSnapshot?
  $apply=
    filter(DateSK gt 20170101)/
    filter(RevisedDateSK eq null or RevisedDateSK gt 20170101)/
    groupby(
      (DateValue), 
      aggregate($count as Count)
    )

✔️ usar instantáneas semanales o mensuales para consultas de tendencias que abarcan un largo período de tiempo

De forma predeterminada, todas las tablas de instantáneas se modela como tablas de hechos de instantáneas diarias. Si consulta un intervalo de tiempo, se obtiene un valor para cada día. Los intervalos de tiempo largos tienen como resultado un gran número de registros. Si no necesita una precisión tan alta, puede usar instantáneas semanales o incluso mensuales.

Puede hacerlo con otras expresiones de filtro para quitar los días que no finalizan una semana o un mes determinados. Use la IsLastDayOfPeriod propiedad , que se agregó a Analytics con este escenario en mente. Esta propiedad es de tipo y puede determinar si un día finaliza en períodos diferentes Microsoft.VisualStudio.Services.Analytics.Model.Period (por ejemplo, semanas, meses, y así sucesivamente).

<EnumType Name="Period" IsFlags="true">
  <Member Name="None" Value="0"/>
  <Member Name="Day" Value="1"/>
  <Member Name="WeekEndingOnSunday" Value="2"/>
  <Member Name="WeekEndingOnMonday" Value="4"/>
  <Member Name="WeekEndingOnTuesday" Value="8"/>
  <Member Name="WeekEndingOnWednesday" Value="16"/>
  <Member Name="WeekEndingOnThursday" Value="32"/>
  <Member Name="WeekEndingOnFriday" Value="64"/>
  <Member Name="WeekEndingOnSaturday" Value="128"/>
  <Member Name="Month" Value="256"/>
  <Member Name="Quarter" Value="512"/>
  <Member Name="Year" Value="1024"/>
  <Member Name="All" Value="2047"/>
</EnumType>

Puesto que se define como y enumera con marcas, use el operador OData y especifique Microsoft.VisualStudio.Services.Analytics.Model.Period el tipo completo para los has literales de punto.

IsLastDayOfPeriod has Microsoft.VisualStudio.Services.Analytics.Model.Period'Month'

Por ejemplo, la consulta siguiente devuelve un recuento de elementos de trabajo que se definieron el último día de cada mes.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemSnapshot?
  $apply=
    filter(IsLastDayOfPeriod has Microsoft.VisualStudio.Services.Analytics.Model.Period'Month')/
    groupby(
      (DateValue), 
      aggregate($count as Count)
    )

✔️ do usar la Tags propiedad de colección en elementos de trabajo al filtrar por etiquetas

Puede usar la TagNames propiedad con la función para determinar si un trabajo se ha marcado con una etiqueta contains específica. Sin embargo, este enfoque podría dar lugar a consultas lentas, especialmente al comprobar varias etiquetas al mismo tiempo. Para obtener el mejor rendimiento y los resultados, use la Tags propiedad de navegación en su lugar.

Por ejemplo, la consulta siguiente obtiene todos los elementos de trabajo etiquetados con {tag} .

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq '{tag}')
  &$select=WorkItemId, Title, State

Este enfoque también funciona muy bien cuando necesita filtrar por varias etiquetas. Por ejemplo, la consulta siguiente devuelve todos los elementos de trabajo etiquetados con {tag1}{tag1}{tag2}

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq {tag1} or t/TagName eq {tag2})
  &$select=WorkItemId, Title, State

También puede combinar estos filtros con un operador "y". Por ejemplo, la consulta siguiente obtiene todos los elementos de trabajo etiquetados con {tag1}{tag1}{tag2}

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq {tag1}) and Tags/any(t:t/TagName eq {tag2})
  &$select=WorkItemId, Title, State

✔️ la propiedad DO si desea mostrar todas las TagNames etiquetas de un elemento de trabajo como texto

La propiedad Tags de navegación , descrita en la sección anterior, es excelente para el filtrado. Sin embargo, trabajar con ellos presenta algunos desafíos, ya que la consulta devuelve etiquetas en una colección anidada. El modelo de datos también contiene una TagNames propiedad primitiva ( ), que hemos agregado para simplificar los Edm.String escenarios de consumo de etiquetas. Es un valor de texto único que contiene una lista de todas las etiquetas combinadas con un separador de punto y coma ";". Use esta propiedad cuando lo único que le interesa sea mostrar etiquetas juntas. Puede combinarlo con los filtros de etiquetas descritos anteriormente.

Por ejemplo, la consulta siguiente obtiene todos los elementos de trabajo etiquetados con {tag} . Devuelve el identificador del elemento de trabajo, el título, el estado y una representación de texto de etiquetas combinadas.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq '{tag}')
  &$select=WorkItemId, Title, State, TagNames

❌ no usar las funciones y para realizar una comparación que no diferencia tolowertoupper entre mayúsculas y minúsculas

Si ha trabajado con otros sistemas, es posible que tenga que usar las funciones o para la comparación que no diferencia entre mayúsculas y tolowertoupper minúsculas. Con Analytics, todas las comparaciones de cadenas no tienen en cuenta las mayúsculas y minúsculas de forma predeterminada, por lo que no es necesario aplicar ninguna función para controlarla explícitamente.

Por ejemplo, la consulta siguiente obtiene todos los elementos de trabajo etiquetados con "QUALITY", "quality" o cualquier otra combinación de mayúsculas y minúsculas de esta palabra.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq 'quality')
  &$select=WorkItemId, Title, State, TagNames

❌ no use la expansión sin enlazar con $levels=max

OData tiene la capacidad de expandir todos los niveles de una estructura jerárquica. Por ejemplo, el seguimiento de elementos de trabajo tiene algunas entidades en las que se podría aplicar una expansión sin enlazar. Esta operación solo funciona para organizaciones con una pequeña cantidad de datos. No se escala bien para conjuntos de datos más grandes. No lo use en absoluto si:

• Está trabajando con grandes conjuntos de datos.
• Está desarrollando un widget y no tiene control sobre dónde se instalará el widget.

✔️ uso de la paginación controlada por el servidor

Si solicita un conjunto demasiado grande para enviarse en una sola respuesta, Analytics aplicará la paginación. La respuesta incluirá solo un conjunto parcial y un vínculo que permite recuperar el siguiente conjunto parcial de elementos. Esta estrategia se describe en la especificación de OData: versión 4.0 de OData. Parte 1: Protocolo: Server-Driven paginación. Al permitir que el servicio controle la paginación, obtiene el mejor rendimiento, ya que ha sido cuidadosamente diseño para que cada entidad sea lo skiptoken más eficaz posible.

El vínculo a la página siguiente se incluye en la @odata.nextLink propiedad .

{
  "@odata.context": "https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/$metadata#WorkItems(*)",
  "value": [
    ...
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?$skiptoken=12345"}

❌ no usar y consultar opciones para $top$skip implementar la paginación controlada por el cliente

Con otras API REST, es posible que haya implementado la paginación controlada por el cliente con las $top opciones de consulta y $skip . No los use con Analytics. Hay varios problemas con este enfoque y el rendimiento es uno de ellos. En su lugar, adopte la estrategia de paginación controlada por el servidor descrita en la sección anterior.

✔️ usar la $top opción de consulta para limitar el número de registros

La opción $top de consulta solo se desaconseja cuando se usa junto con $skip . Si en el escenario de informes solo necesita un subconjunto de registros (por ejemplo, ejemplo), se puede usar la opción $top de consulta . Además, si necesita clasificar los registros según algunos criterios, siempre debe usar en combinación con para obtener un resultado estable con los $top$orderby registros de clasificación superior.

✔️ LA POSIBILIDAD de escribir una consulta para devolver un pequeño número de registros

Escribir una consulta para devolver un pequeño número de registros es la guía más intuitiva. Siempre tiene el objetivo de capturar solo los datos que realmente le importan. Puede lograrlo haciendo que la mayoría de las eficaces funcionalidades de filtrado estén disponibles en el lenguaje de consulta OData.

✔️ CONSIDERAR la limitación del número de propiedades seleccionadas al mínimo

Algunos administradores de proyectos personalizan en gran medida sus procesos mediante la adición de campos personalizados. La personalización intensa puede provocar problemas de rendimiento al capturar todas las columnas disponibles en entidades anchas (por ejemplo, WorkItems ). Analytics se basa en una tecnología de índice de almacén de columnas. Esto significa que los datos son almacenamiento y el procesamiento de consultas se basa en columnas. Por lo tanto, entre más propiedades haga referencia una consulta, más cara será procesar. Siempre debe limitar el conjunto de propiedades de las consultas a lo que realmente le interesa en el escenario de informes.

✔️ CONSIDERE la posibilidad de filtrar en las propiedades de clave suplente de fecha DateSK (sufijo)

Hay muchas maneras de definir un filtro de fecha. Puede filtrar directamente por la propiedad date (por ejemplo, ), su homólogo de navegación (por ejemplo, ) o su representación de clave suplente CreatedDateCreatedOnDate (por ejemplo, CreatedDate ). La última opción produce el mejor rendimiento y es preferible cuando los requisitos de informes lo permiten.

Por ejemplo, la consulta siguiente obtiene todos los elementos de trabajo creados desde principios de 2017.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge 20170101

✔️ CONSIDERE la posibilidad de filtrar por columnas de clave suplentes

Si desea filtrar los datos por el valor de un objeto relacionado (por ejemplo, filtrar un elemento de trabajo por el nombre del proyecto), siempre tiene dos opciones. Puede usar la propiedad de navegación (por ejemplo, ) o capturar la clave suplente por adelantado y usarla directamente en la consulta Project/ProjectName (por ejemplo, Project/ProjectNameProjectSK ).

Si va a crear un widget, se recomienda usar esta última opción. Cuando se pasa la clave como parte de la consulta, se reduce el número de conjuntos de entidades que se deben tocar y mejora el rendimiento.

Por ejemplo, la consulta siguiente filtra WorkItems mediante la propiedad en lugar de la propiedad de ProjectSKProject/ProjectName navegación.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK}

❌ USAR las Parent propiedades Children , o en las Revisions$filter$expand cláusulas o

Los elementos de trabajo son las entidades más costosas de todo el modelo de datos. Tienen varias propiedades de navegación que puede usar para tener acceso a elementos de trabajo relacionados: Parent , Children , Revisions . Sin embargo, cada vez que se usan dentro de una consulta, se espera una disminución del rendimiento. Pregunta siempre si realmente necesitas una de estas propiedades y potencialmente actualizas tu diseño.

Por ejemplo, en lugar de expandir , puede capturar más elementos de trabajo y usar la propiedad para reconstruir la jerarquía completa ParentParentWorkItemId del lado cliente. Realice dicha optimización caso por caso.

✔️ CONSIDERAR la posibilidad de VSTS.Analytics.MaxSize pasar preferencias en el encabezado

Cuando se ejecuta una consulta, no se conoce el número de registros que devolverá la consulta. Tiene que enviar otra consulta con agregaciones o seguir todos los vínculos siguientes y capturar todo el conjunto de datos. Analytics respeta las preferencias, lo que le permite conmutar por error rápidamente en aquellos casos en los que el conjunto de datos es mayor que VSTS.Analytics.MaxSize lo que el cliente puede aceptar.

Esta opción es útil en escenarios de exportación de datos. Para usarlo, tiene que agregar el Prefer encabezado a la solicitud HTTP y VSTS.Analytics.MaxSize establecerlo en un valor no negativo. El VSTS.Analytics.MaxSize valor representa el número máximo de registros que puede aceptar. Si lo establece en cero, se usará un valor predeterminado de 200 000.

Por ejemplo, la consulta siguiente devuelve elementos de trabajo si el conjunto de datos es menor o igual a 1000 registros.

GET https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems HTTP/1.1
User-Agent: {application}
Prefer: VSTS.Analytics.MaxSize=1000
OData-MaxVersion: 4.0
Accept: application/json;odata.metadata=minimal
Host: {OrganizationName}.analytics.visualstudio.com

Si el conjunto de datos supera el límite de 1000 registros, la consulta producirá inmediatamente el siguiente error.

El resultado de la consulta contiene 1296 filas y supera el tamaño máximo permitido de 1000. Reduzca el número de registros mediante la aplicación de filtros adicionales.

Directrices de estilo de consulta

• ✔️ do usar la propiedad virtual en los métodos de agregación
• ❌ EVITAR el uso de la propiedad virtual en el segmento de dirección URL
• ❌ EVITAR la combinación de $filter cláusulas y en una sola consulta
• ✔️ USAR alias de parámetro para separar partes volátiles de la consulta
• ✔️ CONSIDERE la posibilidad de estructurar la consulta para que coincida con el orden de evaluación de OData
• ✔️ considere la posibilidad de revisar las funcionalidades de OData descritas en las anotaciones de metadatos.

✔️ do usar $count la propiedad virtual en los métodos de agregación

Algunas entidades exponen la Count propiedad . Facilitan algunos escenarios de informes cuando los datos se exportan a un almacenamiento diferente. Sin embargo, no debe usar estas columnas en agregaciones en consultas de OData. Use la $count propiedad virtual en su lugar.

Por ejemplo, la consulta siguiente devuelve el número total de elementos de trabajo.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $apply=aggregate($count as Count)

❌ EVITAR el uso de $count la propiedad virtual en el segmento de dirección URL

Aunque OData estándar permite usar la propiedad virtual para conjuntos de entidades (por ejemplo, ), no todos los clientes pueden $count_odata/v1.0/WorkItems/$count interpretar la respuesta correctamente. Por lo tanto, se recomienda usar agregaciones en su lugar.

Por ejemplo, la consulta siguiente devuelve el número total de elementos de trabajo.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $apply=aggregate($count as Count)

✔️ USAR alias de parámetro para separar partes volátiles de la consulta

Los alias de parámetro proporcionan una solución elegante para extraer partes volátiles como valores de parámetro del texto de consulta principal. Puede usarlas en expresiones que evalúen:

• Un valor primitivo
• Un valor complejo
• Colección de valores primitivos o complejos.

Para obtener más información, vea OData Versión 4.0. Parte 2: Convenciones de dirección URL: alias de parámetro 5.1.1.13. Los parámetros son útiles cuando el texto de la consulta se usa como una plantilla a la que se pueden crear instancias con valores proporcionados por el usuario.

Por ejemplo, la consulta siguiente usa @createdDateSK el parámetro para separar el valor de la expresión de filtro.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge @createdDateSK
  &$select=WorkItemId, Title, State
  &@createdDateSK=20170101

❌ EVITAR la combinación $apply de $filter cláusulas y en una sola consulta

Si desea agregar a filter la consulta, tiene dos opciones. Puede hacerlo con la cláusula $filter o la $apply=filter() combinación. Cada una de estas opciones funciona muy bien por sí sola, pero combinarlas juntas podría provocar algunos resultados inesperados.

A pesar de lo esperado, OData define claramente un orden de la evaluación. Además, la $apply cláusula tiene prioridad sobre $filter . Por este motivo, debe elegir una u otra, pero evitar estas dos opciones de filtro en una sola consulta. Es importante si las consultas se generan automáticamente.

Por ejemplo, la consulta siguiente filtra primero los elementos de trabajo por , agrega los resultados por y, por último, filtra StoryPoint gt 5 el resultado por StoryPoints gt 2 . Con este orden de evaluación, la consulta siempre devolverá un conjunto vacío.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=StoryPoints gt 2
  $apply=
    filter(StoryPoints gt 5)/
    groupby(
      (Area/AreaPath),
      aggregate(StoryPoints with sum as StoryPoints)
    )

✔️ CONSIDERE la posibilidad de estructurar la consulta para que coincida con el orden de evaluación de OData

Dado que la combinación de cláusulas y en una sola consulta puede dar lugar a una posible confusión, se recomienda estructurar las cláusulas de consulta para que $applyfilter coincidan con el orden de evaluación.

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

✔️ considere la posibilidad de revisar las funcionalidades de OData descritas en las anotaciones de metadatos.

Si no está seguro de qué funcionalidades de OData admite Analytics, puede buscar anotaciones en los metadatos. El comité Open Data Protocol técnico de OASIS (OData) en un repositorio de GitHub TC mantiene una lista de anotaciones disponibles.

Por ejemplo, la lista de funciones de filtro admitidas está disponible en Org.OData.Capabilities.V1.FilterFunctions la anotación en el contenedor de entidades.

<Annotation Term="Org.OData.Capabilities.V1.FilterFunctions">
  <Collection>
  <String>contains</String>
  <String>endswith</String>
  [...]
  </Collection>
</Annotation>

Otra anotación útil es Org.OData.Capabilities.V1.ExpandRestrictions , que explica qué propiedades de navegación no se pueden usar en la cláusula $expand . Por ejemplo, la anotación siguiente explica Revisions que en el conjunto de entidades no se puede WorkItems expandir.

<EntitySet Name="WorkItems" EntityType="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
  [...]
  <Annotation Term="Org.OData.Capabilities.V1.ExpandRestrictions">
    <Record>
      <PropertyValue Property="Expandable" Bool="true"/>
      <PropertyValue Property="NonExpandableProperties">
        <Collection>
          <NavigationPropertyPath>Revisions</NavigationPropertyPath>
        </Collection>
      </PropertyValue>
    </Record>
  </Annotation>
</EntitySet>

Artículos relacionados

• Consulta de datos de seguimiento de elementos de trabajo
• Agregar datos
• Consultar datos de tendencia
• Consultar vínculos de elemento de trabajo
• Exploración de los metadatos de OData para Analytics
• Cláusulas de funciones admitidas