Metadados OData de Analytics

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

Entender os metadados associados ao modelo de entidade para Analytics é um pré-requisito para consultar programaticamente o modelo de dados para Analytics. Os metadados OData são uma descrição legível por máquina do modelo de entidade projetada para permitir o consumo do cliente.

Observação

"O Open Data Protocol (OData) é um protocolo de acesso a dados construído em protocolos centrais como HTTP e metodologias comumente aceitas como REST para a web. Existem 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, propriedades e 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 o Analytics.

Observação

O serviço do Analytics é habilitado automaticamente e tem suporte na produção para todos os Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço do Analytics estão em disponibilidade geral. Encorajamos você a usá-lo e nos dar feedback. Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0, e a versão prévia mais recente é v4.0-preview. Para obter mais informações, confira Sobre o 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 definir cada uma das entidades no modelo do Analytics, incluindo propriedades e relacionamentos. Os tipos de entidade definem as propriedades e relacionamentos nomeados 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>

Chaves

Keys definir as propriedades da entidade disponíveis para uso como uma propriedade de navegação.

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

Propriedades

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

Qualquer propriedade do Google Analytics que deva 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>

Propriedades de navegação

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

Um NavigationProperty 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)

Conjuntos de entidades

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 nome 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 e anotações de propriedade de navegação associadas.

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

<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 compreendidas pelo ponto de extremidade OData do Analytics.

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

Artigos relacionados

• Modelo de dados para Analytics
• Consultas com escopo de organização e projeto.
• Dados disponíveis no Analytics
• Consultar dados de acompanhamento de trabalho usando o Analytics
• Referência de entidades e propriedades para Azure Boards

Recursos relacionados

• Extensão do Wiql para OData Marketplace
• Tutorial básico da organização OData
• OData versão 4.0. Parte 3: CSDL (Common Schema Definition Language) mais a Errata 03, Wrapper do Modelo de Entidade