OData-API-Versionsverwaltung

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

Mit zunehmender Reifung des Analytics-Diensts möchten wir unseren Benutzern Konsistenz und Zuverlässigkeit bieten. Daher stellt Analytics für Azure DevOps eine versionierte OData-API bereit, die mit Clients kompatibel ist, die für diese Versionen entwickelt wurden. Jede Version kann mit mehr Funktionalität und nicht breaking Änderungen erweitert werden. Inkompatible oder fehlerhafte Änderungen werden in zukünftigen Versionen der API eingeführt.

Die API-Version folgt dem _odata-Element im Anforderungspfad und hat den Wert als eine unserer unterstützten Versionen: v1.0, v2.0, v3.0-preview oder v4.0-preview.

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

Hinweis

Der Analytics-Dienst wird automatisch aktiviert und in der Produktion für alle Azure DevOps Services unterstützt. Die Power BI-Integration und der Zugriff auf den OData-Feed des Analytics-Diensts sind allgemein verfügbar. Wir empfehlen Ihnen, es zu verwenden und uns Feedback zu geben. Verfügbare Daten sind versionsabhängig. Die neueste unterstützte Version ist v2.0, und die neueste Vorschauversion ist v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

Vorschauversionen

• v3.0-preview
• v4.0-preview

Veröffentlichte Versionen

• v1.0
• v2.0

Entitätsgruppen, die in jeder Version unterstützt werden

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

Versionslebenszyklus

Jede Version der OData-API durchläuft während ihres Lebenszyklus drei Phasen.

Vorschau

Alle Breaking Changes werden in zukünftigen Versionen der API kombiniert und veröffentlicht. Um diese Funktionalität so früh wie möglich verfügbar zu machen, veröffentlichen Sie neue Versionen im Vorschaumodus . Breaking Changes sind weiterhin möglich, während sich eine Version im Vorschaumodus befindet. Außerdem gibt es keine Garantie dafür, dass das, was in einer Vorschauversion enthalten ist, in einer veröffentlichten Version enthalten ist.

Die Vorschauversion einer Version ist mindestens sechs Wochen nach ihrer Veröffentlichung verfügbar.

Freigegeben

Sobald eine Vorschauversion reif genug für die Veröffentlichung ist, wird sie ohne das Suffix -preview verfügbar gemacht. Es werden keine Breaking Changes für veröffentlichte Versionen eingeführt, aber das Datenmodell kann immer noch mit additiver Funktionalität wachsen. Veröffentlichte Versionen werden mindestens 12 Monate lang unterstützt.

Als veraltet markiert

Veraltete Versionen werden nicht mehr unterstützt. Anforderungen an eine veraltete Version 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

Breaking- und Non-Breaking-Änderungen

Das von Analytics verfügbar gemachte Datenmodell definiert den Vertrag zwischen dem Dienst und seinen Clients. Die OData-Spezifikation erfordert, dass Clients gegenüber additiven Änderungen am Datenmodell tolerant sind. Breaking Changes werden in zukünftigen Versionen eingeführt. Weitere Informationen finden Sie unter OData Version 4.0 Part 5: Versionsverwaltung

Hinweis

Benutzerdefinierte Arbeitselementfelder werden vom System nicht versioniert. Außerdem ist es möglich, fehlerhafte Änderungen an Ihrem Modell zu verursachen, indem Sie die Typen von Arbeitselementen oder benutzerdefinierten Feldern entfernen oder ändern. Alle Arbeitselemente und ihre Überarbeitungen spiegeln die aktuelle konfiguration des benutzerdefinierten Felds wider.

Beispiel für unterbrechungsfreie Ä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 sind beispielsweise wie in der folgenden Syntax dargestellt.

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

Für version 4.0-preview wurden die Metadaten erweitert. Änderungen sind additiv und können in früheren Versionen verfügbar gemacht 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 Breaking Changes

Betrachten Sie nun ein Szenario, in dem wir auf die ursprüngliche Struktur der Benutzerentität rückgängig machen, wodurch 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 wichtige Änderung ist, wird das Feld erst ab Version 2.0 der API entfernt. Version 1.0 des Datenmodells enthält weiterhin das UserType Feld.

Verwandte Artikel

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