Construir consultas OData para Análise no Azure DevOps

Artigo
07/17/2024

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

O Analytics, 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. Ao exercitar consultas simples em seu navegador da Web, você pode se familiarizar com o modelo de dados e o processo de consulta.

Neste artigo, você aprenderá o seguinte:

Como construir uma consulta OData do Analytics para a nuvem ou local
Como consultar metadados do Analytics
Como consultar o OData do Analytics para um conjunto de entidades
Quais opções de consulta são suportadas e a sequência recomendada
Quando a paginação do lado do servidor é imposta

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.

Observação

OData, um protocolo de nível de aplicativo para interagir com dados por meio de interfaces RESTful (onde REST=Representational State Transfer), suporta a descrição de modelos de dados, bem como a edição e consulta de dados de acordo com esses modelos. 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.

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.

Componentes de URL para consultar os metadados

O Analytics expõe o modelo de entidade na URL de metadados, formada pela anexação $metadata à URL raiz do serviço. A análise fornece raízes de serviço para um projeto ou uma organização inteira no Azure DevOps.

Você pode pesquisar qualquer um dos elementos de dados a seguir consultando os metadados.

Tipos de entidade e conjuntos de entidades
Propriedades e propriedades de navegação
Chaves alternativas
Listas enumeradas
EntitySet
Contêineres
Funções de filtro (Org.OData.Capabilities.V1.FilterFunctions)
Agregações suportadas (Org.OData.Aggregation.V1.ApplySupported)
Suporte em lote (Org.OData.Capabilities.V1.BatchSupportType)

A URL que você usa depende se você está consultando dados para Azure DevOps Services (nuvem) ou um Azure DevOps Server local.

Nuvem (Azure DevOps Services
Local (Azure DevOps Server

Para consultar os metadados de uma organização ou projeto hospedado na nuvem, insira a sintaxe do URL, conforme mostrado abaixo em um navegador da Web. Substitua {OrganizationName} e {ProjectName} pelo nome da sua organização e pelo nome do projeto que você deseja consultar. Para retornar todos os metadados da organização, não especifique o nome do projeto.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

Observação

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

Aqui está um exemplo para a organização fabrikam hospedada em Azure DevOps Services.

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

Para consultar os metadados de um servidor local, insira a sintaxe da URL, conforme mostrado abaixo em um navegador da Web. Substitua {ServerName}e {CollectionName} {ProjectName} por seus nomes locais. Para retornar todos os metadados da coleção, não especifique o nome do projeto.

https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata 
\_________________________________________________/\______________/\________/
                            |                              |            | 
     On-premises server, collection, project         OData version  return metadata

Observação

Aqui está um exemplo para o servidor nomeado fabrikam-devops e hospedado DefaultCollection em Azure DevOps Server 2022:

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

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 específicas da entidade de interesse.

Dica

Dependendo do navegador que você está usando, esse arquivo pode ou não ser formatado de maneira legível. Se não estiver formatado, você pode encontrar um formatador XML online gratuito por meio de uma pesquisa no navegador da Web.

Os dois esquemas principais definidos nos metadados do Analytics são Microsoft.VisualStudio.Services.Analytics.Model, que define os tipos de entidade e os tipos enumerados e seus membros, e o Default esquema, que define os contêineres de entidade e os conjuntos de entidades e as funções de filtragem, transformação e agregação personalizada OData com suporte. Para obter mais informações, consulte Metadados OData do Analytics.

<?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>

Todos os tipos de entidade estão associados a propriedades e propriedades de navegação. Você pode filtrar suas consultas de conjuntos de entidades usando esses dois tipos de propriedades. Eles estão listados nos metadados sob o EntityType como um Property ou NavigationalProperty. Você usa entidades relacionadas para especificar filtros adicionais, como Caminhos de Iteração, Caminhos de Área ou Equipes.

O snippet de código a seguir fornece uma exibição parcial dos metadados da WorkItem entidade. As propriedades correspondem a um campo de item de trabalho, bem como a dados específicos capturados pelo Analytics, como LeadTimeDays e CycleTimeDays. As propriedades de navegação correspondem a outros conjuntos de entidades ou dados específicos do Analytics capturados para o tipo de entidade, como Revisions, Links, Children, e 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"/>
...

Componentes de URL para consultar 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.

A URL a seguir é usada para consultar um EntitySet, como WorkItems, WorkItemSnapshote PipelineRuns.

Nuvem (Azure DevOps Services
Local (Azure DevOps Server

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

Aqui está um exemplo para a organização fabrikam que retorna a contagem de itens de trabalho definidos para o projeto Fabrikam Fiber.

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

O exemplo retorna 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
   }
 ]
}

Aqui está um exemplo para o servidor fabrikam , DefaultCollection, que retorna a contagem de itens de trabalho definidos para o projeto Fabrikam .

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

O exemplo retorna 1399 itens de trabalho.

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

Observação

Se você não incluir uma $select cláusula or $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." É equivalente a executar uma instrução select no conjunto de entidades e retornar tudo, todas as colunas e todas as linhas. Se você tiver um grande número de registros, pode levar vários segundos. Se você tiver mais de 10.000 itens de trabalho, a paginação controlada pelo servidor será imposta.

Para evitar limites de uso, sempre inclua uma $select cláusula or $apply .

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

Exemplo: consultar um conjunto de entidades específico

Para consultar um conjunto de entidades específico, como , , ou Projects, adicione o nome do conjunto de entidades: /WorkItems, /Areas, ou /Projects. AreasWorkItems Para obter uma lista completa de conjuntos de entidades, consulte Modelo de dados para Análise.

Nuvem (Azure DevOps Services
Local (Azure DevOps Server

Por exemplo, você pode obter uma lista de projetos definidos para sua organização consultando /Projects e selecionando para retornar a ProjectName propriedade. Para a organização fabrikam, a URL é mostrada abaixo.

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

O Analytics retorna os nomes de projeto desses projetos definidos para a organização fabrikam .

{
@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"
   }
 ]
}

Aqui está um exemplo que consulta o Projects conjunto de entidades para retornar os nomes de todos os projetos definidos no DefaultCollection no servidor fabrikam ,

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

O exemplo retorna três nomes de projeto.

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

Opções de consulta

Uma opção de consulta é um conjunto de parâmetros de cadeia de caracteres de consulta aplicados a um recurso que pode ajudar a controlar a quantidade de dados que estão sendo retornados para o recurso na URL.

As opções de consulta devem ser especificadas na ordem listada na tabela a seguir.

Opção de consulta	Observações
`$apply`	Conjunto de transformações que você pode aplicar a uma consulta, como: `filter`, `groupby`, `aggregate`, `compute`, , `expand,` `concat` Para obter exemplos, consulte Agregar dados de acompanhamento de trabalho usando o Analytics.
`$compute`	Uma função OData com suporte que você pode especificar para definir propriedades computadas que podem ser usadas em uma `$select`expressão ,`$filter`or `$orderby` .
`$filter`	Use para filtrar a lista de recursos retornados. A expressão especificada com `$filter` é avaliada para cada recurso na coleção e somente os itens em que a expressão é avaliada como true são incluídos na resposta. Os recursos para os quais a expressão é avaliada como false ou null, ou que fazem referência a propriedades que 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`	Use para especificar a sequência na qual os registros devem ser retornados. Para obter exemplos, consulte Consultar dados de acompanhamento de trabalho usando o Analytics.
`$top`/`$skip`	Use para limitar o número de registros retornados. Para obter exemplos, consulte Consultas no escopo do projeto e da organização.
`$select`/`$expand`	Use `$select` para especificar as colunas necessárias para criar seu relatório. Use `$expand` para aninhar 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. Lista separada por ponto-e-vírgula 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`	Use para ignorar um número especificado de registros.
`$count` ou `$count=true`	Enter `$count` para retornar 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ê tem duas opções: (1) usar uma $filter cláusula ou (2) usar uma $apply=filter() cláusula de combinação. Cada uma dessas opções funciona muito bem por conta própria, mas combiná-las pode levar a alguns resultados inesperados.

Impor paginação do lado do servidor

O Analytics força a paginação quando os resultados da consulta excedem 10000 registros. Nesse caso, você obterá a primeira página de dados e o link a seguir para obter a próxima página. Link (@odata.nextLink) pode ser encontrado no final da saída JSON. Ele se parecerá com uma consulta original seguida por $skip ou $skiptoken. Por exemplo:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

Observação

Ao extrair dados para ferramentas de cliente, como Power BI Desktop ou Excel, as ferramentas seguirão automaticamente o próximo link e carregarão todos os registros necessários.

Próximas etapas

Construir consultas básicas usando a Análise OData

Compartilhar via

Construir consultas OData para Análise no Azure DevOps

Pré-requisitos

Componentes de URL para consultar os metadados

Interpretar a resposta de metadados

Componentes de URL para consultar entidades

Exemplo: consultar um conjunto de entidades específico

Opções de consulta

Impor paginação do lado do servidor

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Construir consultas OData para Análise no Azure DevOps

Pré-requisitos

Componentes de URL para consultar os metadados

Interpretar a resposta de metadados

Entidades relacionadas e propriedades de navegação

Componentes de URL para consultar entidades

Exemplo: consultar um conjunto de entidades específico

Opções de consulta

Impor paginação do lado do servidor

Próximas etapas

Artigos relacionados

Comentários

Recursos adicionais