Správa verzí rozhraní API OData

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

Analýza pro Azure DevOps nabízí rozhraní API OData verze kompatibilní s klienty navrženými pro konkrétní verze. Každá verze může zahrnovat vylepšení a rozbíjející změny, zatímco zásadní změny se zavádějí v budoucích verzích.

Verze rozhraní API se řídí elementem _odata v cestě požadavku a může být jednou z podporovaných verzí: v1.0, v2.0, v3.0-preview nebo v4.0-preview.

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

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

Rozdíly mezi verzemi

v1.0 a v2.0: Vydané verze rozhraní OData API jsou stabilní a neobsahují zásadní změny. Verze 2.0 zahrnuje vylepšení a další funkce v porovnání s v1.0.

verze v3.0-preview a v4.0-preview: Verze Preview můžou obsahovat zásadní změny a nezaručuje, že v konečné verzi budou mít stejné funkce. Nabízejí přednostní přístup k novým funkcím a vylepšením, které ještě nejsou v vydaných verzích k dispozici.

Proč zvolit konkrétní verzi?

• Stabilita: Pokud potřebujete stabilní a spolehlivé rozhraní API bez zásadních změn, měli byste zvolit jednu z vydaných verzí (v1.0 nebo v2.0).
• Nové funkce: Pokud chcete využívat nejnovější funkce a vylepšení, můžete zvolit jednu z verzí Preview (v3.0-preview nebo v4.0-preview). Tyto verze ale můžou obsahovat zásadní změny a můžou se změnit.
• Kompatibilita: Ujistěte se, že zvolená verze je kompatibilní s vašimi stávajícími klienty a systémy. Verze rozhraní API se řídí elementem _odata v cestě požadavku a může být jednou z podporovaných verzí: v1.0, v2.0, v3.0-preview nebo v4.0-preview.

Sady entit podporované v jednotlivých verzích

Informace o tom, které sady entit jsou podporovány s každou verzí rozhraní API, najdete v tématu Datový model pro analýzy, entity.

Životní cyklus verzí

Každá verze rozhraní OData API prochází během životního cyklu následujícími třemi fázemi.

1. Fáze preview

Všechny zásadní změny kombinujeme a vydáváme společně v budoucích verzích rozhraní API. Aby byla tato funkce co nejdříve dostupná, vydáváme nové verze v režimu Preview . Zásadní změny jsou stále možné, i když je verze v režimu Preview a není zaručeno, že se do vydané verze zahrne i verze Preview. Verze Preview verze zůstává k dispozici minimálně šest týdnů po vydání.

2. Vydáno

Jakmile se verze Preview zralá a je připravená k vydání, bude k dispozici bez přípony -preview . Vydané verze nezahrnují zásadní změny, i když se datový model může stále rozšiřovat o další funkce. Vydané verze podporujeme minimálně 12 měsíců.

3. Zastaralé

Zastaralé verze se už nepodporují a požadavky na tyto verze nejsou splněné. Pokud se pokusíte požádat o zastaralou nebo nepodporovanou verzi, obdržíte kód odpovědi HTTP 410 a zprávu, například:

Koncový bod OData {version} pro Analýzu se nepodporuje. Informace o nejnovější doporučené verzi najdete tady: https://go.microsoft.com/fwlink/?linkid=856818

Rozbíjející vs. neprolomné změny

Datový model vystavený službou Analytics definuje kontrakt mezi službou a jejími klienty. Podle specifikace OData musí být klienti tolerantní vůči doplňkovým změnám datového modelu. Zásadní změny se zavádějí v budoucích verzích. Další informace naleznete v tématu OData verze 4.0 Část 5: Správa verzí.

Příklad nefunkčních změn

Představte si scénář, ve kterém se do User entity přidá nová UserType vlastnost. Metadata verze v1.0 se například zobrazují v následující syntaxi.

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

Ve verzi v4.0-Preview se metadata rozšiřují o doplňkové změny. Tyto změny lze také zpřístupnit v předchozích verzích.

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

Příklad zásadních změn

Představte si scénář, kdy se vrátíme k původní struktuře User entity, což vede k odebrání dříve dostupné funkce.

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

Vzhledem k tomu, že odebrání UserType pole je zásadní změnou, pole se neodebere až do verze 2.0 rozhraní API. Verze v1.0 datového modelu bude i nadále obsahovat UserType pole.

Související články

• Datový model pro analýzu
• OData verze 4.0 část 5: Správa verzí