Controle de versão da API OData

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

O Analytics for Azure DevOps oferece uma API OData versionada compatível com clientes projetados para versões específicas. Cada versão pode incluir melhorias e alterações ininterruptas, enquanto as alterações de quebra 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 suportadas: 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 de quebra. A v2.0 inclui melhorias e mais funcionalidades em comparação com a v1.0.

v3.0-preview e v4.0-preview: as versões de visualização podem incluir alterações significativas e não é garantido 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.

Porquê escolher uma versão específica?

• Estabilidade: Se você precisar de uma API estável e confiável sem quebrar as alterações, você deve escolher uma das versões lançadas (v1.0 ou v2.0).
• Novos recursos: Se quiser aproveitar os recursos e melhorias mais recentes, você pode optar por uma das versões de visualização (v3.0-preview ou v4.0-preview). No entanto, essas versões podem incluir alterações de quebra e estão sujeitas a alterações.
• Compatibilidade: Certifique-se de que a versão escolhida é compatível com os 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 suportadas: v1.0, v2.0, v3.0-preview ou v4.0-preview.

Conjuntos de entidades suportados em cada versão

Para obter informações sobre quais EntitySets são suportados 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 seguintes durante seu ciclo de vida.

1. Fase de pré-visualização

Combinamos e lançamos todas as alterações significativas em versões futuras da API. Para disponibilizar esta funcionalidade o mais cedo possível, lançamos novas versões no modo de pré-visualização . Alterações significativas 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 de visualização seja incluído na versão lançada. A pré-visualização de uma versão permanece disponível por um mínimo de seis semanas após o seu lançamento.

2. Lançado

Quando uma versão de visualização 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 de quebra, embora o modelo de dados ainda possa se expandir com mais funcionalidades. Suportamos versões lançadas por um período mínimo de 12 meses.

3. Preterido

As versões preteridas não são mais suportadas 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:

O ponto de extremidade {version} OData for Analytics não é suportado. Informações sobre a última versão recomendada estão disponíveis aqui: https://go.microsoft.com/fwlink/?linkid=856818

Quebrando vs alterações ininterruptas

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 ininterruptas

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. Estas 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 de quebra

Considere um cenário em que retornamos à estrutura original da User entidade, resultando na remoção de um recurso previamente 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>

Como a UserType remoção do campo é uma alteração de quebra, 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 o Google Analytics
• OData Versão 4.0 Parte 5: Controle de versão