Consultas com escopo de projeto e organização

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

Usando o Analytics for Azure DevOps, você pode construir consultas com escopo para um projeto, uma organização ou coleção. Você pode executar essas consultas diretamente em seu navegador ou no Power BI.

As consultas de escopo do projeto ajudam a responder perguntas sobre um único projeto, enquanto as consultas de escopo de organização e coleção permitem que você responda a perguntas que cruzam os limites do projeto. As consultas com escopo de organização e coleta 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.

Nota

O serviço Analytics é automaticamente ativado e suportado na produção para todos os Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço Analytics estão geralmente disponíveis. Recomendamos a sua utilização e solicitamos que nos envie os seus comentários. Os dados disponíveis dependem da versão. A última versão suportada é v2.0, e a versão de pré-visualização mais recente é v4.0-preview. Para obter mais informações, consulte o artigo Controlo de Versões da API OData.

Pré-requisitos

• Acesso: Ser membro de um projeto com pelo menos acesso Básico .
• Permissões: por predefinição, os membros do projeto têm permissão para consultar o Analytics e criar vistas.
• Para obter mais informações sobre outros pré-requisitos relacionados com a ativação de serviços e funcionalidades e atividades gerais de monitorização de dados, consulte Permissões e pré-requisitos para aceder ao Analytics.

Importante

Se você não tiver acesso a todos os projetos em uma organização, é recomendável aplicar um filtro de projeto a todas as suas consultas. Ao extrair dados para ferramentas de cliente, como Power BI ou Excel, usar a sintaxe do caminho do projeto é a melhor maneira de garantir que todos os seus dados sejam restringidos pelo projeto determinado. Recomendamos que você use consultas com escopo da organização ou escopo da coleção somente quando precisar relatar dois ou mais projetos.

Consultas com âmbito do projeto

Você constrói uma consulta inserindo a URL OData em um navegador da Web compatível.

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

Nuvem (Serviços de DevOps do Azure

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

Nos exemplos fornecidos, substitua {OrganizationName} e {ProjectName} pelos nomes da sua organização e projeto que você deseja consultar.

Local (Azure DevOps Server

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

Nos exemplos fornecidos, faça as seguintes substituições:

• analytics.dev.azure.com com {ServerName}:{Port}/tfs/
• {CollectionName} com o nome da coleção de projetos (o padrão é DefaultCollection)
• {ProjectName} com o nome do projeto que você deseja consultar.

Nota

Os exemplos restantes fornecidos neste artigo são baseados em uma URL dos Serviços de DevOps do Azure. Você precisará substituir a URL do Servidor de DevOps do Azure para exercer os exemplos.

Devolver uma contagem de itens de trabalho

Por exemplo, a seguinte consulta com escopo de projeto 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 7126 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 caminhos de área do projeto

Da mesma forma, a seguinte seqüência de caracteres de consulta retornará as áreas para um projeto específico:

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

É equivalente ao seguinte filtro em uma consulta com 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 um caminho de área, pois nenhum $select operador é 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 caminho 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

Utilização da opção $expand

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

Por exemplo, o seguinte filtro com escopo de projeto:

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

é filtrado automaticamente para reforçar a segurança:

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

Consultas com âmbito 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 usar uma consulta com escopo da organização com uma $expand opção, você deve fornecer outro filtro.

Por exemplo, a seguinte consulta com 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

Requer outro filtro para verificar se as crianças estão limitadas 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 $expand opção 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

Ele requer 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 outro filtro, 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 ao nível do projeto

O Google Analytics tem mais algumas restrições na sintaxe de consulta relacionada à segurança no nível do projeto.

Os any filtros ou all aplicam-se à entidade base em um $expandarquivo . Para filtros baseados em um projeto, ignoramos explicitamente o filtro 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}')

É interpretado 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 contornar a restrição, você precisa 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 só é suportado se você tiver acesso a todos os projetos da coleção ou ao usar uma consulta com escopo de projeto:

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

O Google Analytics não oferece suporte a nenhuma referência de nível cruzado para projetos que usam a $it cláusula. Como exemplo, a consulta a seguir faz referência ao alias de uso $it do ProjectName item de trabalho raiz, que não é suportado:

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

Próximo passo

Consultar dados agregados

Artigos relacionados

• Orientações de consulta