Управление версиями API OData

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

По мере развития службы "Аналитика" мы посвящаем себя обеспечению согласованности и надежности для наших пользователей. Таким образом, Аналитика для Azure DevOps предоставляет API OData с управлением версиями, совместимый с клиентами, предназначенными для этих версий. Каждая версия может быть расширена с помощью дополнительных функциональных возможностей и некриминационных изменений. Несовместимые или критические изменения будут внесены в будущие версии API.

Версия API следует элементу _odata в пути запроса и имеет значение в качестве одной из поддерживаемых версий: v1.0, v2.0, v3.0-preview или v4.0-preview.

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

Примечание

Служба аналитики автоматически включается и поддерживается в рабочей среде для всех Azure DevOps Services. Интеграция Power BI и доступ к веб-каналу OData службы аналитики являются общедоступными. Мы рекомендуем вам использовать его и оставить отзыв. Доступные данные зависят от версии. Последняя поддерживаемая версия — v2.0, а последняя предварительная версия — v4.0-preview. Дополнительные сведения см. в разделе Управление версиями API OData.

Предварительные версии

• Версия 3.0 (предварительная версия)
• версия 4.0-preview

Выпущенные версии

• версия 1.0
• Версия 2.0

Наборы сущностей, поддерживаемые в каждой версии

Сведения о том, какие наборы EntitySet поддерживаются с каждой версией API, см. в статье Модель данных для аналитики, сущности.

Жизненный цикл версии

В течение жизненного цикла каждая версия API OData будет проходить три этапа.

Предварительный просмотр

Все критические изменения будут объединены и выпущены вместе в будущих версиях API. Чтобы сделать эту функцию доступной как можно раньше, выпустите новые версии в режиме предварительной версии . Критические изменения по-прежнему возможны, когда версия находится в режиме предварительного просмотра. Кроме того, нет никакой гарантии, что то, что входит в предварительную версию, будет включено в выпущенную версию.

Предварительная версия будет доступна не менее шести недель после выпуска.

Выпущено

После того как предварительная версия созревает достаточно для выпуска, она будет доступна без суффикса -preview . В выпущенных версиях не будут вноситься критические изменения, но модель данных может по-прежнему расширяться с помощью аддитивных функций. Выпущенные версии будут поддерживаться не менее 12 месяцев.

Не рекомендуется

Устаревшие версии больше не поддерживаются. Запросы на нерекомендуемую версию выполняться не будут. При попытке запросить нерекомендуемую или неподдерживаемую версию вы получите код ответа HTTP 410 и следующее сообщение:

Конечная точка OData {version} для Аналитики не поддерживается. Сведения о последней рекомендуемой версии доступны здесь: https://go.microsoft.com/fwlink/?linkid=856818

Критические и некримируемые изменения

Модель данных, предоставленная Аналитикой, определяет контракт между службой и ее клиентами. Спецификация OData требует, чтобы клиенты были терпимы к аддитивных изменений в модели данных. Критические изменения будут представлены в будущих версиях. Дополнительные сведения см. в разделе OData версии 4.0, часть 5. Управление версиями

Примечание

Система не выполняет версию полей настраиваемых рабочих элементов. Кроме того, можно вызвать критические изменения в модели, удалив или изменив типы рабочих элементов или настраиваемые поля. Все рабочие элементы и их редакции будут отражать текущую конфигурацию настраиваемого поля.

Пример некримивных изменений

Рассмотрим сценарий, в котором к сущности User добавляется новое UserType свойство. Например, метаданные версии 1.0 , как показано в следующем синтаксисе.

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

В предварительной версии версии 4.0 метаданные были дополнены. Изменения являются аддитивными и могут быть доступны в предыдущих версиях.

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

Пример критических изменений

Теперь рассмотрим сценарий, в котором мы отменить изменения к исходной структуре сущности User, что приводит к удалению ранее доступной функции.

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

Так как удаление UserType поля является критическим изменением, поле не будет удалено до версии 2.0 API. Версия 1.0 модели данных продолжает включать UserType поле .

Похожие статьи

• Модель данных для аналитики
• OData версии 4.0, часть 5. Управление версиями