OData API sürümü oluşturma

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

Analiz hizmeti olgunlaştıkça, kullanıcılarımıza tutarlılık ve güvenilirlik sağlamaya kendimizi adadık. Bu nedenle, Azure DevOps için Analytics, bu sürümler için tasarlanmış istemcilerle uyumlu bir sürüme sahip OData API'si sağlar. Her sürüm daha fazla işlevsellik ve hataya neden olmayan değişikliklerle geliştirilebilir. Uyumsuz veya hataya neden olan değişiklikler API'nin gelecek sürümlerine dağıtılacaktır.

API sürümü, istek yolundaki _odata öğesini izler ve desteklenen sürümlerimizden biri olarak değere sahiptir: v1.0, v2.0, v3.0-preview veya v4.0-preview.

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

Not

Analiz hizmeti tüm Azure DevOps Services için otomatik olarak etkinleştirilir ve üretimde desteklenir. Power BI tümleştirmesi ve Analiz Hizmeti'nin OData akışına erişim genel olarak kullanılabilir. Bunu kullanmanızı ve bize geri bildirim göndermenizi öneririz. Kullanılabilir veriler sürüme bağlıdır. Desteklenen en son sürüm, v2.0en son önizleme sürümü ise sürümüdür v4.0-preview. Daha fazla bilgi için bkz. OData API sürümü oluşturma.

Önizleme sürümleri

• v3.0-preview
• v4.0-önizleme

Yayımlanan sürümler

• v1.0
• v2.0

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şamadan geçer.

Önizleme

Tüm hataya neden olan değişiklikler, API'nin gelecek sürümlerinde birleştirilir ve yayımlanır. Bu işlevi mümkün olan en erken zamanda kullanılabilir hale getirmek için önizleme modunda yeni sürümleri kullanıma sunabilirsiniz. Sürüm önizleme modundayken hataya neden olan değişiklikler hala mümkündür. Ayrıca, önizleme sürümüne dahil edilenlerin yayımlanmış bir sürüme dahil olacağının garantisi yoktur.

Bir sürümün önizlemesi, yayımlandıktan sonra en az altı hafta boyunca kullanılabilir.

Yayınlandı

Önizleme sürümü yayın için yeterince olgunlaştıktan sonra , -preview soneki olmadan kullanıma sunulacaktır. Yayımlanan sürümlerde hataya neden olan hiçbir değişiklik yapılmaz, ancak veri modeli yine de eklenebilir işlevsellikle büyüyebilir. Yayımlanan sürümler en az 12 ay boyunca desteklenecektir.

Kullanım Dışı

Kullanım dışı bırakılan sürümler artık desteklenmiyor. Kullanım dışı bir sürüme yapılan istekler yerine getirilmeyecek. Kullanım dışı veya desteklenmeyen bir sürüm istemeye çalışırsanız bir HTTP 410 yanıt kodu ve şöyle bir ileti alırsınız:

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

Hataya neden olan ve hataya neden olmayan değişiklikler

Analytics tarafından sunulan veri modeli, hizmet ve istemcileri arasındaki sözleşmeyi tanımlar. OData belirtimi, istemcilerin veri modelinde eklemeli değişikliklere dayanıklı olmasını gerektirir. Hataya neden olan değişiklikler gelecek 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

Not

Sistem herhangi bir özel iş öğesi alanı sürümü oluşturmaz. Ayrıca, iş öğesi veya özel alan türlerini kaldırarak veya değiştirerek modelinizde hataya neden olan değişikliklere neden olabilir. Tüm iş öğeleri ve düzeltmeleri geçerli özel alan yapılandırmasını yansıtır.

Hataya neden olmayan 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österildiği gibidir.

<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ü için meta veriler artırıldı. Değişiklikler eklenebilir ve önceki sürümlerde 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

Şimdi Kullanıcı varlığının özgün yapısına geri dönerek daha önce kullanılabilir bir özelliğin kaldırılmasına neden olduğumuz bir senaryoyu 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ını 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