Construir consultas OData para Analytics no Azure DevOps

  • Artigo

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

O Analytics, a plataforma de relatórios para o Azure DevOps, pode responder a perguntas quantitativas sobre o estado passado ou presente de seus projetos. O Google Analytics oferece suporte a consultas OData de seus metadados e dados do conjunto de entidades. Ao exercer consultas simples do 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 Google 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 Google Analytics em qualquer navegador da Web compatível. Para obter outras ferramentas que você pode usar para consultar o Google Analytics, consulte Ferramentas de consulta do Google Analytics.

Observação

OData, um protocolo de nível de aplicativo para interagir com dados via interfaces RESTful (onde REST=Representational State Transfer), suporta a descrição de modelos de dados, bem como edição e consulta de dados de acordo com esses modelos. O EDM (Modelo de Dados de Entidade) ou metadados descrevem as informações disponíveis no Google 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.

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.

Componentes de URL para consultar os metadados

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

Você pode procurar qualquer um dos seguintes elementos de dados 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 usada depende se você está consultando dados para os Serviços de DevOps do Azure (nuvem) ou um Servidor de DevOps do Azure local.

Para consultar os metadados de uma organização ou projeto hospedado na nuvem, insira a sintaxe da URL conforme mostrado abaixo em um navegador da Web. Substitua {OrganizationName} e {ProjectName} pelo nome da sua organização e o 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 v4.0-preview. Você pode usar essa versão para todas as consultas no serviço hospedado. Para obter mais informações sobre versões do Google Analytics e dados disponíveis, consulte Modelo de dados para o Google Analytics.

Aqui está um exemplo para a organização fabrikam hospedada nos Serviços de DevOps do Azure.

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

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 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 ele não estiver formatado, você pode encontrar um formatador XML on-line gratuito através 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 conjuntos de entidades e as funções de filtro, 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 a Property ou NavigationalProperty. Use entidades relacionadas para especificar filtros adicionais, como Caminhos de Iteração, Caminhos de Área ou Equipes.

O trecho 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 Google Analytics, como LeadTimeDays e CycleTimeDays. As propriedades de navegação correspondem a outros conjuntos de entidades ou a dados específicos do Google Analytics capturados para o tipo de entidade, como Revisions, LinksChildren, 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 entidades de consulta

Para consultar dados do Google 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.

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 Fibra.

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
   }
 ]
}

Observação

Se você não incluir uma $select cláusula 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." É 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, isso pode levar vários segundos. Se você tiver mais de 10.000 itens de trabalho, a paginação controlada por servidor será imposta.

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

Para obter informações sobre propriedade e relacionamento de metadados de entidade, consulte os seguintes artigos:

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: /WorkItems, /Areasou /Projects. 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. Para a organização fabrikam, a URL é a mostrada abaixo.

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

O Google 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"
   }
 ]
}

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 controle de trabalho usando o Google Analytics.
$compute Uma função OData com suporte que você pode especificar para definir propriedades computadas que podem ser usadas em uma $selectexpressão ou $orderby$filter, ou .
$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 cujas propriedades de referência 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 Google Analytics .
$orderby Use para especificar a sequência na qual os registros devem ser retornados.
Para obter exemplos, consulte Consultar dados de controle de trabalho usando o Google Analytics.
$top/$skip Use para limitar o número de registros retornados.
Para obter exemplos, consulte Consultas de escopo de projeto e 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 , , , , , , e $search$expand. $top$count$skip$orderby$select$filter
Para obter exemplos, consulte Consultar dados de controle de trabalho usando o Google Analytics.
$skiptoken Use para ignorar um número especificado de registros.
$count ou $count=true Digite $count para retornar apenas o número de registros. Enter $count=truepara retornar uma contagem do registro e dos dados consultados.
Para obter exemplos, consulte Agregar dados de controle de trabalho usando o Google Analytics.

Dica

Evite misturar $apply e $filter cláusulas 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 si só, mas combiná-las pode levar a alguns resultados inesperados.

Impor paginação do lado do servidor

O Google Analytics força a paginação quando os resultados da consulta excedem 10000 registros. Nesse caso, você receberá a primeira página de dados e o link para seguir para obter a próxima página. Link (@odata.nextLink) pode ser encontrado no final da saída JSON. Ele será parecido com uma consulta original seguida de $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 o Power BI Desktop ou o 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 o OData Analytics