Controle de versão da API OData

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

O Analytics para Azure DevOps oferece uma API OData com versão compatível com clientes projetados para versões específicas. Cada versão pode incluir aprimoramentos e alterações não interruptivas, enquanto as alterações significativas são introduzidas em versões futuras.

A versão da API segue o _odata elemento no caminho da solicitação e pode ser uma das versões com suporte: v1.0, v2.0, v3.0-preview ou v4.0-preview.

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

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/$metadata

Diferenças entre versões

v1.0 e v2.0: as versões lançadas da API OData são estáveis e não incluem alterações significativas. A v2.0 inclui aprimoramentos e mais funcionalidades em comparação com a v1.0.

v3.0-preview e v4.0-preview: as versões prévias podem incluir alterações significativas e não há garantia de que tenham os mesmos recursos na versão final. Eles oferecem acesso antecipado a novos recursos e melhorias que ainda não estão disponíveis nas versões lançadas.

Por que escolher uma versão específica?

• Estabilidade: Se você precisa de uma API estável e confiável sem alterações significativas, deve escolher uma das versões lançadas (v1.0 ou v2.0).
• Novos recursos: se você quiser aproveitar os recursos e melhorias mais recentes, poderá optar por uma das versões prévias (v3.0-preview ou v4.0-preview). No entanto, essas versões podem incluir alterações significativas e estão sujeitas a alterações.
• Compatibilidade: Certifique-se de que a versão escolhida seja compatível com seus clientes e sistemas existentes. A versão da API segue o _odata elemento no caminho da solicitação e pode ser uma das versões com suporte: v1.0, v2.0, v3.0-preview ou v4.0-preview.

Conjuntos de entidades com suporte em cada versão

Para obter informações sobre quais EntitySets têm suporte com cada versão da API, consulte Modelo de dados para Analytics, Entidades.

Ciclo de vida da versão

Cada versão da API OData passa pelas três fases a seguir durante seu ciclo de vida.

1. Fase de visualização

Combinamos e lançamos todas as alterações significativas juntas em versões futuras da API. Para disponibilizar essa funcionalidade o mais cedo possível, lançamos novas versões no modo de visualização . As alterações interruptivas ainda são possíveis enquanto uma versão está no modo de visualização e não há garantia de que o que está incluído em uma versão prévia seja incluído na versão lançada. A visualização de uma versão permanece disponível por um período mínimo de seis semanas após seu lançamento.

2. Lançado

Depois que uma versão prévia amadurece e está pronta para lançamento, ela fica disponível sem o sufixo -preview . As versões lançadas não incluem alterações significativas, embora o modelo de dados ainda possa se expandir com mais funcionalidades. Oferecemos suporte a versões lançadas por um período mínimo de 12 meses.

3. Obsoleto

Não há mais suporte para versões preteridas e as solicitações para essas versões não são atendidas. Se você tentar solicitar uma versão preterida ou sem suporte, receberá um código de resposta HTTP 410 e uma mensagem como:

Não há suporte para o ponto de extremidade OData {version} para Análise. Informações sobre a versão recomendada mais recente estão disponíveis aqui: https://go.microsoft.com/fwlink/?linkid=856818

Alterações significativas versus não interruptivas

O modelo de dados exposto pelo Analytics define o contrato entre o serviço e seus clientes. De acordo com a especificação OData, os clientes devem ser tolerantes a alterações aditivas no modelo de dados. Alterações significativas são introduzidas em versões futuras. Para obter mais informações, consulte OData versão 4.0 Parte 5: controle de versão.

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 mostrados na sintaxe a seguir.

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

Na versão v4.0-preview, os metadados são aumentados com alterações aditivas. Essas alterações também 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

Considere um cenário em que revertemos para a estrutura original da User entidade, resultando na remoção de um recurso disponível anteriormente.

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

Como a UserType remoção do campo é uma alteração significativa, o campo não é removido até a 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: Controle de versão