Construir consultas OData para Análise no Azure DevOps

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

A Análise, a plataforma de relatórios do Azure DevOps, pode responder a perguntas quantitativas sobre o estado passado ou presente de seus projetos. O Analytics dá suporte a consultas OData de seus metadados e dados do conjunto de entidades. Você pode aprender sobre o modelo de dados e o processo de consulta executando consultas simples no navegador da Web.

Observação

O OData, um protocolo no nível do aplicativo para interagir com dados por meio de interfaces REST (Transferência de Estado Representacional), dá suporte à descrição, edição e consulta de modelos de dados. O EDM (Modelo de Dados de Entidade) ou metadados descreve as informações disponíveis no Analytics, incluindo as entidades, os tipos de entidade, as propriedades, as relações e as 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:

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

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

Pré-requisitos

Categoria	Requirements
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 Análise 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.

Consultar os metadados

A análise expõe o modelo de entidade OData na URL de metadados formada acrescentando $metadata à URL raiz do serviço. A análise fornece raízes de serviço para projetos do Azure DevOps ou organizações e coleções inteiras.

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

Tipos de entidade e conjuntos de entidades
Propriedades e propriedades de navegação
Chaves alternativas
Listas enumeradas
Conjuntos de entidades
Contêineres
Funções de filtro, com Org.OData.Capabilities.V1.FilterFunctions
Agregações suportadas, com Org.OData.Aggregation.V1.ApplySupported
Tipo de suporte por lote, com Org.OData.Capabilities.V1.BatchSupportType

Para consultar os metadados de uma organização ou projeto hospedado na nuvem, insira a sintaxe de URL a seguir 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 de Análise, seguida do nome da organização, nome do projeto, versão do OData e da designação $metadata.

Para consultar os metadados de um servidor, insira a sintaxe de URL a seguir em um navegador da Web. Substitua <ServerName>e <CollectionName><ProjectName> pelos nomes do servidor, da coleção e do 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 nomeado fabrikam-devops e seu DefaultCollection.

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

Observação

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

Interpretar a resposta de metadados

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

Dica

Dependendo do navegador, esse arquivo pode não ser formatado de maneira legível por humanos. Você pode encontrar um formatador XML online gratuito por meio de uma pesquisa na Web.

Os metadados de análise definem os esquemas principais a seguir.

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

<?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 OData do Analytics.

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 em cada EntityType. Você pode usar entidades relacionadas para especificar mais filtros, como caminhos de iteração, caminhos de área ou equipes.

O snippet 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 Analytics capturados para o tipo de entidade, como Revisions, Linkse ChildrenParent.

<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 a relação de metadados da entidade, consulte os seguintes artigos:

Consulta de conjuntos de entidades

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

Use a sintaxe de URL a seguir para consultar uma EntitySetdeterminada, como WorkItems, WorkItemSnapshotou PipelineRuns. Substitua <EntitySet> pela entidade que você deseja pesquisar e <QueryOptions> por 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 a contagem 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 itens de trabalho 1399.

{
"@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 servidor DefaultCollection do 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 trabalho 1399.

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

Observação

Para evitar atingir os limites de uso, inclua sempre uma cláusula $select ou $apply em sua consulta. Se você 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 instrução select no conjunto de entidades que retorna todas as colunas e todas as linhas. Se você tiver um grande número de registros, a consulta poderá levar vários segundos. Se você 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 da entidade definida à 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 da fabrikam organização.

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

A análise 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 a seguir mostra a URL de consulta para o DefaultCollection no servidor fabrikam.

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 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`, ou `expandconcat`. Para obter exemplos, consulte Agregar dados de acompanhamento de trabalho usando o Analytics.
`$compute`	Define as propriedades computadas em uma `$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 nos quais a expressão é avaliada como `true` na resposta. Os recursos onde a expressão é avaliada como `false` ou `null`, ou onde as propriedades de referência estão indisponíveis devido às 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 no escopo do projeto e da organização.
`$select`	Especifica as colunas necessárias.
`$expand`	Agrupa outras opções de consulta. Cada um `expandItem` é avaliado em relação à entidade que contém a propriedade de navegação ou fluxo que está sendo expandida. Forneça uma lista separada por vírgulas de opções de consulta, entre parênteses, para o nome da propriedade de navegação. As opções de consulta do sistema permitidas são `$filter`, `$select`, `$orderby`, `$skip$top`, , `$count`, , `$search`e `$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`	Retorna apenas o número de registros. 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 Analytics.

Dica

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

Entender a paginação do lado do servidor

A análise força a paginação quando os resultados da consulta excedem 10.000 registros. Nesse caso, você obtém a primeira página de dados e um link a seguir para obter a próxima página. Ferramentas de clientes, como o Power BI Desktop ou o Excel, seguem @odata.nextLink e carregam automaticamente todos os registros necessários ao puxar 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óxima etapa

Construir consultas básicas usando a Análise OData

Comentários

Esta página foi útil?

Last updated on 2025-12-17

Compartilhar via

Construir consultas OData para Análise no Azure DevOps

Pré-requisitos

Consultar os metadados

Interpretar a resposta de metadados

Obter entidades e propriedades de navegação relacionadas

Consulta de conjuntos de entidades

Exemplo: consultar um conjunto de entidades específico

Usar opções de consulta

Entender a paginação do lado do servidor

Próxima etapa

Conteúdo relacionado

Comentários

Recursos adicionais