OData API sürümleme

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Azure DevOps için Analiz, belirli sürümler için tasarlanmış istemcilerle uyumlu, sürümlenmiş bir OData API'si sunar. Her sürüm iyileştirmeler ve kesintisiz değişiklikler içerebilirken, bozan değişiklikler gelecekteki sürümlerde tanıtılacaktır.

API sürümü, istek yolundaki öğesini izler _odata ve desteklenen sürümlerden biri olabilir: v1.0, v2.0, v3.0-preview veya v4.0-preview.

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

Not

Analiz hizmeti, Azure DevOps Services içindeki tüm hizmetler için üretimde otomatik olarak etkinleştirilir ve desteklenir. Power BI tümleştirmesi ve Analiz hizmetinin OData akışına erişim genel olarak kullanılabilir. Analytics OData akışını kullanmanız ve geri bildirim sağlamanız teşvik edilir.

Kullanılabilir veriler sürüme bağlıdır. OData API'sinin desteklenen en son sürümü, v2.0en son önizleme sürümü ise şeklindedir v4.0-preview. Daha fazla bilgi için bkz . OData API sürümü oluşturma.

Sürümler arasındaki farklar

v1.0 ve v2.0:OData API'sinin yayımlanan sürümleri kararlıdır ve hataya neden olan değişiklikleri içermez. v2.0, v1.0 ile karşılaştırıldığında iyileştirmeler ve daha fazla işlevsellik içerir.

v3.0-preview ve v4.0-preview:Önizleme sürümleri hataya neden olan değişiklikler içerebilir ve son sürümde aynı özelliklere sahip olması garanti değildir. Henüz yayımlanan sürümlerde bulunmayan yeni özelliklere ve iyileştirmelere erken erişim sunar.

Neden belirli bir sürümü seçmelisiniz?

• Kararlılık: Değişiklik yapmadan kararlı ve güvenilir bir API'ye ihtiyacınız varsa, yayımlanan sürümlerden birini (v1.0 veya v2.0) seçmelisiniz.
• Yeni özellikler: En son özelliklerden ve geliştirmelerden yararlanmak istiyorsanız, önizleme sürümlerinden birini (v3.0-preview veya v4.0-preview) tercih edebilirsiniz. Ancak, bu sürümler hataya neden olan değişiklikler içerebilir ve değiştirilebilir.
• Uyumluluk: Seçtiğiniz sürümün mevcut istemcileriniz ve sistemlerinizle uyumlu olduğundan emin olun. API sürümü, istek yolundaki öğesini izler _odata ve desteklenen sürümlerden biri olabilir: v1.0, v2.0, v3.0-preview veya v4.0-preview.

Her sürümde desteklenen varlık kümeleri

Her API sürümünde hangi EntitySet'lerin desteklendiği hakkında bilgi için bkz . Analiz, Varlıklar için veri modeli.

Sürüm yaşam döngüsü

OData API'sinin her sürümü yaşam döngüsü boyunca aşağıdaki üç aşamadan geçer.

1. Önizleme aşaması

API'deki tüm uyumsuzluk yaratan değişiklikleri gelecekteki sürümlerde birleştirir ve yayımlarız. Bu işlevi mümkün olan en erken zamanda kullanılabilir hale getirmek için yeni sürümleri önizleme modunda yayınlarız. Sürüm önizleme modundayken büyük değişiklikler yine de mümkündür ve önizleme sürümündeki özelliklerin yayımlanan sürüme dahil olması garanti değildir. Sürümün önizlemesi, yayımlandıktan sonra en az altı hafta boyunca kullanılabilir durumda kalır.

2. Yayınlandı

Önizleme sürümü olgunlaşıp yayına hazır hale geldiğinde, -preview soneki olmadan kullanılabilir hale gelir. Yayımlanan sürümler hataya neden olan değişiklikleri içermez, ancak veri modeli daha fazla işlevsellikle genişleyebilir. Yayınlanan sürümleri en az 12 ay boyunca destekliyoruz.

3. Kullanım dışı

Kullanım dışı bırakılan sürümler artık desteklenmemektedir ve bu sürümlere yönelik istekler karşılanmamıştır. Kullanım dışı veya desteklenmeyen bir sürüm istemeye çalışırsanız, bir HTTP 410 yanıt kodu ve aşağıdaki gibi bir ileti alırsınız:

Analytics için {version} OData uç noktası desteklenmiyor. Önerilen en son sürümle ilgili bilgilere buradan ulaşabilirsiniz: https://go.microsoft.com/fwlink/?linkid=856818

Kritik (Bozan) Değişiklikler ve Kritik Olmayan Değişiklikler Karşılaştırması

Analytics tarafından sunulan veri modeli, hizmetle istemcileri arasındaki sözleşmeyi tanımlar. OData belirtimine göre, istemcilerin veri modelinde yapılan eklemeli değişikliklere dayanıklı olması gerekir. Geriye dönük uyumluluğu bozan değişiklikler gelecekteki sürümlerde tanıtılacaktır. Daha fazla bilgi için bkz . OData Sürüm 4.0 Bölüm 5: Sürüm oluşturma.

Not

Sistem herhangi bir özel iş öğesi alanı sürümü oluşturmaz. Sistem herhangi bir özel iş öğesi alanı sürümü oluşturmaz. İş öğesi türlerinin veya özel alan türlerinin kaldırılması veya değiştirilmesi modelinizde bozulmalara neden olabilir. Tüm iş öğeleri ve düzeltmeleri geçerli özel alan yapılandırmasını yansıtır.

Bozulmayan değişiklikler örneği

Yeni bir UserType özelliği User varlığa eklendiği bir senaryoyu düşünün. Örneğin, v1.0 sürümünün meta verileri aşağıdaki söz diziminde gösterilir.

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

v4.0-preview sürümünde meta veriler ek değişikliklerle genişletilir. Bu değişiklikler önceki sürümlerde de kullanılabilir hale getirilebilir.

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

Kırılma yaratan değişiklikler örneği

Varlığın özgün yapısına User geri dönerek daha önce kullanılabilir bir özelliğin kaldırılmasıyla sonuçlandığı bir senaryo düşünün.

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

Alanın kaldırılması UserType hataya neden olan bir değişiklik olduğundan, alan API'nin v2.0 sürümüne kadar kaldırılmaz. Veri modelinin v1.0 sürümü alanı eklemeye UserType devam eder.

İlgili makaleler

• Analiz için veri modeli
• OData Sürüm 4.0 Bölüm 5: Sürüm Oluşturma