Construir consultas OData para Analytics no Azure DevOps

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

O Analytics, a plataforma de relatórios do Azure DevOps, pode responder a perguntas quantitativas sobre o estado passado ou presente dos seus projetos. O Analytics suporta consultas de OData aos seus metadados e aos dados do conjunto de entidades. Você pode aprender sobre o modelo de dados e o processo de consulta executando consultas simples a partir do seu navegador da Web.

Nota

OData, um protocolo de nível de aplicativo para interagir com dados por meio de interfaces REST (Representational State Transfer), suporta a descrição, edição e consulta de modelos de dados. O Modelo de Dados de Entidade (EDM) ou metadados descreve as informações disponíveis do Analytics, incluindo as entidades, tipos de entidade, propriedades, relacionamentos e enumerações que você usa para consultar os dados para criar relatórios. Para obter uma visão geral do OData, consulte Bem-vindo ao OData.

Este artigo explica como:

Construa uma consulta OData do Google Analytics.
Metadados do Query Analytics.
Query Analytics OData para um conjunto de entidades.
Use as opções de consulta na sequência recomendada.
Entender a paginação do lado do servidor.

Você pode consultar o Google Analytics a partir de qualquer navegador da Web compatível. Para outras ferramentas que você pode usar para consultar o Google Analytics, consulte Ferramentas de consulta do Google Analytics.

Pré-requisitos

Categoria	Requerimentos
Níveis de acesso	- Membro do projeto. - Pelo menos acesso básico .
Permissões	Por padrão, os membros do projeto têm permissão para consultar o Google Analytics e criar modos de exibição. 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.

Consultar os metadados

O Google Analytics expõe o modelo de entidade OData na URL de metadados formada anexando $metadata à URL raiz do serviço. O Analytics fornece raízes de serviço para projetos de DevOps do Azure ou organizações e coleções inteiras.

Você pode consultar os metadados para procurar qualquer um dos seguintes elementos de dados:

Tipos de entidades e conjuntos de entidades
Atributos e propriedades de navegação
Chaves substitutas
Listas enumeradas
Conjuntos de entidades
Contentores
Funções de filtro, com Org.OData.Capabilities.V1.FilterFunctions
Agregações suportadas, com Org.OData.Aggregation.V1.ApplySupported
Tipo de suporte de lote, com Org.OData.Capabilities.V1.BatchSupportType

Para consultar os metadados de uma organização ou projeto hospedado na nuvem, insira a seguinte sintaxe de URL em um navegador da Web. Substitua <OrganizationName> e <ProjectName> pelos nomes da organização e do projeto que você deseja consultar. Para retornar todos os metadados de uma organização, não especifique um nome de projeto.

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/$metadata

O exemplo a seguir consulta metadados para a fabrikam organização.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

Na cadeia de caracteres de consulta, analytics.dev.azure.com é a URL raiz do serviço Analytics, seguida pelo nome da organização, nome do projeto, versão OData e $metadata designação.

Para consultar os metadados de um servidor, insira a seguinte sintaxe de URL em um navegador da Web. Substitua <ServerName>, <CollectionName> e <ProjectName> pelos nomes do servidor, coleção e projeto que você deseja consultar. Para retornar todos os metadados de uma coleção, não especifique um nome de projeto.

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/$metadata

O exemplo a seguir consulta os metadados de um servidor chamado fabrikam-devops e seu DefaultCollection.

https://fabrikam-devops/DefaultCollection/_odata/v4.0-preview/$metadata

Nota

A versão mais recente do Analytics OData é v4.0-preview. Você pode usar esta versão para todas as consultas no Azure DevOps. Para obter mais informações sobre versões do Google Analytics e dados disponíveis, consulte Modelo de dados para análise.

Interpretar a resposta de metadados

O Google Analytics retorna um arquivo XML do modelo de dados. Use a função de pesquisa do seu navegador para encontrar informações para a sua entidade de interesse.

Gorjeta

Dependendo do seu navegador, esse arquivo pode não ser formatado de forma legível por humanos. Você pode encontrar um formatador XML on-line gratuito através de uma pesquisa na web.

Os metadados do Google Analytics definem os seguintes esquemas principais.

Microsoft.VisualStudio.Services.Analytics.Model define os tipos de entidade e tipos enumerados e seus membros.
O Default esquema define os contêineres de entidade e os conjuntos de entidades e as funções de filtro, transformação e agregação personalizada OData suportadas.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Para obter mais informações, consulte Metadados do Analytics OData.

Todos os tipos de entidade têm propriedades e propriedades de navegação que você pode usar para filtrar suas consultas. Essas propriedades são listadas nos metadados como Property ou NavigationProperty sob cada EntityType. Você pode usar entidades relacionadas para especificar mais filtros, como caminhos de iteração, caminhos de área ou equipes.

O trecho de código a seguir mostra uma exibição parcial dos metadados da WorkItem entidade. As propriedades correspondem a campos de item de trabalho e dados específicos capturados pelo Analytics, como LeadTimeDays e CycleTimeDays. As propriedades de navegação correspondem a outros conjuntos de entidades e dados específicos do Google Analytics capturados para o tipo de entidade, como Revisions, Links, Childrene Parent.

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

Para obter informações sobre a propriedade e o relacionamento dos metadados da entidade, consulte os seguintes artigos:

Consultar conjuntos de entidades

Para consultar dados do Google Analytics e criar relatórios, normalmente você consulta um conjunto de entidades. Para obter uma visão geral das entidades suportadas, consulte Metadados do Analytics OData.

Use a seguinte sintaxe de URL para consultar um EntitySet específico, tal como WorkItems, WorkItemSnapshot, ou PipelineRuns. Substitua <EntitySet> pela entidade que você deseja pesquisar e <QueryOptions> pelas opções de consulta, conforme descrito em Usar opções de consulta.

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

O exemplo a seguir consulta o número de itens de trabalho no projeto Fabrikam Fiber da organização fabrikam.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

A consulta de exemplo retorna resultados mostrando uma contagem de 1399 itens de trabalho.

{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
   "@odata.id": null,
   "Count": 1399
   }
 ]
}

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

O exemplo a seguir consulta a contagem de itens de trabalho no projeto Fabrikam no DefaultCollection do servidor fabrikam.

https://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

A consulta de exemplo retorna os seguintes resultados de itens de 1399 trabalho.

{
"@odata.context": "http://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
      "@odata.id": null,
      "Count": 44
   }
 ]
}

Nota

Para evitar limites de utilização, inclua sempre uma cláusula $select ou $apply na sua consulta. Se não incluir uma cláusula $select ou $apply, receberá um aviso como VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060.

Omitir uma cláusula $select ou $apply é equivalente a executar uma declaração select no conjunto de entidades que retorna todas as colunas e linhas. Se você tiver um grande número de registros, a consulta pode levar vários segundos. Se tiver mais de 10.000 itens, a paginação do lado do servidor é aplicada.

Exemplo: Consultar um conjunto de entidades específico

Para consultar um conjunto de entidades específico, como WorkItems, Areasou Projects, adicione o nome do conjunto de entidades à consulta. Para obter uma lista completa de conjuntos de entidades, consulte Modelo de dados para análise.

Por exemplo, você pode obter uma lista de projetos definidos para sua organização consultando Projects e selecionando para retornar a ProjectName propriedade. O exemplo a seguir mostra a URL de consulta para a fabrikam organização.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

O Google Analytics retorna os nomes dos projetos na fabrikam organização.

{
@odata.context": "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

Por exemplo, você pode obter uma lista de projetos definidos para seu servidor e coleção consultando Projects e selecionando para retornar a ProjectName propriedade. O exemplo seguinte DefaultCollection mostra a URL de consulta para o fabrikam no servidor.

https://fabrikam/DefaultCollection/_odata/v4.0-preview/Projects?$select=ProjectName

O exemplo retorna os três nomes de projeto a seguir.

{
"@odata.context": "http://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
"value": [
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Florida"
   }
 ]
}

Usar opções de consulta

As opções de consulta são parâmetros de cadeia de caracteres de consulta que ajudam a controlar a quantidade de dados que estão sendo retornados para um recurso. Especifique as opções de consulta na ordem listada na tabela a seguir.

Opção de consulta	Description
`$apply`	Aplica uma transformação a uma consulta, como `filter`, `groupby`, `aggregate`, `compute`, `expand`ou `concat`. Para obter exemplos, consulte Agregar dados de acompanhamento de trabalho usando o Google Analytics.
`$compute`	Define propriedades computadas em um `$select`, `$filter`ou `$orderby` expressão.
`$filter`	Filtra a lista de recursos retornados. A consulta avalia a expressão especificada com `$filter` para cada recurso no escopo da consulta e inclui apenas itens em que a expressão é avaliada como `true` na resposta. Os recursos em que a expressão é avaliada para `false` ou `null`, ou onde as propriedades de referência não estão disponíveis devido a permissões, são omitidos da resposta. Para obter exemplos, consulte Consultar dados de acompanhamento de trabalho usando o Analytics.
`$orderby`	Especifica a sequência na qual retornar registros. Para obter exemplos, consulte Consultar dados de acompanhamento de trabalho usando o Analytics.
`$top`/`$skip`	Limita o número de registros retornados. Para obter exemplos, consulte Consultas com âmbito de projeto e organização.
`$select`	Especifica as colunas necessárias.
`$expand`	Aninha outras opções de consulta. Cada `expandItem` é avaliado relativamente à entidade que contém a propriedade de navegação ou fluxo que está a ser expandida. Forneça, entre parênteses, uma lista de opções de consulta separadas por vírgulas para o nome da propriedade de navegação. As opções de consulta do sistema permitidas são `$filter`, , , `$select`, `$orderby$skip`, `$top`, `$count`, e `$search$expand`. Para obter exemplos, consulte Consultar dados de acompanhamento de trabalho usando o Analytics.
`$skiptoken`	Ignora um número especificado de registros.
`$count` ou `$count=true`	Devolve apenas o número de registos. Enter `$count=true`para retornar uma contagem do registro e dos dados consultados. Para obter exemplos, consulte Agregar dados de acompanhamento de trabalho usando o Google Analytics.

Gorjeta

Evite misturar cláusulas $apply e cláusulas $filter numa só consulta. Para filtrar sua consulta, você pode usar uma $filter cláusula ou uma $apply=filter() cláusula combinada. Ambas as opções funcionam, mas combiná-las em uma única consulta pode levar a resultados inesperados.

Compreender a paginação do lado do servidor

O Google Analytics força a paginação quando os resultados da consulta excedem 10.000 registros. Nesse caso, você recebe a primeira página de dados e um link a seguir para obter a próxima página. Ferramentas de cliente como o Power BI Desktop ou o @odata.nextLink Excel seguem e carregam automaticamente todos os registros necessários ao extrair dados.

Você pode encontrar o @odata.nextLink link no final da saída JSON. O link se parece com a consulta original seguida por $skip ou $skiptoken. Por exemplo:

{
  "@odata.context":"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/WorkItems?$skiptoken=10000"
}

Próximo passo

Construa consultas básicas usando o OData Analytics

Feedback

Esta página foi útil?

Last updated on 2025-12-17

Partilhar via

Construir consultas OData para Analytics no Azure DevOps

Pré-requisitos

Consultar os metadados

Interpretar a resposta de metadados

Obter entidades relacionadas e propriedades de navegação

Consultar conjuntos de entidades

Exemplo: Consultar um conjunto de entidades específico

Usar opções de consulta

Compreender a paginação do lado do servidor

Próximo passo

Conteúdo relacionado

Feedback

Recursos adicionais