OData API-versiebeheer

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

Naarmate de Analytics-service volwassener wordt, zijn we toegewijd aan het bieden van consistentie en betrouwbaarheid aan onze gebruikers. Als zodanig biedt Analytics voor Azure DevOps een OData-API met een versie die compatibel is met clients die voor deze versies zijn ontworpen. Elke versie kan worden uitgebreid met meer functionaliteit en wijzigingen die geen fouten veroorzaken. Incompatibele wijzigingen of wijzigingen die fouten veroorzaken, worden in toekomstige versies van de API geïmplementeerd.

De API-versie volgt het element _odata in het aanvraagpad en heeft waarde als een van de ondersteunde versies: 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 de versie. De meest recente ondersteunde versie is v2.0en de meest recente preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Preview-versies

• v 3.0-preview
• v4.0-preview

Uitgebrachte versies

• v1.0
• v2.0

Entiteitssets die in elke versie worden ondersteund

Zie 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 drie fasen tijdens de levenscyclus.

Preview

Alle wijzigingen die fouten veroorzaken, worden gecombineerd en samen uitgebracht in toekomstige versies van de API. Als u deze functionaliteit zo vroeg mogelijk beschikbaar wilt maken, moet u nieuwe versies in de preview-modus uitbrengen. Wijzigingen die fouten veroorzaken, zijn nog steeds mogelijk wanneer een versie zich in de preview-modus bevindt. Er is ook geen garantie dat wat is opgenomen in een preview-versie, wordt opgenomen in een uitgebrachte versie.

De preview van een versie is minimaal zes weken na de release beschikbaar.

Vrijgegeven

Zodra een preview-versie voldoende volwassen is voor release, wordt deze beschikbaar gemaakt zonder het achtervoegsel -preview . Er worden geen belangrijke wijzigingen geïntroduceerd in uitgebrachte versies, maar het gegevensmodel kan nog steeds groeien met aanvullende functionaliteit. Uitgebrachte versies worden minimaal 12 maanden ondersteund.

Afgeschaft

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

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

Belangrijke versus niet-belangrijke wijzigingen

Het gegevensmodel dat door Analytics wordt weergegeven, definieert het contract tussen de service en de bijbehorende clients. De OData-specificatie vereist dat clients tolerant zijn voor additieve wijzigingen in het gegevensmodel. Wijzigingen die fouten veroorzaken, worden in toekomstige versies geïntroduceerd. Zie OData Versie 4.0 Deel 5: Versiebeheer voor meer informatie

Notitie

Het systeem heeft geen versie van aangepaste werkitemvelden. Het is ook mogelijk om belangrijke wijzigingen in uw model te veroorzaken door de typen werkitems of aangepaste velden te verwijderen of te wijzigen. Alle werkitems en de bijbehorende revisies weerspiegelen de huidige configuratie van het aangepaste veld.

Voorbeeld van niet-belangrijke wijzigingen

Overweeg een scenario waarin een nieuwe UserType eigenschap wordt toegevoegd aan de User entiteit. De metagegevens voor versie v1.0 zijn bijvoorbeeld zoals 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>

Voor versie v4.0-preview zijn de metagegevens uitgebreid. Wijzigingen zijn additief en kunnen in eerdere versies beschikbaar worden gesteld.

<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 wijzigingen die fouten veroorzaken

Overweeg nu een scenario waarin we terugkeren naar de oorspronkelijke structuur van de entiteit Gebruiker, waardoor een eerder beschikbare functie wordt verwijderd.

<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 wijziging is die fouten veroorzaakt, 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