OData API sürümü oluşturma

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

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ümde iyileştirmeler ve bölünemez değişiklikler bulunurken, hataya neden olan değişiklikler gelecek sürümlerde kullanıma sunulacaktı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

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/$metadata

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ı

Tüm hataya neden olan değişiklikleri API'nin gelecek sürümlerinde birleştirir ve yayınları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 hataya neden olan değişiklikler yine de mümkündür ve önizleme sürümündeki değişikliklerin 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ştıktan ve yayına hazır olduğunda , -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

Hataya neden olan ve bölünemeyen değişikliklerle karşılaştırma

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. Hataya neden olan değişiklikler sonraki sürümlerde kullanıma sunulacaktır. Daha fazla bilgi için bkz . OData Sürüm 4.0 Bölüm 5: Sürüm oluşturma.

Bölünemez değişiklikler örneği

Varlığa yeni UserType bir özelliğin eklendiği bir senaryo düşünün User . Ö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>

Hataya neden olan 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