Controllo delle versioni dell'API OData

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

Analisi per Azure DevOps offre un'API OData con controllo delle versioni compatibile con i client progettati per versioni specifiche. Ogni versione può includere miglioramenti e modifiche che non causano interruzioni, mentre le modifiche di rilievo vengono introdotte nelle versioni future.

La versione dell'API segue l'elemento _odata nel percorso della richiesta e può essere 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

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

Differenze tra le versioni

v1.0 e v2.0: le versioni rilasciate dell'API OData sono stabili e non includono modifiche di rilievo. La versione 2.0 include miglioramenti e maggiore funzionalità rispetto alla versione 1.0.

v3.0-preview e v4.0-preview: le versioni di anteprima possono includere modifiche di rilievo e non hanno la certezza di avere le stesse funzionalità nella versione finale. Offrono l'accesso anticipato a nuove funzionalità e miglioramenti che non sono ancora disponibili nelle versioni rilasciate.

Perché scegliere una versione specifica?

• Stabilità: se è necessaria un'API stabile e affidabile senza modifiche di rilievo, è consigliabile scegliere una delle versioni rilasciate (v1.0 o v2.0).
• Nuove funzionalità: se si vogliono sfruttare le funzionalità e i miglioramenti più recenti, è possibile scegliere una delle versioni di anteprima (v3.0-preview o v4.0-preview). Tuttavia, queste versioni potrebbero includere modifiche di rilievo e sono soggette a modifiche.
• Compatibilità: assicurarsi che la versione scelta sia compatibile con i client e i sistemi esistenti. La versione dell'API segue l'elemento _odata nel percorso della richiesta e può essere una delle versioni supportate: v1.0, v2.0, v3.0-preview o v4.0-preview.

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 esegue le tre fasi seguenti durante il ciclo di vita.

1. Fase di anteprima

Tutte le modifiche di rilievo vengono combinate e rilasciate insieme nelle versioni future dell'API. Per rendere questa funzionalità disponibile il prima possibile, vengono rilasciate nuove versioni in modalità di anteprima . Le modifiche di rilievo sono ancora possibili mentre una versione è in modalità di anteprima e non c'è alcuna garanzia che ciò che è incluso in una versione di anteprima venga incluso nella versione rilasciata. L'anteprima di una versione rimane disponibile per un minimo di sei settimane dopo il rilascio.

2. Rilasciato

Una volta maturata una versione di anteprima e pronta per il rilascio, diventa disponibile senza il suffisso -preview . Le versioni rilasciate non includono modifiche di rilievo, anche se il modello di dati potrebbe continuare a espandersi con altre funzionalità. Sono supportate versioni rilasciate per un minimo di 12 mesi.

3. Deprecato

Le versioni deprecate non sono più supportate e le richieste a queste versioni non vengono soddisfatte. Se si tenta di richiedere una versione deprecata o non supportata, si riceve un codice di risposta HTTP 410 e un messaggio come:

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 interruzioni

Il modello di dati esposto da Analytics definisce il contratto tra il servizio e i relativi client. In base alla specifica OData, i client devono essere tolleranti delle modifiche additive apportate al modello di dati. Le modifiche di rilievo vengono introdotte nelle versioni future. Per altre informazioni, vedere OData Versione 4.0 Parte 5: Controllo delle versioni.

Esempio di modifiche che non causano interruzioni

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

Nella versione v4.0-preview i metadati vengono aumentati con modifiche aggiuntive. Queste modifiche possono essere rese disponibili anche 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 uno scenario in cui si ripristina la struttura originale dell'entità User , con conseguente 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 viene 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