Versionshantering för OData API

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

I takt med att Analytics-tjänsten mognar är vi dedikerade till att ge våra användare konsekvens och tillförlitlighet. Därför tillhandahåller Analytics för Azure DevOps ett versionshanterat OData-API som är kompatibelt med klienter som är utformade för dessa versioner. Varje version kan förbättras med fler funktioner och icke-bakåtkompatibla ändringar. Inkompatibla eller icke-bakåtkompatibla ändringar kommer att distribueras till framtida versioner av API:et.

API-versionen följer elementet _odata i begärandesökvägen och har värdet som en av våra versioner som stöds: v1.0, v2.0, v3.0-preview eller v4.0-preview.

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

Anteckning

Analytics-tjänsten aktiveras automatiskt och stöds i produktion för alla Azure DevOps-tjänster. Power BI-integrering och åtkomst till OData-flödet för Analystjänsten är allmänt tillgängliga. Vi rekommenderar att du använder den och ger oss feedback. Tillgängliga data är versionsberoende. Den senaste versionen som stöds är v2.0och den senaste förhandsversionen är v4.0-preview. Mer information finns i OData API-versionshantering.

Förhandsversioner

• v3.0-förhandsversion
• v4.0-förhandsversion

Utgivna versioner

• v1.0
• v2.0

Entitetsuppsättningar som stöds i varje version

Information om vilka EntitySets som stöds med varje API-version finns i Datamodell för analys, entiteter.

Versionslivscykel

Varje version av OData-API:et går igenom tre faser under livscykeln.

Förhandsgranskning

Alla icke-bakåtkompatibla ändringar kombineras och släpps tillsammans i framtida versioner av API:et. Om du vill göra den här funktionen tillgänglig så tidigt som möjligt bör du släppa nya versioner i förhandsgranskningsläge . Icke-bakåtkompatibla ändringar är fortfarande möjliga när en version är i förhandsgranskningsläge. Det finns heller ingen garanti för att det som ingår i en förhandsversion inkluderas i en utgiven version.

Förhandsversionen av en version kommer att vara tillgänglig i minst sex veckor efter att den har släppts.

Släppt

När en förhandsversion har mognat tillräckligt för lansering görs den tillgänglig utan suffixet -preview . Inga icke-bakåtkompatibla ändringar kommer att introduceras i utgivna versioner, men datamodellen kan fortfarande växa med additiva funktioner. Versioner som har släppts stöds i minst 12 månader.

Inaktuell

Inaktuella versioner stöds inte längre. Begäranden som görs till en inaktuell version uppfylls inte. Om du försöker begära en inaktuell eller icke-stödd version får du en HTTP 410-svarskod och ett meddelande som:

OData-slutpunkten {version} för analys stöds inte. Information om den senaste rekommenderade versionen finns här: https://go.microsoft.com/fwlink/?linkid=856818

Icke-bakåtkompatibla eller icke-bakåtkompatibla ändringar

Datamodellen som exponeras av Analytics definierar kontraktet mellan tjänsten och dess klienter. OData-specifikationen kräver att klienterna är toleranta mot additiva ändringar i datamodellen. Icke-bakåtkompatibla ändringar kommer att introduceras i framtida versioner. Mer information finns i OData Version 4.0 Del 5: Versionshantering

Anteckning

Systemet versionshanterade inte några anpassade arbetsobjektfält. Det är också möjligt att orsaka icke-bakåtkompatibla ändringar i din modell genom att ta bort eller ändra typerna av arbetsobjekt eller anpassade fält. Alla arbetsobjekt och deras revisioner återspeglar den aktuella konfigurationen för anpassade fält.

Exempel på icke-bakåtkompatibla ändringar

Tänk dig ett scenario där en ny UserType egenskap läggs till i entiteten User . Metadata för v1.0-versionen är till exempel som visas i följande syntax.

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

För v4.0-förhandsversionen har metadata utökats. Ändringar är additiva och kan göras tillgängliga i tidigare versioner.

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

Exempel på icke-bakåtkompatibla ändringar

Tänk dig nu ett scenario där vi återgår till den ursprungliga strukturen för användarentiteten, vilket gör att en tidigare tillgänglig funktion tas bort.

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

Eftersom borttagningen UserType av fältet är en icke-bakåtkompatibel ändring tas fältet inte bort förrän version v2.0 av API:et. Version v1.0 av datamodellen fortsätter att innehålla fältet UserType .

Relaterade artiklar

• Datamodell för analys
• OData version 4.0 Del 5: Versionshantering