OData API-versionshantering

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Analytics för Azure DevOps erbjuder ett versionshanterat OData-API som är kompatibelt med klienter som är utformade för specifika versioner. Varje version kan innehålla förbättringar och icke-inbrytande ändringar, medan icke-bakåtkompatibla ändringar introduceras i framtida versioner.

API-versionen följer elementet _odata i begärandesökvägen och kan vara en av de versioner som stöds: v1.0, v2.0, v3.0-preview eller v4.0-preview.

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

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

Skillnader mellan versioner

v1.0 och v2.0: Frisläppt versioner av OData-API:et är stabila och inkluderar inte icke-bakåtkompatibla ändringar. v2.0 innehåller förbättringar och fler funktioner jämfört med v1.0.

v3.0-preview och v4.0-preview: Förhandsversioner kan innehålla icke-bakåtkompatibla ändringar och garanteras inte ha samma funktioner i den slutliga versionen. De ger tidig åtkomst till nya funktioner och förbättringar som ännu inte är tillgängliga i de utgivna versionerna.

Varför välja en specifik version?

• Stabilitet: Om du behöver ett stabilt och tillförlitligt API utan icke-bakåtkompatibla ändringar bör du välja en av de utgivna versionerna (v1.0 eller v2.0).
• Nya funktioner: Om du vill dra nytta av de senaste funktionerna och förbättringarna kan du välja någon av förhandsversionerna (v3.0-preview eller v4.0-preview). Dessa versioner kan dock innehålla icke-bakåtkompatibla ändringar och kan komma att ändras.
• Kompatibilitet: Kontrollera att den version du väljer är kompatibel med dina befintliga klienter och system. API-versionen följer elementet _odata i begärandesökvägen och kan vara en av de versioner som stöds: v1.0, v2.0, v3.0-preview eller v4.0-preview.

Entitetsuppsättningar som stöds i varje version

Information om vilka EntitySets som stöds med varje API-version finns i Datamodell för analys, entiteter.

Versionslivscykel

Varje version av OData-API:et går igenom följande tre faser under livscykeln.

1. Förhandsversionsfas

Vi kombinerar och släpper alla icke-bakåtkompatibla ändringar tillsammans i framtida versioner av API:et. För att göra den här funktionen tillgänglig så tidigt som möjligt släpper vi nya versioner i förhandsgranskningsläge . Icke-bakåtkompatibla ändringar är fortfarande möjliga när en version är i förhandsgranskningsläge, och det finns ingen garanti för att det som ingår i en förhandsversion tas med i den utgivna versionen. Förhandsversionen av en version är tillgänglig i minst sex veckor efter att den har släppts.

2. Frisläppt

När en förhandsversion har mognat och är redo för lansering blir den tillgänglig utan suffixet -preview . Utgivna versioner innehåller inte icke-bakåtkompatibla ändringar, även om datamodellen fortfarande kan utökas med fler funktioner. Vi stöder utgivna versioner i minst 12 månader.

3. Inaktuell

Inaktuella versioner stöds inte längre och begäranden till dessa versioner uppfylls inte. Om du försöker begära en inaktuell eller icke-stödd version får du en HTTP 410-svarskod och ett meddelande som:

OData-slutpunkten för Analys i {version} stöds inte. Information om den senaste rekommenderade versionen finns här: https://go.microsoft.com/fwlink/?linkid=856818

Icke-bakåtkompatibla eller icke-bakåtkompatibla ändringar

Datamodellen som exponeras av Analytics definierar kontraktet mellan tjänsten och dess klienter. Enligt OData-specifikationen måste klienter vara toleranta mot additiva ändringar i datamodellen. Icke-bakåtkompatibla ändringar introduceras i framtida versioner. Mer information finns i OData Version 4.0 Del 5: Versionshantering.

Exempel på icke-inbrytningsändringar

Tänk dig ett scenario där en ny UserType egenskap läggs till i User entiteten. Metadata för v1.0-versionen visas till exempel i följande syntax.

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

I v4.0-förhandsversionen utökas metadata med additiva ändringar. Dessa ändringar kan också göras tillgängliga i tidigare versioner.

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

Exempel på icke-bakåtkompatibla ändringar

Tänk dig ett scenario där vi återgår till den ursprungliga strukturen för User entiteten, vilket resulterar i att en tidigare tillgänglig funktion tas bort.

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

Eftersom borttagningen UserType av fältet är en icke-bakåtkompatibel ändring tas fältet inte bort förrän version v2.0 av API:et. Version v1.0 av datamodellen fortsätter att innehålla fältet UserType .

Relaterade artiklar

• Datamodell för analys
• OData version 4.0 Del 5: Versionshantering