Versiebeheer van OData-API

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Analytics voor Azure DevOps biedt een versieversie van de OData-API die compatibel is met clients die zijn ontworpen voor specifieke versies. Elke versie kan verbeteringen en vaste wijzigingen bevatten, terwijl belangrijke wijzigingen worden geïntroduceerd in toekomstige versies.

De API-versie volgt het _odata element in het aanvraagpad en kan een van de ondersteunde versies zijn: v1.0, v2.0, v3.0-preview of v4.0-preview.

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

Notitie

De Analytics-service wordt automatisch ingeschakeld en ondersteund in productie voor alle Azure DevOps-services. Power BI-integratie en -toegang tot de OData-feed van de Analytics-service zijn algemeen beschikbaar. We raden u aan deze te gebruiken en ons feedback te geven. Beschikbare gegevens zijn afhankelijk van versie. De meest recente ondersteunde versie is v2.0en de nieuwste preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Verschillen tussen versies

v1.0 en v2.0: Uitgebrachte versies van de OData-API zijn stabiel en bevatten geen belangrijke wijzigingen. v2.0 bevat verbeteringen en meer functionaliteit in vergelijking met v1.0.

v3.0-preview en v4.0-preview: preview-versies bevatten mogelijk belangrijke wijzigingen en hebben niet gegarandeerd dezelfde functies in de definitieve release. Ze bieden vroege toegang tot nieuwe functies en verbeteringen die nog niet beschikbaar zijn in de uitgebrachte versies.

Waarom een specifieke versie kiezen?

• Stabiliteit: Als u een stabiele en betrouwbare API nodig hebt zonder wijzigingen die fouten veroorzaken, moet u een van de uitgebrachte versies (v1.0 of v2.0) kiezen.
• Nieuwe functies: Als u wilt profiteren van de nieuwste functies en verbeteringen, kunt u kiezen voor een van de preview-versies (v3.0-preview of v4.0-preview). Deze versies kunnen echter belangrijke wijzigingen bevatten en kunnen worden gewijzigd.
• Compatibiliteit: Zorg ervoor dat de versie die u kiest compatibel is met uw bestaande clients en systemen. De API-versie volgt het _odata element in het aanvraagpad en kan een van de ondersteunde versies zijn: v1.0, v2.0, v3.0-preview of v4.0-preview.

Entiteitssets die in elke versie worden ondersteund

Zie Het gegevensmodel voor analyse, entiteiten voor informatie over welke EntitySets worden ondersteund met elke API-versie.

Levenscyclus van versie

Elke versie van de OData-API doorloopt de volgende drie fasen tijdens de levenscyclus.

1. Preview-fase

We combineren en vrijgeven alle belangrijke wijzigingen in toekomstige versies van de API. Om deze functionaliteit zo vroeg mogelijk beschikbaar te maken, brengen we nieuwe versies uit in de preview-modus . Belangrijke wijzigingen zijn nog steeds mogelijk terwijl een versie in de preview-modus staat en er is geen garantie dat wat is opgenomen in een preview-versie wordt opgenomen in de uitgebrachte versie. De preview van een versie blijft minimaal zes weken na de release beschikbaar.

2. Uitgebracht

Zodra een preview-versie is gerijpt en klaar is voor release, wordt deze beschikbaar zonder het achtervoegsel -preview . Uitgebrachte versies bevatten geen belangrijke wijzigingen, hoewel het gegevensmodel mogelijk nog steeds wordt uitgebreid met meer functionaliteit. We ondersteunen uitgebrachte versies voor minimaal 12 maanden.

3. Afgeschaft

Afgeschafte versies worden niet meer ondersteund en aanvragen voor deze versies worden niet uitgevoerd. Als u een afgeschafte of niet-ondersteunde versie probeert aan te vragen, ontvangt u een HTTP 410-antwoordcode en een bericht zoals:

Het OData-eindpunt {version} voor Analytics wordt niet ondersteund. Hier vindt u informatie over de meest recente aanbevolen versie: https://go.microsoft.com/fwlink/?linkid=856818

Wijzigingen die fouten veroorzaken ten opzichte van vaste wijzigingen

Het gegevensmodel dat door Analytics wordt weergegeven, definieert het contract tussen de service en de bijbehorende clients. Volgens de OData-specificatie moeten clients tolerant zijn voor additieve wijzigingen in het gegevensmodel. Belangrijke wijzigingen worden geïntroduceerd in toekomstige versies. Zie OData-versie 4.0 Deel 5: Versiebeheer voor meer informatie.

Notitie

In het systeem worden geen aangepaste werkitemvelden geversied. In het systeem worden geen aangepaste werkitemvelden geversied. Het verwijderen of wijzigen van de typen werkitems of aangepaste velden kan leiden tot belangrijke wijzigingen in uw model. Alle werkitems en de bijbehorende revisies weerspiegelen de huidige configuratie van het aangepaste veld.

Voorbeeld van vaste wijzigingen

Overweeg een scenario waarin een nieuwe UserType eigenschap wordt toegevoegd aan de User entiteit. De metagegevens voor versie v1.0 worden bijvoorbeeld weergegeven in de volgende syntaxis.

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

In de versie v4.0-preview worden de metagegevens uitgebreid met additieve wijzigingen. Deze wijzigingen kunnen ook beschikbaar worden gesteld in eerdere versies.

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

Voorbeeld van belangrijke wijzigingen

Overweeg een scenario waarin we terugkeren naar de oorspronkelijke structuur van de User entiteit, wat resulteert in het verwijderen van een eerder beschikbare functie.

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

Omdat het verwijderen van het UserType veld een belangrijke wijziging is, wordt het veld pas verwijderd als versie v2.0 van de API. Versie v1.0 van het gegevensmodel blijft het UserType veld bevatten.

Verwante artikelen:

• Gegevensmodel voor analyse
• OData-versie 4.0 deel 5: Versiebeheer