Penerapan versi OData API

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Analitik untuk Azure DevOps menawarkan API OData versi yang kompatibel dengan klien yang dirancang untuk versi tertentu. Setiap versi mungkin menyertakan penyempurnaan dan perubahan yang tidak pecah, sementara perubahan yang melanggar diperkenalkan dalam versi mendatang.

Versi API mengikuti _odata elemen di jalur permintaan dan dapat menjadi salah satu versi yang didukung: v1.0, v2.0, v3.0-preview, atau v4.0-preview.

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

Catatan

Layanan Analitik diaktifkan secara otomatis dan didukung dalam produksi untuk semua Layanan Azure DevOps. Integrasi dan akses Power BI ke umpan OData Dari Layanan Analitik umumnya tersedia. Kami mendorong Anda untuk menggunakannya dan memberi kami umpan balik. Data yang tersedia bergantung pada versi. Versi terbaru yang didukung adalah v2.0, dan versi pratinjau terbaru adalah v4.0-preview. Untuk informasi selengkapnya, lihat Penerapan versi OData API.

Perbedaan antar versi

v1.0 dan v2.0: Versi OData API yang dirilis stabil dan tidak menyertakan perubahan yang melanggar. v2.0 mencakup peningkatan dan lebih banyak fungsi dibandingkan dengan v1.0.

v3.0-preview dan v4.0-preview: Versi pratinjau mungkin menyertakan perubahan yang melanggar dan tidak dijamin memiliki fitur yang sama dalam rilis akhir. Mereka menawarkan akses awal ke fitur dan peningkatan baru yang belum tersedia dalam versi yang dirilis.

Mengapa memilih versi tertentu?

• Stabilitas: Jika Anda memerlukan API yang stabil dan andal tanpa melanggar perubahan, Anda harus memilih salah satu versi yang dirilis (v1.0 atau v2.0).
• Fitur baru: Jika Anda ingin memanfaatkan fitur dan peningkatan terbaru, Anda mungkin memilih salah satu versi pratinjau (v3.0-preview atau v4.0-preview). Namun, versi ini mungkin termasuk perubahan yang melanggar dan dapat berubah.
• Kompatibilitas: Pastikan versi yang Anda pilih kompatibel dengan klien dan sistem yang ada. Versi API mengikuti _odata elemen di jalur permintaan dan dapat menjadi salah satu versi yang didukung: v1.0, v2.0, v3.0-preview, atau v4.0-preview.

Kumpulan entitas yang didukung di setiap versi

Untuk informasi tentang EntitySets mana yang didukung dengan setiap versi API, lihat Model data untuk Analitik, Entitas.

Siklus hidup versi

Setiap versi API OData melewati tiga fase berikut selama siklus hidupnya.

1. Fase pratinjau

Kami menggabungkan dan merilis semua perubahan yang melanggar bersama-sama dalam versi API yang akan datang. Untuk membuat fungsionalitas ini tersedia sedini mungkin, kami merilis versi baru dalam mode pratinjau . Perubahan yang melanggar masih dimungkinkan saat versi berada dalam mode pratinjau, dan tidak ada jaminan bahwa apa yang disertakan dalam versi pratinjau disertakan dalam versi yang dirilis. Pratinjau versi tetap tersedia selama minimal enam minggu setelah rilis.

2. Dirilis

Setelah versi pratinjau matang dan siap untuk rilis, versi tersebut akan tersedia tanpa akhiran -preview . Versi yang dirilis tidak menyertakan perubahan yang melanggar, meskipun model data mungkin masih diperluas dengan lebih banyak fungsionalitas. Kami mendukung versi yang dirilis selama minimal 12 bulan.

3. Tidak digunakan lagi

Versi yang tidak digunakan lagi tidak lagi didukung, dan permintaan ke versi ini tidak terpenuhi. Jika Anda mencoba meminta versi yang tidak digunakan lagi atau tidak didukung, Anda menerima kode respons HTTP 410 dan pesan seperti:

Titik akhir OData {version} untuk Analitik tidak didukung. Informasi tentang versi terbaru yang direkomendasikan tersedia di sini: https://go.microsoft.com/fwlink/?linkid=856818

Perubahan melanggar vs non-pecah

Model data yang diekspos oleh Analytics menentukan kontrak antara layanan dan kliennya. Menurut spesifikasi OData, klien harus toleran terhadap perubahan aditif pada model data. Perubahan yang melanggar diperkenalkan dalam versi mendatang. Untuk informasi selengkapnya, lihat OData Versi 4.0 Bagian 5: Penerapan versi.

Catatan

Sistem tidak membuat versi bidang item kerja kustom apa pun. Sistem tidak membuat versi bidang item kerja kustom apa pun. Menghapus atau mengubah jenis item kerja atau bidang kustom dapat menyebabkan perubahan yang melanggar pada model Anda. Semua item kerja dan revisinya mencerminkan konfigurasi bidang kustom saat ini.

Contoh perubahan yang tidak pecah

Pertimbangkan skenario di mana properti baru UserType ditambahkan ke User entitas. Misalnya, metadata untuk versi v1.0 diperlihatkan dalam sintaks berikut.

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

Dalam versi v4.0-preview, metadata ditambahkan dengan perubahan aditif. Perubahan ini juga dapat tersedia di versi sebelumnya.

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

Contoh perubahan yang melanggar

Pertimbangkan skenario di mana kita kembali ke struktur User asli entitas, yang mengakibatkan penghapusan fitur yang tersedia sebelumnya.

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

Karena penghapusan UserType bidang adalah perubahan yang melanggar, bidang tidak dihapus hingga versi v2.0 API. Model data versi v1.0 terus menyertakan UserType bidang .

Artikel terkait

• Model data untuk Analitik
• OData Versi 4.0 Bagian 5: Penerapan versi