OData API verziószámozása

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Az Azure DevOps-hez készült Analytics egy olyan verziójú OData API-t kínál, amely kompatibilis az adott verziókhoz tervezett ügyfelekkel. Az egyes verziók tartalmazhatnak fejlesztéseket és nem megszakító módosításokat, míg a megszakító módosításokat a jövőbeli verziókban vezetik be.

Az API-verzió a _odata kérelem elérési útjának elemét követi, és a támogatott verziók egyike lehet: v1.0, v2.0, v3.0-preview vagy v4.0-preview.

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

Feljegyzés

Az Elemzési szolgáltatás automatikusan engedélyezve van és támogatott éles környezetben az Azure DevOps Services összes szolgáltatásához. Az Analytics szolgáltatás OData-hírcsatornájánakPower BI-integrációja és hozzáférése általánosan elérhető. Javasoljuk, hogy használja az Analytics OData-hírcsatornát, és küldjön visszajelzést.

A rendelkezésre álló adatok verziófüggők. Az OData API legújabb támogatott verziója v2.0, és a legújabb előzetes verzió v4.0-preview. További információ: OData API-verziószámozás.

Verziók közötti különbségek

1.0-s és 2.0-s verzió:Az OData API kiadott verziói stabilak, és nem tartalmaznak kompatibilitástörő módosításokat. A 2.0-s verzió az 1.0-s verzióhoz képest további fejlesztéseket és funkciókat tartalmaz.

v3.0-előzetes és v4.0-előzetes verziók:Az előzetes verziók tartalmazhatnak kompatibilitástörő módosításokat, és nem garantált, hogy ugyanazokat a funkciókat tartalmazzák a végleges kiadásban. Korai hozzáférést biztosítanak az új funkciókhoz és fejlesztésekhez, amelyek még nem érhetők el a kiadott verziókban.

Miért érdemes egy adott verziót választani?

• Stabilitás: Ha stabil és megbízható API-ra van szüksége kompatibilitástörő módosítások nélkül, válasszon egyet a kiadott verziók közül (1.0-s vagy 2.0-s verzió).
• Új funkciók: Ha ki szeretné használni a legújabb funkciókat és fejlesztéseket, választhatja az előzetes verzió (3.0-s vagy 4.0-s verziójú) egyikét. Ezek a verziók azonban tartalmazhatnak kompatibilitástörő módosításokat, és változhatnak.
• Kompatibilitás: Győződjön meg arról, hogy a választott verzió kompatibilis a meglévő ügyfelekkel és rendszerekkel. Az API-verzió a _odata kérelem elérési útjának elemét követi, és a támogatott verziók egyike lehet: v1.0, v2.0, v3.0-preview vagy v4.0-preview.

Az egyes verziókban támogatott entitáskészletek

Az egyes API-verziókban támogatott EntitySet-ekkel kapcsolatos információkért tekintse meg az Analytics adatmodellje, az Entitások című témakört.

Verzió életciklusa

Az OData API minden verziója a következő három fázison megy keresztül az életciklusa során.

1. Előzetes verziójú fázis

Az API jövőbeli verzióiban egyesítjük és kiadjuk az összes kompatibilitástörő változást. Annak érdekében, hogy ezt a funkciót a lehető leghamarabb elérhetővé tegyük, előzetes verzió módban bocsátjuk ki az új verziókat. A kompatibilitástörő módosítások továbbra is lehetségesek, miközben egy verzió előzetes verzióban van, és nincs garancia arra, hogy az előzetes verzióban szereplő funkciók bekerülnek a kiadott verzióba. A verzió előzetes verziója a kiadás után legalább hat hétig elérhető marad.

2. Kiadás dátuma

Miután az előzetes verzió kiforrott, és készen áll a kiadásra, elérhetővé válik az -preview utótag nélkül. A kiadott verziók nem tartalmaznak kompatibilitástörő módosításokat, bár az adatmodell további funkciókkal bővülhet. Legalább 12 hónapig támogatjuk a kiadott verziókat.

3. Elavult

Az elavult verziók már nem támogatottak, és az ezekre a verziókra irányuló kérések nem teljesülnek. Ha elavult vagy nem támogatott verziót próbál kérni, egy HTTP 410-es válaszkódot és egy üzenetet kap, például:

Az Analytics {version} OData végpontja nem támogatott. A legújabb ajánlott verzióval kapcsolatos információk itt érhetők el: https://go.microsoft.com/fwlink/?linkid=856818

Kompatibilitástörő és nem törhető módosítások

Az Analytics által közzétett adatmodell határozza meg a szolgáltatás és ügyfelei közötti szerződést. Az OData specifikációja szerint az ügyfeleknek tolerálni kell az adatmodell additív változásait. A kompatibilitástörő változások a jövőbeli verziókban lesznek bevezetve. További információ: OData 4.0-s verzió, 5. rész: Verziószámozás.

Feljegyzés

A rendszer nem verziószámozza az egyéni munkaelem-mezőket. A rendszer nem verziószámozza az egyéni munkaelem-mezőket. A munkaelemek vagy egyéni mezők típusainak eltávolítása vagy módosítása a modell kompatibilitástörő változásait okozhatja. Az összes munkaelem és a hozzájuk tartozó változatok az aktuális egyéni mezőkonfigurációt tükrözik.

Példa a nem törhető módosításokra

Fontolja meg azt a forgatókönyvet, amikor egy új UserType tulajdonságot ad hozzá az User entitáshoz. Az 1.0-s verzió metaadatai például az alábbi szintaxisban jelennek meg.

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

A 4.0-s verziójú verzióban a metaadatok additív módosításokkal bővülnek. Ezek a módosítások a korábbi verziókban is elérhetővé tehetők.

<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élda a kompatibilitástörő változásokra

Vegyünk egy olyan forgatókönyvet, amelyben visszaállítjuk az entitás eredeti struktúráját User , ami egy korábban elérhető funkció eltávolítását eredményezi.

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

Mivel a UserType mező eltávolítása kompatibilitástörő változás, a mező csak az API 2.0-s verziójáig lesz eltávolítva. Az adatmodell 1.0-s verziója továbbra is tartalmazza a UserType mezőt.

Kapcsolódó cikkek

• Adatmodell az Elemzéshez
• OData 4.0-s verzió 5. rész: Verziószámozás