Metadados OData do Analytics

  • Artigo

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

Entender os metadados associados ao modelo de entidade do Analytics é um pré-requisito para consultar programaticamente o modelo de dados para Análise. Os metadados OData são uma descrição legível por computador do modelo de entidade projetado para habilitar o consumo do cliente.

Observação

"O Protocolo open data (OData) é um protocolo de acesso a dados criado em protocolos principais como HTTP e metodologias comumente aceitas, como REST para a Web. Há vários tipos de bibliotecas e ferramentas que podem ser usadas para consumir serviços OData." - Tutorial Básico da Organização OData.

Neste artigo, você aprenderá a:

  • Consultar os metadados em um projeto específico
  • Consultar os metadados em uma organização
  • Identificar as chaves, as propriedades e as propriedades de navegação associadas a uma entidade
  • Identificar os recursos do ponto de extremidade OData do Analytics

Para obter descrições detalhadas de todos os elementos OData, consulte Modelo OData. Para obter informações sobre como consultar os metadados, consulte Construir consultas OData para Análise.

Observação

O serviço de Análise é habilitado automaticamente e tem suporte em produção para todos os Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão em disponibilidade geral. Recomendamos que você o use e nos envie comentários. Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0e a versão prévia mais recente é v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Observação

O serviço Analytics é instalado automaticamente e tem suporte em produção para todas as novas coleções de projetos para Azure DevOps Server 2020 e versões posteriores. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão em disponibilidade geral. Recomendamos que você o use e nos envie comentários. Se você atualizou do Azure DevOps Server 2019, poderá instalar o serviço de Análise durante a atualização.

Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0e a versão prévia mais recente é v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Observação

O serviço de Análise está em versão prévia para Azure DevOps Server 2019. Você pode habilitá-lo ou instalá-lo para uma coleção de projetos. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão em Versão Prévia. Recomendamos que você o use e nos envie comentários.

Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0e a versão prévia mais recente é v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Conjuntos de entidades e tipos de entidade

As entidades são os principais tipos de identidade em um modelo de dados. Os conjuntos de entidades são coleções nomeadas de entidades. Por exemplo, Projects é um conjunto de entidades que contém Project entidades. Uma entidade pode ser membro de no máximo um conjunto de entidades.

EntitySets e EntityTypes definem cada uma das entidades no modelo de Análise, incluindo propriedades e relações. Os tipos de entidade definem as propriedades nomeadas e as relações de uma entidade. Os tipos de entidade podem derivar por herança única de outros tipos de entidade. A chave de um tipo de entidade é formada a partir de um subconjunto de suas propriedades primitivas.

O exemplo a seguir mostra os metadados associados ao Project tipo de entidade.

<EntityType Name="Project">
  <Key>
    <PropertyRef Name="ProjectSK"/>
  </Key>
  <Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
  <Property Name="ProjectId" Type="Edm.Guid" Nullable="false">
    <Annotation Term="Display.DisplayName" String="Project Id"/>
  </Property>
  <Property Name="ProjectName" Type="Edm.String" Nullable="false">
    <Annotation Term="Display.DisplayName" String="Project Name"/>
  </Property>
  <Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
  <Property Name="ProjectVisibility" Type="Microsoft.VisualStudio.Services.Analytics.Model.ProjectVisibility">
    <Annotation Term="Display.DisplayName" String="Project Visibility"/>
  </Property>
  <NavigationProperty Name="Areas" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Area)"/>
  <NavigationProperty Name="Iterations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Iteration)"/>
  <NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
</EntityType>

simétricas

Keys defina as propriedades de entidade disponíveis para uso como uma propriedade navigational.

<Key>
   <PropertyRef Name="ProjectSK"/>
</Key>

Propriedades

O conjunto de 'Propriedades de entidade disponíveis para consulta. As anotações representam outros detalhes sobre uma determinada propriedade.

Qualquer propriedade do Analytics que deve ser visível para os usuários finais é anotada com um DisplayName.

<Property Name="ProjectSK" Nullable="false" Type="Edm.Guid"/>
<Property Name="ProjectId" Nullable="false" Type="Edm.Guid">
   <Annotation String="Project Id" Term="Display.DisplayName"/>
</Property>
<Property Name="ProjectName" Nullable="false" Type="Edm.String">
   <Annotation String="Project Name" Term="Display.DisplayName"/>
</Property>

ReferenceName é outra anotação comum usada para definir o identificador do sistema para uma propriedade específica.

<Property Name="State" Type="Edm.String">
   <Annotation String="State" Term="Display.DisplayName"/>
   <Annotation String="System.State" Term="Ref.ReferenceName"/>
</Property>

Consultar uma entidade individual é útil. Eventualmente, você provavelmente desejará filtrar ou expandir detalhes de outra Entidade. Para fazer isso, você precisa entender como usar as Propriedades de Navegação do modelo de entidade.

Um NavigationaProperty com um tipo de coleção representa uma relação muitos para muitos no modelo.

<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>

ReferentialConstraints vincule as propriedades de navegação a uma chave específica de uma entidade, representando uma relação muitos para um no modelo.

<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project">
   <ReferentialConstraint ReferencedProperty="ProjectSK" Property="ProjectSK"/>
</NavigationProperty>

Contêineres (recursos OData)

Entitysets

As entidades são os principais tipos de identidade em um modelo de dados. Os conjuntos de entidades são coleções nomeadas de entidades. Por exemplo, WorkItems e WorkItemRevisions estão EntitySets dentro do EntityContainer chamado Container. Uma entidade pode ser membro de no máximo um conjunto de entidades. Os conjuntos de entidades fornecem os pontos de entrada primários no modelo de dados e representam uma coleção de entidades e associações de propriedade navigational associadas e anotações.

A sintaxe a seguir indica o modelo de dados do Projects conjunto de entidades. Para obter uma descrição de cada conjunto de entidades, consulte Modelo de dados para Análise.

<EntitySet Name="Projects" EntityType="Microsoft.VisualStudio.Services.Analytics.Model.Project">
  <NavigationPropertyBinding Path="Areas" Target="Areas"/>
  <NavigationPropertyBinding Path="Iterations" Target="Iterations"/>
  <NavigationPropertyBinding Path="Teams" Target="Teams"/>
  <Annotation Term="Org.OData.Display.V1.DisplayName" String="Projects"/>
</EntitySet>

Funcionalidades

Os recursos definem o conjunto de funções compreendido pelo ponto de extremidade OData de Análise.

<Annotation Term="Org.OData.Capabilities.V1.FilterFunctions">
   <Collection>
      <String>contains</String>
      <String>endswith</String>
      <String>startswith</String>
      <String>length</String>
      <String>indexof</String>
      <String>substring</String>
      <String>tolower</String>
      <String>toupper</String>
      <String>trim</String>
      <String>concat</String>
      <String>year</String>
      <String>month</String>
      <String>day</String>
      <String>hour</String>
      <String>minute</String>
      <String>second</String>
      <String>fractionalseconds</String>
      <String>round</String>
      <String>floor</String>
      <String>ceiling</String>
      <String>date</String>
      <String>time</String>
      <String>isof</String>
      <String>cast</String>
   </Collection>
</Annotation>

Agregações

As anotações de agregação definem o conjunto de transformações compreendidas pelo ponto de extremidade OData do Analytics.

<Annotation Term="Org.OData.Aggregation.V1.ApplySupported">
   <Record>
      <PropertyValue Property="Transformations">
         <Collection>
            <String>aggregate</String>
            <String>filter</String>
            <String>groupby</String>
            <String>compute</String>
            <String>expand</String>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="CustomAggregationMethods ">
         <Collection>
           <String>ax.ApproxCountDistinct</String>
           <String>ax.StandardDeviation</String>
           <String>ax.StandardDeviationP</String>
           <String>ax.Variance</String>
           <String>ax.VarianceP</String>
         </Collection>
      </PropertyValue>
   </Record>
</Annotation>

<Annotation Term="Org.OData.Capabilities.V1.BatchSupportType" Bool="true"/>
<Annotation Term="Org.OData.Capabilities.V1.BatchSupportType">
   <Record>
      <PropertyValue Property="Supported" Bool="true"/>
      <PropertyValue Property="ContinueOnErrorSupported" Bool="false"/>
      <PropertyValue Property="ReferencesInRequestBodiesSupported" Bool="false"/>
      <PropertyValue Property="ReferencesAcrossChangeSetsSupported" Bool="false"/>
      <PropertyValue Property="EtagReferencesSupported" Bool="false"/>
   </Record>
</Annotation>

Próximas etapas

Modelo de dados para Análise