Przechowywanie wersji interfejsu API OData

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

Analiza dla usługi Azure DevOps oferuje wersjonowany interfejs API OData zgodny z klientami zaprojektowanymi dla określonych wersji. Każda wersja może zawierać ulepszenia i niełamające się zmiany, podczas gdy zmiany powodujące niezgodność są wprowadzane w przyszłych wersjach.

Wersja interfejsu _odata API jest zgodna z elementem w ścieżce żądania i może być jedną z obsługiwanych wersji: v1.0, v2.0, v3.0-preview lub v4.0-preview.

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

Uwaga

Usługa Analytics jest automatycznie włączona i obsługiwana w środowisku produkcyjnym dla wszystkich usług Azure DevOps Services. Integracja usługi Power BI i dostęp do źródła danych OData usługi Analytics są ogólnie dostępne. Zachęcamy do korzystania z niego i przekazywania opinii. Dostępne dane są zależne od wersji. Najnowsza obsługiwana wersja to v2.0, a najnowsza wersja zapoznawcza to v4.0-preview. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji interfejsu API OData.

Różnice między wersjami

Wersje 1.0 i v2.0: wydane wersje interfejsu API OData są stabilne i nie obejmują zmian powodujących niezgodność. Wersja 2.0 zawiera ulepszenia i więcej funkcji w porównaniu z wersją 1.0.

Wersja 3.0-preview i wersja 4.0-preview: wersje zapoznawcza mogą zawierać zmiany powodujące niezgodność i nie mają gwarancji, że te same funkcje są dostępne w ostatecznej wersji. Oferują one wczesny dostęp do nowych funkcji i ulepszeń, które nie są jeszcze dostępne w wydanych wersjach.

Dlaczego warto wybrać określoną wersję?

• Stabilność: Jeśli potrzebujesz stabilnego i niezawodnego interfejsu API bez zmian powodujących niezgodność, wybierz jedną z wydanych wersji (wersja 1.0 lub wersja 2.0).
• Nowe funkcje: jeśli chcesz korzystać z najnowszych funkcji i ulepszeń, możesz wybrać jedną z wersji zapoznawczych (wersja 3.0-preview lub wersja 4.0-preview). Jednak te wersje mogą obejmować zmiany powodujące niezgodność i mogą ulec zmianie.
• Zgodność: upewnij się, że wybrana wersja jest zgodna z istniejącymi klientami i systemami. Wersja interfejsu _odata API jest zgodna z elementem w ścieżce żądania i może być jedną z obsługiwanych wersji: v1.0, v2.0, v3.0-preview lub v4.0-preview.

Zestawy jednostek obsługiwane w każdej wersji

Aby uzyskać informacje o tym, które zestawy EntitySet są obsługiwane w każdej wersji interfejsu API, zobacz Model danych dla analiz, jednostek.

Cykl życia wersji

Każda wersja interfejsu API OData przechodzi przez następujące trzy fazy w cyklu życia.

1. Faza podglądu

Łączymy i zwalniamy wszystkie zmiany powodujące niezgodność w przyszłych wersjach interfejsu API. Aby udostępnić tę funkcję tak szybko, jak to możliwe, udostępnimy nowe wersje w trybie wersji zapoznawczej . Zmiany powodujące niezgodność są nadal możliwe, gdy wersja jest w trybie wersji zapoznawczej i nie ma gwarancji, że informacje zawarte w wersji zapoznawczej zostaną uwzględnione w wydanej wersji. Wersja zapoznawcza wersji pozostaje dostępna przez co najmniej sześć tygodni po wydaniu.

2. Wydano

Gdy wersja zapoznawcza dojrzała i będzie gotowa do wydania, staje się dostępna bez sufiksu -preview . Wydane wersje nie zawierają zmian powodujących niezgodność, chociaż model danych może nadal rozszerzać się o więcej funkcji. Obsługujemy wersje wydane przez co najmniej 12 miesięcy.

3. Przestarzałe

Przestarzałe wersje nie są już obsługiwane, a żądania do tych wersji nie są spełnione. Jeśli próbujesz zażądać przestarzałej lub nieobsługiwanej wersji, otrzymasz kod odpowiedzi HTTP 410 i komunikat, taki jak:

Punkt końcowy OData {version} dla analizy nie jest obsługiwany. Informacje o najnowszej zalecanej wersji są dostępne tutaj: https://go.microsoft.com/fwlink/?linkid=856818

Zmiany powodujące niezgodność a niezgodność

Model danych uwidoczniony przez usługę Analytics definiuje kontrakt między usługą a jej klientami. Zgodnie ze specyfikacją OData klienci muszą być odporni na zmiany addytywne w modelu danych. Zmiany powodujące niezgodność są wprowadzane w przyszłych wersjach. Aby uzyskać więcej informacji, zobacz OData Version 4.0 Part 5: Versioning (Wersja 4.0— część 5: przechowywanie wersji).

Uwaga

System nie wersjonuje żadnych niestandardowych pól elementów roboczych. System nie wersjonuje żadnych niestandardowych pól elementów roboczych. Usunięcie lub zmiana typów elementów roboczych lub pól niestandardowych może spowodować niezgodność zmian w modelu. Wszystkie elementy robocze i ich poprawki odzwierciedlają bieżącą konfigurację pola niestandardowego.

Przykład niełamających się zmian

Rozważmy scenariusz, w którym nowa UserType właściwość jest dodawana do User jednostki. Na przykład metadane wersji 1.0 są wyświetlane w następującej składni.

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

W wersji 4.0-preview metadane są rozszerzone o zmiany addytywne. Te zmiany można również udostępnić w poprzednich wersjach.

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

Przykład zmian powodujących niezgodność

Rozważmy scenariusz, w którym przywracamy oryginalną strukturę User jednostki, co powoduje usunięcie wcześniej dostępnej funkcji.

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

Ponieważ usunięcie UserType pola jest zmianą powodującą niezgodność, pole nie zostanie usunięte do wersji 2.0 interfejsu API. Wersja 1.0 modelu danych nadal zawiera UserType pole.

Powiązane artykuły

• Model danych dla analizy
• OData w wersji 4.0 — część 5: przechowywanie wersji