Consultas dentro do escopo do projeto e da organização

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

Você pode construir consultas com escopo para um projeto, uma organização ou coleção utilizando o Analytics para Azure DevOps. Essas consultas podem ser executadas diretamente no navegador ou no Power BI.

As consultas de escopo de projeto ajudam a responder a perguntas sobre um único projeto, enquanto as consultas com escopo de organização e de coleção permitem responder a perguntas que atravessam os limites do projeto. As consultas com escopo de organização e de coleção exigem permissões de usuário mais amplas ou restrições de escopo cuidadosas, para garantir que sua consulta não seja bloqueada devido à falta de permissões.

Pré-requisitos

Consultas no escopo do projeto

Para construir uma consulta, insira a URL do OData em um navegador da Web compatível.

A URL de base para uma consulta de OData no nível do projeto é mostrada na sintaxe a seguir.

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

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

Retornar uma contagem de itens de trabalho

Por exemplo, a consulta no escopo de projeto a seguir retorna a contagem de itens de trabalho para um projeto específico.

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

Por exemplo, uma consulta do projeto Fabrikam Fiber retorna uma contagem de 7.126 itens de trabalho. Os itens de trabalho excluídos não são incluídos na contagem.

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

7126

Retornar Área e Caminhos do projeto

Da mesma forma, a seguinte cadeia de caracteres de consulta retorna as áreas de um projeto específico:

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

É equivalente ao seguinte filtro em uma consulta dentro do escopo da organização:

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

Por exemplo, uma consulta do projeto Fabrikam Fiber retorna todas as propriedades definidas para uma Área Caminho, já que nenhum operador $select é aplicado na consulta.

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

O exemplo a seguir mostra os dados retornados para um único Área Caminho.

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 da opção $expand

Ao usar uma consulta dentro do escopo do projeto com uma opção $expand, não é necessário fornecer outros filtros.

Por exemplo, o seguinte filtro no escopo do projeto:

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

É filtrado automaticamente para impor a segurança:

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

Consultas no escopo da organização

A URL base para consultas no nível da organização é a mostrada:

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

Ao utilizar uma consulta dentro do escopo da organização com uma opção $expand, é necessário fornecer outro filtro.

Por exemplo, a seguinte consulta dentro do escopo da organização, que usa um $expand para recuperar os filhos de todos os itens de trabalho.

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

Ela exige outro filtro para verificar se os filhos se limitam ao projeto especificado:

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

Retornar o pai de todos os itens de trabalho

A consulta a seguir, que usa uma opção $expand para recuperar o pai de todos os itens de trabalho.

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

Ela exige outro filtro para verificar se o pai está limitado ao projeto especificado:

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

Sem o filtro adicional, a solicitação falhará se o pai de qualquer item de trabalho fizer referência a itens de trabalho em um projeto ao qual você não tem acesso de Leitura.

Restrições de segurança no nível do projeto

O Analytics tem algumas outras restrições na sintaxe de consulta relacionadas à segurança no nível de projeto.

Os filtros any ou all se aplicam à entidade base em um $expand. No caso de filtros baseados em um projeto, ignoramos o filtro explicitamente ao usar um $expand:

Por exemplo, a seguinte consulta:

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

É interpretada como:

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

E falhará se você não tiver acesso a todos os projetos.

Para solucionar a restrição, é necessário adicionar uma expressão extra no $filter:

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

O uso $level somente será compatível se você tiver acesso a todos os projetos na coleção ou quando utilizar uma consulta no escopo do projeto:

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

O Analytics não é compatível com nenhuma referência de nível cruzado para projetos que empregam a cláusula $it. Por exemplo, a consulta a seguir faz referência ao ProjectName do item de trabalho raiz utilizando o alias $it, que não é compatível:

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

Próxima etapa

Artigos relacionados

• Diretrizes de consulta