Penerapan versi OData API

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

Saat layanan Analytics matang, kami berdedikasi untuk memberikan konsistensi dan keandalan kepada pengguna kami. Dengan demikian, Analytics untuk Azure DevOps menyediakan API OData versi yang kompatibel dengan klien yang dirancang untuk versi tersebut. Setiap versi dapat ditingkatkan dengan lebih banyak fungsionalitas dan perubahan yang tidak melanggar. Perubahan yang tidak kompatibel atau melanggar akan digulirkan ke versi API yang akan datang.

Versi API mengikuti elemen _odata di jalur permintaan dan memiliki nilai sebagai salah satu versi kami 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 Analytics 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.

Versi pratinjau

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

Versi yang dirilis

• v1.0
• v2.0

Kumpulan entitas yang didukung di setiap versi

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

Siklus hidup versi

Setiap versi API OData akan melalui tiga fase selama siklus hidupnya.

Pratinjau

Semua perubahan yang melanggar akan digabungkan dan dirilis bersama-sama dalam versi API yang akan datang. Untuk membuat fungsionalitas ini tersedia sedini mungkin, rilis versi baru dalam mode pratinjau . Perubahan yang melanggar masih dimungkinkan saat versi dalam mode pratinjau. Selain itu, tidak ada jaminan bahwa apa yang disertakan dalam versi pratinjau akan disertakan dalam versi yang dirilis.

Pratinjau versi akan tersedia selama minimal enam minggu setelah dirilis.

Dirilis

Setelah versi pratinjau cukup matang untuk rilis, versi tersebut akan tersedia tanpa akhiran -preview . Tidak ada perubahan yang melanggar yang akan diperkenalkan ke versi yang dirilis, tetapi model data mungkin masih tumbuh dengan fungsionalitas aditif. Versi yang dirilis akan didukung selama minimal 12 bulan.

Tidak digunakan lagi

Versi yang tidak digunakan lagi tidak didukung. Permintaan yang dibuat ke versi yang tidak digunakan lagi tidak akan terpenuhi. Jika Anda mencoba meminta versi yang tidak digunakan lagi atau tidak didukung, Anda akan 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 mencolok vs tidak melanggar

Model data yang diekspos oleh Analytics menentukan kontrak antara layanan dan kliennya. Spesifikasi OData mengharuskan klien toleran terhadap perubahan aditif pada model data. Perubahan yang melanggar akan 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. Selain itu, dimungkinkan untuk menyebabkan perubahan yang melanggar pada model Anda dengan menghapus, atau mengubah jenis item kerja atau bidang kustom. Semua item kerja, dan revisinya, akan mencerminkan konfigurasi bidang kustom saat ini.

Contoh perubahan yang tidak melanggar

Pertimbangkan skenario di mana properti baru UserType ditambahkan ke User entitas. Misalnya, metadata untuk versi v1.0 seperti yang ditunjukkan 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>

Untuk versi v4.0-preview , metadata telah ditambungkan. Perubahan bersifat aditif dan 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

Sekarang pertimbangkan skenario di mana kita kembali ke struktur asli entitas Pengguna, menyebabkan 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 akan dihapus hingga versi v2.0 DARI API. Model data versi v1.0 terus menyertakan UserType bidang .

Artikel terkait

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