Penerapan versi OData API

Layanan Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Analitik untuk Azure DevOps menawarkan API OData yang sudah memiliki versi, kompatibel dengan klien yang dirancang untuk versi tertentu. Setiap versi mungkin menyertakan penyempurnaan dan perubahan yang tidak merusak, sementara perubahan besar 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 dalam Azure DevOps Services. Integrasi Power BI dan akses ke umpan OData dari layanan Analytics kini tersedia secara umum. Anda dianjurkan untuk menggunakan umpan OData Analytics dan memberikan umpan balik.

Data yang tersedia bergantung pada versi. Versi terbaru yang didukung dari API OData adalah v2.0, dan versi pratinjau terbaru adalah v4.0-preview. Untuk informasi selengkapnya, lihat Pengaturan versi OData API.

Perbedaan antar versi

v1.0 dan v2.0:Versi yang dirilis dari OData API stabil dan tidak menyertakan perubahan yang mengganggu. 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 signifikan dan tidak dapat dipastikan 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 signifikan 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 mendasar bersama-sama pada versi API mendatang. Untuk membuat fungsionalitas ini tersedia sedini mungkin, kami merilis versi baru dalam mode pratinjau . Perubahan besar tetap dimungkinkan saat versi berada dalam mode pratinjau, dan tidak ada jaminan bahwa apa yang disertakan dalam versi pratinjau akan disertakan dalam versi yang dirilis. Pratinjau versi tetap tersedia selama minimal enam minggu setelah dirilis.

2. Dirilis

Setelah versi pratinjau matang dan siap untuk rilis, versi tersebut akan tersedia tanpa akhiran -preview . Versi yang dirilis tidak menyertakan perubahan yang menyebabkan kendala, meskipun model data mungkin masih diperluas dengan lebih banyak fungsi. 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:

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

Perubahan yang mengganggu vs tidak mengganggu

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 signifikan dapat diperkenalkan dalam versi mendatang. Untuk informasi selengkapnya, lihat OData Versi 4.0 Bagian 5: Pengaturan 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 mengakibatkan perubahan yang mengganggu 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 merusak

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 bidang UserType adalah perubahan yang memutus kompatibilitas, bidang tersebut 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