OData API verziószámozása

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

Ahogy az Analytics szolgáltatás kiforrott, elkötelezettek vagyunk a felhasználók konzisztenciájának és megbízhatóságának biztosításában. Ezért az Azure DevOpshoz készült Analytics egy verziószámozott OData API-t biztosít, amely kompatibilis az adott verziókhoz tervezett ügyfelekkel. Az egyes verziók további funkciókkal és nem kompatibilitástörő módosításokkal bővíthetők. Az inkompatibilis vagy kompatibilitástörő változások az API jövőbeli verzióiba kerülnek.

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

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

Megjegyzés

Az Elemzési szolgáltatás éles környezetben automatikusan engedélyezve és támogatva van az összes Azure DevOps Services esetében. Általánosan elérhető a Power BI integrációja és az Elemzési szolgáltatás OData-hírcsatornájának elérése. Javasoljuk, hogy használja, és küldjön nekünk visszajelzést. Az elérhető adatok verziófüggőek. A legújabb támogatott verzió a v2.0, a legújabb előzetes verzió pedig .v4.0-preview További információ: OData API-verziószámozás.

Előzetes verzió

• 3.0-s előzetes verzió
• 4.0-s verziójú előzetes verzió

Megjelent verziók

• 1.0-s verzió
• 2.0-s verzió

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

Az egyes API-verziókban támogatott EntitySet-ekkel kapcsolatos információkért lásd: Adatmodell elemzésekhez, entitások.

Verzió életciklusa

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

Előnézet

Az API későbbi verzióiban az összes kompatibilitástörő változás össze lesz állítva és együtt jelenik meg. Ha a lehető leghamarabb elérhetővé szeretné tenni ezt a funkciót, akkor az új verziókat előzetes verzió módban is kiadhatja. A kompatibilitástörő változások továbbra is lehetségesek, amíg egy verzió előnézeti módban van. Emellett nem garantálható, hogy az előzetes verzióban szereplő funkciók szerepelni fognak a kiadott verziókban.

A verzió előzetes verziója legalább hat hétig lesz elérhető a kiadás után.

Mentesít

Ha az előzetes verzió elég kiforrott a kiadáshoz, az -preview utótag nélkül is elérhetővé válik. A kiadott verziókban nem vezetünk be kompatibilitástörő változásokat, de az adatmodell tovább nőhet az additív funkciókkal. A kiadott verziók legalább 12 hónapig támogatottak lesznek.

Elavult

Az elavult verziók már nem támogatottak. Az elavult verzióra irányuló kérések nem lesznek teljesítve. Ha elavult vagy nem támogatott verziót próbál kérni, egy HTTP 410-es válaszkódot és egy üzenetet fog kapni, például:

Az Elemzés {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 kompatibilitástörő változá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ó megköveteli, hogy az ügyfelek tolerálják az adatmodell additív módosítá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

Megjegyzés

A rendszer nem verziószámít egyéni munkaelem-mezőket. Emellett a modell kompatibilitástörő változásait is okozhatja a munkaelemek vagy egyéni mezők típusának eltávolításával vagy módosításával. Az összes munkaelem és azok változatai az aktuális egyéni mezőkonfigurációt tükrözik.

Példa a nem kompatibilitástörő változásokra

Vegyünk egy olyan forgatókönyvet, amelyben egy új UserType tulajdonságot adnak hozzá az User entitáshoz. Az 1.0-s verzió metaadatai például az alábbi szintaxisban láthatóak.

<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ú előzetes verzió esetében a metaadatok ki lettek bővítve. A módosítások additívak, és 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 kompatibilitástörő változásokra

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

<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ő nem lesz eltávolítva az API 2.0-s verziójáig. Az adatmodell 1.0-s verziója továbbra is tartalmazza a UserType mezőt.

Kapcsolódó cikkek

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