Consultas com escopo de projeto e 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 ou uma organização ou coleção. Você pode executar essas consultas diretamente em seu navegador ou no Power BI.

As consultas de escopo de projeto ajudam a responder a perguntas sobre um único projeto, enquanto as consultas de escopo de organização e coleção permitem que você responda a perguntas que ultrapassam 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 Analytics é automaticamente habilitado e suportado na produção para todos os Serviços de DevOps do Azure. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão disponíveis para o público em geral. Nós encorajamos você a usá-lo e nos dar feedback. Os dados disponíveis dependem da versão. A versão mais recente suportada é v2.0, e a versão de visualização mais recente é v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Pré-requisitos

• Para exibir dados do Analytics e consultar o serviço, você precisa ser membro de um projeto com acesso básico ou superior. Por padrão, todos os membros do projeto recebem permissões para consultar Análise e definir exibições do Analytics.
• Para saber mais sobre outros pré-requisitos relacionados à habilitação de serviços e recursos e atividades gerais de acompanhamento 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 o Power BI ou o Excel, usar a sintaxe do caminho do projeto é a melhor maneira de garantir que todos os seus dados sejam restritos pelo projeto especificado. Recomendamos que você use consultas com escopo de organização ou escopo de coleção somente quando precisar relatar dois ou mais projetos.

Consultas com escopo de 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.

Cloud (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 (Servidor de DevOps do Azure

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 do projeto (o padrão é DefaultCollection)
• {ProjectName} com o nome do projeto que você deseja consultar.

Observação

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.

Retornar uma contagem de itens de trabalho

Por exemplo, a consulta com 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 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 da área do projeto

Da mesma forma, a seguinte cadeia de caracteres 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 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 como 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 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 escopo da organização

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

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

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

Por exemplo, a seguinte consulta com escopo de 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 em nível de projeto

O Google 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 $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 na 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 ProjectName de uso $it do 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óxima etapa

Consultar dados agregados

Artigos relacionados

• Diretrizes de consulta