Controle de versão da API do OData

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

À medida que o serviço de Análise amadurece, estamos dedicados a fornecer consistência e confiabilidade aos nossos usuários. Dessa forma, o Analytics para Azure DevOps fornece uma API OData com controle de versão compatível com clientes projetados para essas versões. Cada versão pode ser aprimorada com mais funcionalidade e alterações não interruptivas. 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 da solicitação e tem o valor como uma de nossas 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

Observação

O serviço de Análise é 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 de Análise estão em disponibilidade geral. Incentivamos você a usá-lo e nos enviar 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.

Versões prévias

• v3.0–versão prévia
• v4.0-preview

Versões lançadas

• v1.0
• v2.0

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 Análise, Entidades.

Ciclo de vida da versão

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

Versão Prévia

Todas as alterações interruptivas serão combinadas e lançadas juntas em versões futuras da API. Para disponibilizar essa funcionalidade o mais cedo possível, libere também novas versões no modo de visualização . Alterações interruptivas ainda são possíveis enquanto uma versão está no modo de visualização. Além disso, não há garantia de que o que está incluído em uma versão prévia será incluído em uma versão lançada.

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

Liberado

Depois que uma versão prévia amadurecer o suficiente para o lançamento, ela será disponibilizada sem o sufixo -preview . Nenhuma alteração interruptiva será introduzida nas versões lançadas, mas o modelo de dados ainda pode crescer com a funcionalidade aditiva. As versões lançadas terão suporte por um mínimo de 12 meses.

Preterido

Não há mais suporte para versões preteridas. As solicitações feitas a uma versão preterida não serã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. 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 versus não interruptivas

O modelo de dados exposto pelo Analytics define o contrato entre o serviço e seus clientes. A especificação OData exige que os clientes sejam tolerantes a alterações aditivas ao modelo de dados. Alterações interruptivas serão introduzidas em versões futuras. Para obter mais informações, consulte OData Versão 4.0 Parte 5: Controle de versão

Observação

O sistema não faz a versão de nenhum campo de item de trabalho personalizado. Além disso, é possível causar alterações interruptivas em seu modelo removendo ou alterando os tipos de itens de trabalho ou campos personalizados. Todos os itens de trabalho e suas revisões refletirão a configuração de campo personalizado atual.

Exemplo de alterações não interruptivas

Considere um cenário em que uma nova UserType propriedade é adicionada à User entidade. Por exemplo, os metadados para a 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>

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 reverter à estrutura original da entidade User, causando a 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 remoção do UserType campo é uma alteração interruptiva, o campo não será 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