Controllo delle versioni delle API OData

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

Man mano che il servizio Analytics è maturo, siamo dedicati alla coerenza e all'affidabilità per gli utenti. Di conseguenza, Analytics per Azure DevOps fornisce un'API OData con controllo delle versioni compatibile con i client progettati per tali versioni. Ogni versione può essere migliorata con più funzionalità e modifiche non di rilievo. Le modifiche incompatibili o di rilievo verranno implementate nelle versioni future dell'API.

La versione dell'API segue l'elemento _odata nel percorso della richiesta e ha valore come una delle versioni supportate: v1.0, v2.0, v3.0-preview o v4.0-preview.

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

Nota

Il servizio Analytics viene abilitato automaticamente e supportato nell'ambiente di produzione per tutti i Azure DevOps Services. L'integrazione di Power BI e l'accesso al feed OData del servizio Analisi sono disponibili a livello generale. Ti invitiamo a usarlo e a inviare commenti e suggerimenti. I dati disponibili dipendono dalla versione. La versione supportata più recente è v2.0e la versione di anteprima più recente è v4.0-preview. Per altre informazioni, vedere Controllo delle versioni delle API OData.

Versioni di anteprima

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

Versioni rilasciate

• v1.0
• v2.0

Set di entità supportati in ogni versione

Per informazioni su quali EntitySet sono supportati con ogni versione dell'API, vedere Modello di dati per Analisi, Entità.

Ciclo di vita della versione

Ogni versione dell'API OData passa attraverso tre fasi durante il ciclo di vita.

Anteprima

Tutte le modifiche di rilievo verranno combinate e rilasciate insieme nelle versioni future dell'API. Per rendere questa funzionalità disponibile il prima possibile, rilasciare le nuove versioni in modalità anteprima . Le modifiche che causano un'interruzione sono ancora possibili mentre una versione è in modalità di anteprima. Inoltre, non c'è garanzia che ciò che è incluso in una versione di anteprima verrà incluso in una versione rilasciata.

L'anteprima di una versione sarà disponibile per un minimo di sei settimane dopo il rilascio.

Rilasciata

Una volta maturata una versione di anteprima sufficiente per il rilascio, verrà resa disponibile senza il suffisso -preview . Non verranno introdotte modifiche di rilievo alle versioni rilasciate, ma il modello di dati potrebbe continuare a crescere con funzionalità aggiuntive. Le versioni rilasciate saranno supportate per almeno 12 mesi.

Deprecato

Le versioni deprecate non sono più supportate. Le richieste effettuate a una versione deprecata non verranno soddisfatte. Se si tenta di richiedere una versione deprecata o non supportata, si riceverà un codice di risposta HTTP 410 e un messaggio simile al seguente:

L'endpoint OData {version} per Analytics non è supportato. Le informazioni sulla versione consigliata più recente sono disponibili qui: https://go.microsoft.com/fwlink/?linkid=856818

Modifiche che causano interruzioni e non di rilievo

Il modello di dati esposto da Analytics definisce il contratto tra il servizio e i relativi client. La specifica OData richiede che i client siano tolleranti delle modifiche aggiuntive apportate al modello di dati. Le modifiche di rilievo verranno introdotte nelle versioni future. Per altre informazioni, vedere OData versione 4.0 Parte 5: Controllo delle versioni

Nota

Il sistema non esegue la versione di alcun campo dell'elemento di lavoro personalizzato. Inoltre, è possibile causare modifiche di rilievo al modello rimuovendo o modificando i tipi di elementi di lavoro o i campi personalizzati. Tutti gli elementi di lavoro e le relative revisioni rifletteranno la configurazione del campo personalizzato corrente.

Esempio di modifiche non di rilievo

Si consideri uno scenario in cui viene aggiunta una nuova UserType proprietà all'entità User . Ad esempio, i metadati per la versione 1.0 sono indicati nella sintassi seguente.

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

Per la versione v4.0-preview , i metadati sono stati aumentati. Le modifiche sono additive e possono essere rese disponibili nelle versioni precedenti.

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

Esempio di modifiche di rilievo

Si consideri ora uno scenario in cui si ripristina la struttura originale dell'entità User, causando la rimozione di una funzionalità disponibile in precedenza.

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

Poiché la UserType rimozione del campo è una modifica che causa un'interruzione, il campo non verrà rimosso fino alla versione 2.0 dell'API. La versione 1.0 del modello di dati continua a includere il UserType campo .

Articoli correlati

• Modello di dati per Analytics
• OData versione 4.0 Parte 5: Controllo delle versioni