Construir consultas OData para Analytics no Azure DevOps

  • Artigo

Serviços de DevOps do Azure | 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 dos seus projetos. O Analytics suporta consultas OData de seus metadados e dados do conjunto de entidades. Ao exercitar consultas simples a partir 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 no local
  • Como consultar metadados do Google Analytics
  • Como consultar o Analytics OData 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 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.

Nota

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

Pré-requisitos

  • Para visualizar dados do Google 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 o Google Analytics e definir exibições do Google Analytics.
  • Para saber mais sobre outros pré-requisitos relacionados à ativação de serviços e recursos e atividades gerais de controle de dados, consulte Permissões e pré-requisitos para acessar o Google 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 entidades e conjuntos de entidades
  • Propriedades e propriedades de navegação
  • Chaves substitutas
  • Listas enumeradas
  • Conjunto de Entidades
  • Contentores
  • 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 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

Nota

A versão mais recente do Analytics OData é v4.0-preview. Você pode usar esta 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 análise.

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. Utilize a função de pesquisa do seu navegador para encontrar informações específicas da entidade de interesse.

Gorjeta

Dependendo do navegador que estiver a utilizar, este ficheiro pode ou não estar formatado de forma legível. Se não estiver formatado, pode encontrar um formatador XML online gratuito através de uma pesquisa no navegador da Web.

Os dois esquemas principais definidos nos metadados do Google 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 filtro, transformação e agregação personalizadas OData suportadas. Para obter mais informações, consulte Metadados do Analytics OData.

<?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. Estes estão listados nos metadados em como EntityType a Property ou NavigationalProperty. Você usa 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 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, 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"/>
...

Componentes de URL para entidades de consulta

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.

O URL a seguir é usado para consultar um EntitySetarquivo , 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
   }
 ]
}

Nota

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 tiver um grande número de registos, poderá demorar vários segundos. Se você tiver mais de 10.000 itens de trabalho, a paginação orientada por servidor será imposta.

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

Para obter informações sobre a propriedade e o relacionamento dos metadados da 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, /Areas, ou /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 Analytics retorna os nomes dos 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 Notas
$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 Google Analytics.
$compute Uma função OData suportada que você pode especificar para definir propriedades computadas que podem ser usadas em um $select,$filter, ou $orderby expressão.
$filter Use para filtrar a lista de recursos que são retornados. A expressão especificada com é avaliada para cada recurso na coleção, e somente os itens em $filter que a expressão é avaliada como true são incluídos na resposta. Recursos para os quais a expressão é avaliada como false ou nulo, 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 Google 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 de 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 expandItem um é avaliado em relação à entidade que contém a propriedade de navegação ou fluxo que está sendo expandida.

Lista de opções de consulta separada por ponto-e-vírgula, entre parênteses, para o nome da propriedade de navegação. As opções de consulta do sistema permitidas são $filter, , , $orderby, $top$skip, $count, $search, e $expand$select.
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=truepara 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 $apply cláusulas $filter e 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 combinada. Cada uma dessas opções funciona muito bem por si só, mas combiná-las pode levar a alguns resultados inesperados.

Impor a 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 a seguir para obter a próxima página. O link (@odata.nextLink) pode ser encontrado no final da saída JSON. Parecerá 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"
}

Nota

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óximos passos

Construa consultas básicas usando o OData Analytics