Consultas no escopo do projeto e da organização

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

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

As consultas de escopo do projeto ajudam a responder a perguntas sobre um único projeto, enquanto as consultas com 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 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.

Observação

O serviço do Analytics é habilitado automaticamente e tem suporte na produção para todos os Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço do Analytics estão em disponibilidade geral. Encorajamos você a usá-lo e nos dar feedback. Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0, e a versão prévia mais recente é v4.0-preview. Para obter mais informações, confira Sobre o controle de versão da API OData.

Pré-requisitos

• Acesso: ser membro de um projeto com pelo menos acesso básico.
• Permissões: por padrão, os membros do projeto têm permissão para consultar o Analytics e criar exibições.
• Para obter mais informações sobre outros pré-requisitos relacionados à ativação de serviços e recursos e atividades gerais de rastreamento de dados, consulte Permissões e pré-requisitos para acessar o 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 restritos pelo projeto fornecido. Recomendamos que você use consultas no escopo da organização ou no escopo da coleção somente quando precisar relatar dois ou mais projetos.

Consultas no escopo do projeto

Você constrói uma consulta inserindo a URL OData em um navegador da Web com suporte.

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

Nuvem (Azure DevOps Services

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

Nos exemplos fornecidos, substitua {OrganizationName} e {ProjectName} pelos nomes da organização e do 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} pelo nome da coleção de projetos (o padrão é DefaultCollection)
• {ProjectName} pelo nome do projeto que você deseja consultar.

Observação

Os exemplos restantes fornecidos neste artigo são baseados em uma URL do Azure DevOps Services. Você precisará substituir em sua URL Azure DevOps Server para exercitar os exemplos.

Retornar uma contagem de itens de trabalho

Por exemplo, a consulta no escopo do 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 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 string de consulta retornará 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 no 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

Uso da opção $expand

Ao usar uma consulta no escopo do projeto com uma $expand opção, você não precisa 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 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 no escopo da organização

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

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

Ao usar uma consulta no escopo da organização com uma $expand opção, você deve fornecer outro filtro.

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

Ele requer outro filtro para verificar se os filhos estão limitados 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 no nível do projeto

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

Os any filtros ou all se aplicam à entidade base em um $expand. 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ó terá suporte se você tiver acesso a todos os projetos na coleção ou ao usar uma consulta no escopo do projeto:

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

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

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

Próxima etapa

Consultar dados agregados

Artigos relacionados

• Diretrizes de consulta