Consultas con ámbito de proyecto y organización

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

Con Analytics para Azure DevOps, puede construir consultas de ámbito de proyecto u organización para devolver elementos de trabajo de interés. Estas consultas se ejecutan directamente en el explorador.

Project de ámbito le ayudan a responder preguntas sobre un único proyecto, mientras que las consultas de ámbito de la organización le permiten responder preguntas que cruzan 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.

Requisitos previos

Project con ámbito de aplicación

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

La dirección URL base para las consultas de nivel de proyecto es:

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

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

Devolver un recuento de elementos de trabajo

Por ejemplo, la siguiente consulta con ámbito de proyecto devolverá el recuento de elementos de trabajo para un proyecto específico:

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

Devolver las áreas definidas para un proyecto

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

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

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

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

Uso de la opción $expand aplicación

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

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

https://analytics.dev.azure.com/{OrganizationName}/ProjectA/_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 'ProjectA'
  &$expand=Parent($filter=ProjectName eq 'ProjectA')

Consultas de ámbito de la organización

La dirección URL base para las consultas de nivel de organización es la siguiente:

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

Cuando se usa una consulta de ámbito de organización con una $expand opción, debe proporcionar otro filtro.

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

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq 'ProjectA'
  &$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 'ProjectA'
  &$expand=Children($filter=Project/ProjectName eq 'ProjectA')

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 'ProjectA'
  &$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 'ProjectA'
  &$expand=Parent($filter=Project/ProjectName eq 'ProjectA')

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.

Project de seguridad de nivel de servicio

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

Los any filtros o se aplican a la entidad base en all$expand . Para los filtros basados en Project, se omite explícitamente el filtro cuando se usa $expand :

Por ejemplo, la consulta siguiente:

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

Se interpreta como:

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

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

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

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

El $level uso de 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 'ProjectA')

Analytics no admite ninguna referencia de nivel cruzado para los proyectos que usan $it alias. Por ejemplo, la consulta siguiente hace referencia al projectName del elemento de 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

Artículos relacionados

• Consultar instrucciones