Controlo de versões da API OData

Serviços do Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

À medida que o serviço de Análise amadurece, dedicamo-nos a fornecer consistência e fiabilidade aos nossos utilizadores. Como tal, o Analytics for Azure DevOps fornece uma API OData com versão compatível com clientes concebidos para essas versões. Cada versão pode ser melhorada com mais funcionalidades e alterações não interruptivas. As alterações incompatíveis ou interruptivas serão implementadas em versões futuras da API.

A versão da API segue o elemento _odata no caminho do pedido e tem valor como uma das nossas versões suportadas: v1.0, v2.0, v3.0-preview ou v4.0-preview.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata

Nota

O serviço Analytics é ativado e suportado automaticamente em produção para todos os Serviços do Azure DevOps. A integração e o acesso do Power BI ao feed OData do Serviço de Análise estão geralmente disponíveis. Encorajamo-lo a utilizá-lo e a dar-nos feedback. Os dados disponíveis dependem da versão. A versão suportada mais recente é v2.0, e a versão de pré-visualização mais recente é v4.0-preview. Para obter mais informações, veja Controlo de versões da API OData.

Versões de pré-visualização

• v3.0 - pré-visualização
• v4.0-preview

Versões lançadas

• v1.0
• v2.0

Conjuntos de entidades suportados em cada versão

Para obter informações sobre quais Os Conjuntos de Entidades são suportados com cada versão da API, veja Modelo de dados para Análise, Entidades.

Ciclo de vida da versão

Cada versão da API OData passará por três fases durante o ciclo de vida.

Pré-visualizar

Todas as alterações interruptivas serão combinadas e lançadas em conjunto em versões futuras da API. Para disponibilizar esta funcionalidade o mais cedo possível, liberte as novas versões no modo de pré-visualização . As alterações interruptivas ainda são possíveis enquanto uma versão está no modo de pré-visualização. Além disso, não há garantias de que o que está incluído numa versão de pré-visualização será incluído numa versão lançada.

A pré-visualização de uma versão estará disponível durante um mínimo de seis semanas após o lançamento.

Lançado

Assim que uma versão de pré-visualização amadurecer o suficiente para o lançamento, esta será disponibilizada sem o sufixo -preview . Não serão introduzidas alterações interruptivas às versões lançadas, mas o modelo de dados pode continuar a crescer com a funcionalidade de adição. As versões lançadas serão suportadas durante um mínimo de 12 meses.

Preterido

As versões preteridas já não são suportadas. Os pedidos feitos a uma versão preterida não serão cumpridos. Se tentar pedir uma versão preterida ou não suportada, receberá um código de resposta HTTP 410 e uma mensagem como:

O ponto final OData de {version} para Análise não é suportado. As informações sobre a versão recomendada mais recente estão disponíveis aqui: https://go.microsoft.com/fwlink/?linkid=856818

Alterações interruptivas vs. não interruptivas

O modelo de dados exposto pela Analytics define o contrato entre o serviço e os seus clientes. A especificação OData requer que os clientes sejam tolerantes a alterações de aditivos ao modelo de dados. As alterações interruptivas serão introduzidas em versões futuras. Para obter mais informações, veja OData Versão 4.0 Parte 5: Controlo de Versões

Nota

O sistema não versa campos de itens de trabalho personalizados. Além disso, é possível causar alterações interruptivas ao modelo ao remover ou alterar os tipos de itens de trabalho ou campos personalizados. Todos os itens de trabalho e as respetivas revisões refletirão a configuração atual do campo personalizado.

Exemplo de alterações não interruptivas

Considere um cenário em que uma nova UserType propriedade é adicionada à User entidade. Por exemplo, os metadados da versão v1.0 são apresentados na seguinte sintaxe.

<EntityType Name="User">
    <Key>
        <PropertyRef Name="UserSK"/>
    </Key>
    <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
    <Property Name="UserId" Type="Edm.Guid">
        <Annotation Term="Display.DisplayName" String="User Id"/>
    </Property>
    <Property Name="UserName" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Name"/>
    </Property>
    <Property Name="UserEmail" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Email"/>
    </Property>
    <!-- New User Type property -->
    <Property Name="UserType" Type="Edm.Int32">
        <Annotation Term="Display.DisplayName" String="User Type"/>
    </Property>
    <!-- New User Type property -->
</EntityType>

Para a versão v4.0-preview , os metadados foram aumentados. As alterações são aditivas e podem ser disponibilizadas em versões anteriores.

<EntityType Name="User">
  <Key>
    <PropertyRef Name="UserSK"/>
  </Key>
  <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
  <Property Name="UserId" Type="Edm.Guid">
    <Annotation Term="Display.DisplayName" String="User Id"/>
  </Property>
  <Property Name="UserName" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="User Name"/>
    <Annotation Term="Microsoft.VisualStudio.Services.Analytics.IsPersonallyIdentifiableInformation" Bool="true"/>
  </Property>
  <Property Name="UserEmail" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="User Email"/>
    <Annotation Term="Microsoft.VisualStudio.Services.Analytics.IsPersonallyIdentifiableInformation" Bool="true"/>
  </Property>
  <Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
  <Property Name="GitHubUserId" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="GitHub User Id"/>
  </Property>
  <Property Name="UserType" Type="Microsoft.VisualStudio.Services.Analytics.Model.UserType">
    <Annotation Term="Display.DisplayName" String="User Type"/>
  </Property>
</EntityType>

Exemplo de alterações interruptivas

Agora, considere um cenário em que revertemos para a estrutura original da entidade Utilizador, causando a remoção de uma funcionalidade anteriormente disponível.

<EntityType Name="User">
    <Key>
        <PropertyRef Name="UserSK"/>
    </Key>
    <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
    <Property Name="UserId" Type="Edm.Guid" Nullable="false">
        <Annotation Term="Display.DisplayName" String="User Id"/>
    </Property>
    <Property Name="UserName" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Name"/>
    </Property>
    <Property Name="UserEmail" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Email"/>
    </Property>
    <!-- User Type property has been removed -->
</EntityType>

Uma vez que a remoção do UserType campo é uma alteração interrupção, o campo só será removido na versão v2.0 da API. A versão v1.0 do modelo de dados continua a incluir o UserType campo.

Artigos relacionados

• Modelo de dados para Análise
• OData Versão 4.0 Parte 5: Controlo de Versões