Przechowywanie wersji interfejsu API OData

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

Gdy usługa Analytics dojrzała, jesteśmy dedykowani, aby zapewnić spójność i niezawodność naszym użytkownikom. W związku z tym usługa Analytics for Azure DevOps udostępnia w wersji interfejs API OData zgodny z klientami zaprojektowanymi dla tych wersji. Każda wersja może zostać rozszerzona o większą funkcjonalność i zmiany powodujące niezgodność. Niezgodne lub powodujące niezgodność zmiany zostaną wprowadzone w przyszłych wersjach interfejsu API.

Wersja interfejsu API jest zgodna z elementem _odata w ścieżce żądania i ma wartość jedną z obsługiwanych wersji: v1.0, v2.0, v3.0-preview lub 4.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 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 nam 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.

Wersje wersji zapoznawczej

• Wersja 3.0 (wersja zapoznawcza)
• Wersja 4.0-preview

Wydane wersje

• wersja 1.0
• Wersja 2.0

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 przejdzie przez trzy fazy w cyklu życia.

Wersja zapoznawcza

Wszystkie zmiany powodujące niezgodność zostaną połączone i wydane razem w przyszłych wersjach interfejsu API. Aby udostępnić tę funkcję tak wcześnie, jak to możliwe, należy wydać nowe wersje w trybie wersji zapoznawczej . Zmiany powodujące niezgodność są nadal możliwe, gdy wersja jest w trybie podglądu. Ponadto nie ma gwarancji, że elementy zawarte w wersji zapoznawczej zostaną uwzględnione w wydanej wersji.

Wersja zapoznawcza wersji będzie dostępna przez co najmniej sześć tygodni po jej wydaniu.

Wydano

Gdy wersja zapoznawcza dojrzała wystarczająco dużo do wydania, zostanie udostępniona bez sufiksu -preview . Nie zostaną wprowadzone żadne zmiany powodujące niezgodność w wersjach, ale model danych może nadal rosnąć z funkcją dodawania. Wydane wersje będą obsługiwane przez co najmniej 12 miesięcy.

Przestarzałe

Przestarzałe wersje nie są już obsługiwane. Żądania wysyłane do przestarzałej wersji nie zostaną spełnione. Jeśli spróbujesz zażądać przestarzałej lub nieobsługiwanej wersji, otrzymasz kod odpowiedzi HTTP 410 i komunikat podobny do następującego:

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ść i niezgodność

Model danych uwidoczniony przez usługę Analytics definiuje kontrakt między usługą a jej klientami. Specyfikacja OData wymaga, aby klienci mogli tolerować zmiany addytywne w modelu danych. Zmiany powodujące niezgodność zostaną wprowadzone w przyszłych wersjach. Aby uzyskać więcej informacji, zobacz OData Version 4.0 Part 5: Versioning

Uwaga

System nie zawiera żadnych niestandardowych pól elementów roboczych. Ponadto istnieje możliwość spowodowania zmian powodujących niezgodność modelu przez usunięcie lub zmianę typów elementów roboczych lub pól niestandardowych. Wszystkie elementy robocze i ich poprawki będą odzwierciedlać bieżącą konfigurację pola niestandardowego.

Przykład zmian powodujących niezgodność

Rozważmy scenariusz, w którym nowa UserType właściwość jest dodawana do User jednostki. Na przykład metadane wersji 1.0 są pokazane w poniższej 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 przypadku wersji 4.0-preview metadane zostały rozszerzone. Zmiany są addytywne i mogą być udostępniane 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ść

Teraz rozważmy scenariusz, w którym przywracamy oryginalną strukturę jednostki Użytkownik, powodując 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.

Pokrewne artykuły:

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