Consultas con ámbito de proyecto y organización

  • Artículo

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

Con Analytics para Azure DevOps, puede construir consultas cuyo ámbito sea un proyecto o una organización o colección. Puede ejecutar estas consultas directamente en el explorador o en Power BI.

Las consultas de ámbito de proyecto ayudan a responder preguntas sobre un solo proyecto, mientras que las consultas con ámbito de organización y recopilación permiten responder a preguntas que cruzan los límites del proyecto. Las consultas con ámbito de organización y recopilació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.

Nota:

El servicio Analytics se habilita automáticamente y se admite en producción para todos los servicios de Azure DevOps. La integración de Power BI y el acceso a la fuente OData del servicio Analytics están disponibles con carácter general. Le recomendamos que lo use y nos envíe sus comentarios. Los datos disponibles dependen de la versión. La versión más reciente admitida es v2.0y la versión preliminar más reciente es v4.0-preview. Para obtener más información, consulte Control de versiones de la API de OData.

Nota:

El servicio Analytics se instala y admite automáticamente en producción para todas las colecciones de proyectos nuevas para Azure DevOps Server 2020 y versiones posteriores. La integración de Power BI y el acceso a la fuente OData del servicio Analytics están disponibles con carácter general. Le recomendamos que lo use y nos envíe sus comentarios. Si ha actualizado desde Azure DevOps Server 2019, puede instalar el servicio Analytics durante la actualización.

Los datos disponibles dependen de la versión. La versión más reciente admitida es v2.0y la versión preliminar más reciente es v4.0-preview. Para obtener más información, consulte Control de versiones de la API de OData.

Nota:

El servicio Analytics está en versión preliminar para Azure DevOps Server 2019. Puede habilitarlo o instalarlo para una colección de proyectos. La integración y el acceso de Power BI a la fuente OData del servicio Analytics se encuentran en versión preliminar. Le recomendamos que lo use y nos envíe sus comentarios.

Los datos disponibles dependen de la versión. La versión más reciente admitida es v2.0y la versión preliminar más reciente es v4.0-preview. Para obtener más información, consulte Control de versiones de la API de 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.

Importante

Si no tiene acceso a todos los proyectos de una organización, se recomienda aplicar un filtro de proyecto a todas las consultas. Al extraer datos en herramientas de cliente como Power BI o Excel, el uso de la sintaxis de la ruta de acceso del proyecto es la mejor manera de asegurarse de que todos los datos están restringidos por el proyecto determinado. Se recomienda usar consultas con ámbito de organización o con ámbito de recopilación solo cuando necesite informar sobre dos o más proyectos.

Consultas con ámbito de proyecto

Para crear una consulta, escriba la dirección URL de OData en un explorador web compatible.

La dirección URL base de una consulta de OData de nivel de proyecto se muestra en la sintaxis siguiente.

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

En los ejemplos proporcionados, reemplace {OrganizationName} y {ProjectName} por los nombres de su organización y proyecto que desee consultar.

Nota:

Los ejemplos restantes que se proporcionan en este artículo se basan en una dirección URL de Azure DevOps Services. Tendrá que sustituir en la dirección URL del servidor de Azure DevOps para ejercer los ejemplos.

Devolver un recuento de elementos de trabajo

Por ejemplo, la siguiente consulta con ámbito de proyecto devuelve el recuento de elementos de trabajo de un proyecto específico.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count

Por ejemplo, una consulta del proyecto Fabrikam Fiber devuelve un recuento de 7126 elementos de trabajo. Los elementos de trabajo eliminados no se incluyen en el recuento.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count

7126

Devolver rutas de acceso del área del proyecto

Del mismo modo, la siguiente cadena de consulta devolverá las áreas de un proyecto específico:

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

Es equivalente al siguiente filtro en una consulta con ámbito de organización:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas?
  $filter=Project/ProjectName eq '{ProjectName}'

Por ejemplo, una consulta del proyecto Fabrikam Fiber devuelve todas las propiedades definidas para una ruta de acceso de área, ya que no se aplica ningún $select operador en la consulta.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas

En el ejemplo siguiente se muestran los datos devueltos para una única ruta de acceso de área.

ProjectSK	"56af920d-393b-4236-9a07-24439ccaa85c"
AreaSK	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaId	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaName	"Service Delivery"
Number	55373
AreaPath	"Fabrikam Fiber\\Service Delivery"
AreaLevel1	"Fabrikam Fiber"
AreaLevel2	"Service Delivery"
AreaLevel3	null
AreaLevel4	null
AreaLevel5	null
AreaLevel6	null
AreaLevel7	null
AreaLevel8	null
AreaLevel9	null
AreaLevel10	null
AreaLevel11	null
AreaLevel12	null
AreaLevel13	null
AreaLevel14	null
Depth	1

Uso de la opción $expand

Al usar una consulta con ámbito de proyecto con una $expand opción, no es necesario proporcionar otros filtros.

Por ejemplo, el siguiente filtro con ámbito de proyecto:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems?
  $expand=Parent

se filtra automáticamente para aplicar la seguridad:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=ProjectName eq '{ProjectName}')

Consultas con ámbito de organización

La dirección URL base de las consultas de nivel de organización se muestra como se muestra:

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0

Al usar una consulta con ámbito de organización con una $expand opción, debe proporcionar otro filtro.

Por ejemplo, la siguiente consulta con ámbito de organización, que usa para $expand recuperar los elementos secundarios de todos los elementos de trabajo.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children

Requiere otro filtro para comprobar que los elementos secundarios están limitados al proyecto especificado:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Devolver el elemento primario de todos los elementos de trabajo

La consulta siguiente, que usa una $expand opción para recuperar el elemento primario de todos los elementos de trabajo.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent

Requiere otro filtro para comprobar que el elemento primario está limitado al proyecto especificado:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}')

Sin el otro filtro, se producirá un error en la solicitud si el elemento primario de cualquier elemento de trabajo hace referencia a elementos de trabajo de un proyecto al que no tiene acceso de lectura.

Restricciones de seguridad de nivel de proyecto

Analytics tiene algunas restricciones más en la sintaxis de consulta relacionada con la seguridad de nivel de proyecto.

Los any filtros o all se aplican a la entidad base en un $expand. En el caso de los filtros basados en un proyecto, se omite explícitamente el filtro al usar :$expand

Por ejemplo, la siguiente consulta:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Se interpreta como:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children

y producirá un error si no tiene acceso a todos los proyectos.

Para solucionar la restricción, debe agregar una expresión adicional en $filter:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}' and Children/any(r: r/ProjectName eq '{ProjectName}')
  &$expand=Children

El uso $level solo se admite si tiene acceso a todos los proyectos de la colección o cuando se usa una consulta con ámbito de proyecto:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Children($levels=2;$filter=ProjectName eq '{ProjectName}')

Analytics no admite ninguna referencia entre niveles para proyectos que usen la $it cláusula . Por ejemplo, la consulta siguiente hace referencia al elemento de ProjectName trabajo raíz mediante $it alias, que no se admite:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Links(
    $expand=TargetWorkItem;
    $filter=TargetWorkItem/Project/ProjectName eq $it/Project/ProjectName)

Paso siguiente

Consulta de datos agregados