Správa verzí rozhraní API OData

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

Jak služba Analytics zraje, věnujeme se poskytování konzistence a spolehlivosti našim uživatelům. Analytics pro Azure DevOps proto poskytuje rozhraní OData API s verzemi, které je kompatibilní s klienty určenými pro tyto verze. Každá verze může být vylepšena o další funkce a zásadní změny. Nekompatibilní nebo zásadní změny se převedou do budoucích verzí rozhraní API.

Verze rozhraní API se řídí elementem _odata v cestě požadavku a má hodnotu jako jedna 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

Poznámka

Služba Analytics je automaticky povolená a podporovaná v produkčním prostředí pro všechny Azure DevOps Services. Integrace Power BI a přístup k datovému kanálu OData analytické služby jsou obecně dostupné. Doporučujeme, abyste ji použili a poskytli nám zpětnou vazbu. Dostupná data závisí na verzi. Nejnovější podporovaná verze je v2.0a nejnovější verze Preview je v4.0-preview. Další informace najdete v tématu Správa verzí rozhraní API OData.

Verze Preview

• v3.0-preview
• verze 4.0 preview

Vydané verze

• verze 1.0
• v2.0

Sady entit podporované v jednotlivých verzích

Informace o podporovaných sadách EntitySet v jednotlivých verzích rozhraní API najdete v tématu Datový model pro analýzu, Entity.

Životní cyklus verze

Každá verze rozhraní OData API projde během svého životního cyklu třemi fázemi.

Preview

Všechny zásadní změny budou v budoucích verzích rozhraní API sloučeny a vydávány společně. Pokud chcete tuto funkci zpřístupnit co nejdříve, vydáte nové verze v režimu Preview . Změny způsobující chybu jsou stále možné, i když je verze v režimu náhledu. Navíc není zaručeno, že to, co je součástí verze Preview, bude součástí vydané verze.

Verze Preview bude k dispozici minimálně šest týdnů od vydání.

Vydáno

Jakmile bude verze Preview dostatečná pro vydání, bude k dispozici bez přípony -preview . Ve vydaných verzích nebudou zavedeny žádné zásadní změny, ale datový model se může stále rozšiřovat s dalšími funkcemi. Vydané verze budou podporovány minimálně 12 měsíců.

Zastaralé

Zastaralé verze se už nepodporují. Požadavky na zastaralou verzi nebudou splněny. Pokud se pokusíte požádat o zastaralou nebo nepodporovanou verzi, zobrazí se kód odpovědi HTTP 410 a zpráva podobná:

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

Zásadní vs. nevýrušné změny

Datový model vystavený službou Analytics definuje kontrakt mezi službou a jejími klienty. Specifikace OData vyžaduje, aby klienti měli odolnost vůči doplňkovým změnám datového modelu. Zásadní změny budou zavedeny v budoucích verzích. Další informace najdete v tématu OData verze 4.0, část 5: Správa verzí.

Poznámka

Systém neobsahuje verze žádných vlastních polí pracovních položek. Odebráním nebo změnou typů pracovních položek nebo vlastních polí je také možné způsobit zásadní změny modelu. Všechny pracovní položky a jejich revize budou odrážet aktuální konfiguraci vlastního pole.

Příklad nevýrušných změn

Představte si scénář, kdy se do User entity přidá nová UserType vlastnost. Například metadata pro verzi v1.0 jsou znázorněna 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>

Pro verzi v4.0 Preview byla metadata rozšířena. Změny jsou doplňkové a je možné je 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

Teď se zamyslete nad scénářem, ve kterém se vrátíme k původní struktuře entity Uživatel, což způsobí 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, UserType že odebrání pole představuje zásadní změnu, neodebere se pole až do verze 2.0 rozhraní API. Verze v1.0 datového modelu bude i nadále obsahovat pole UserType .

Související články

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