OData-API-Versionsverwaltung

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

Analytics für Azure DevOps bietet eine versionsgebundene OData-API, die mit Clients kompatibel ist, die für bestimmte Versionen entwickelt wurden. Jede Version enthält möglicherweise Verbesserungen und geschützte Änderungen, während in zukünftigen Versionen unterbrechungsfreie Änderungen eingeführt werden.

Die API-Version folgt dem _odata Element im Anforderungspfad und kann eine der unterstützten Versionen sein: v1.0, v2.0, v3.0-preview oder v4.0-preview.

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

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/$metadata

Unterschiede zwischen Versionen

v1.0 und v2.0: Veröffentlichte Versionen der OData-API sind stabil und enthalten keine wichtigen Änderungen. v2.0 enthält Verbesserungen und mehr Funktionen im Vergleich zu v1.0.

v3.0-preview und v4.0-preview: Vorschauversionen enthalten möglicherweise unterbrechungsfreie Änderungen und sind nicht garantiert, dass die gleichen Features in der endgültigen Version vorhanden sind. Sie bieten frühzeitigen Zugriff auf neue Features und Verbesserungen, die noch nicht in den veröffentlichten Versionen verfügbar sind.

Warum eine bestimmte Version auswählen?

• Stabilität: Wenn Sie eine stabile und zuverlässige API benötigen, ohne Änderungen zu unterbrechen, sollten Sie eine der veröffentlichten Versionen (v1.0 oder v2.0) auswählen.
• Neue Features: Wenn Sie die neuesten Features und Verbesserungen nutzen möchten, können Sie sich für eine der Vorschauversionen entscheiden (v3.0-preview oder v4.0-preview). Diese Versionen können jedoch unterbrechungsbegrenzende Änderungen enthalten und können geändert werden.
• Kompatibilität: Stellen Sie sicher, dass die ausgewählte Version mit Ihren vorhandenen Clients und Systemen kompatibel ist. Die API-Version folgt dem _odata Element im Anforderungspfad und kann eine der unterstützten Versionen sein: v1.0, v2.0, v3.0-preview oder v4.0-preview.

Entitätssätze, die in jeder Version unterstützt werden

Informationen dazu, welche EntitySets mit jeder API-Version unterstützt werden, finden Sie unter "Datenmodell für Analysen, Entitäten".

Versionslebenszyklus

Jede Version der OData-API durchläuft die folgenden drei Phasen während des Lebenszyklus.

1. Vorschauphase

Wir kombinieren und veröffentlichen alle wichtigen Änderungen in zukünftigen Versionen der API. Um diese Funktionalität so früh wie möglich verfügbar zu machen, veröffentlichen wir neue Versionen im Vorschaumodus . Unterbrechungsänderungen sind weiterhin möglich, während sich eine Version im Vorschaumodus befindet, und es gibt keine Garantie, dass das, was in einer Vorschauversion enthalten ist, in der veröffentlichten Version enthalten ist. Die Vorschau einer Version bleibt mindestens sechs Wochen nach der Veröffentlichung verfügbar.

2. Veröffentlicht

Sobald eine Vorschauversion reif ist und für die Veröffentlichung bereit ist, wird sie ohne das Suffix "-preview " verfügbar. Veröffentlichte Versionen enthalten keine grundlegenden Änderungen, obwohl das Datenmodell möglicherweise noch mit mehr Funktionen erweitert wird. Wir unterstützen veröffentlichte Versionen für mindestens 12 Monate.

3. Veraltet

Veraltete Versionen werden nicht mehr unterstützt, und Anforderungen an diese Versionen werden nicht erfüllt. Wenn Sie versuchen, eine veraltete oder nicht unterstützte Version anzufordern, erhalten Sie einen HTTP 410-Antwortcode und eine Meldung wie:

Der {version}-OData-Endpunkt für Analytics wird nicht unterstützt. Informationen zur neuesten empfohlenen Version finden Sie hier: https://go.microsoft.com/fwlink/?linkid=856818

Unterbrechen von und nicht geschützte Änderungen

Das von Analytics verfügbar gemachte Datenmodell definiert den Vertrag zwischen dem Dienst und seinen Kunden. Gemäß der OData-Spezifikation müssen Clients gegenüber additiven Änderungen am Datenmodell tolerant sein. Neue Änderungen werden in zukünftigen Versionen eingeführt. Weitere Informationen finden Sie unter OData Version 4.0 Teil 5: Versionsverwaltung.

Beispiel für geschützte Änderungen

Betrachten Sie ein Szenario, in dem der User Entität eine neue UserType Eigenschaft hinzugefügt wird. Die Metadaten für version 1.0 werden beispielsweise in der folgenden Syntax angezeigt.

<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 der Version v4.0-Preview werden die Metadaten durch additive Änderungen erweitert. Diese Änderungen können auch in früheren Versionen zur Verfügung gestellt werden.

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

Beispiel für bruchbrechende Änderungen

Betrachten Sie ein Szenario, in dem wir zur ursprünglichen Struktur der User Entität zurückkehren, was dazu führt, dass ein zuvor verfügbares Feature entfernt wird.

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

Da das Entfernen des UserType Felds eine bahnbrechende Änderung ist, wird das Feld erst entfernt, wenn Version v2.0 der API. Version v1.0 des Datenmodells enthält weiterhin das UserType Feld.

Verwandte Artikel

• Datenmodell für Analytics
• OData Version 4.0 Teil 5: Versionsverwaltung