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

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Аналитика для Azure DevOps предлагает api OData, совместимый с версиями, совместимым с клиентами, предназначенными для определенных версий. Каждая версия может включать улучшения и неразрывные изменения, а критические изменения вводятся в будущих версиях.

Версия API следует элементу _odata в пути запроса и может быть одной из поддерживаемых версий: версии 1.0, версии 2.0, версии 3.0-preview или версии 4.0-preview.

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

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

Различия между версиями

версии 1.0 и версии 2.0: выпущенные версии API OData стабильны и не включают критические изменения. версия 2.0 включает улучшения и больше функций по сравнению с версией 1.0.

версии 3.0-preview и версии 4.0-preview: предварительные версии могут включать критические изменения и не гарантируется, что в окончательном выпуске одинаковые функции. Они предлагают ранний доступ к новым функциям и улучшениям, которые еще не доступны в выпущенных версиях.

Зачем выбрать определенную версию?

• Стабильность. Если вам нужен стабильный и надежный API без критических изменений, следует выбрать одну из выпущенных версий (версии 1.0 или версии 2.0).
• Новые функции. Если вы хотите воспользоваться новейшими функциями и улучшениями, вы можете выбрать одну из предварительных версий (версия 3.0-preview или версии 4.0-preview). Однако эти версии могут включать критические изменения и могут быть изменены.
• Совместимость. Убедитесь, что выбранная версия совместима с существующими клиентами и системами. Версия API следует элементу _odata в пути запроса и может быть одной из поддерживаемых версий: версии 1.0, версии 2.0, версии 3.0-preview или версии 4.0-preview.

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

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

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

Каждая версия API OData проходит следующие три этапа во время жизненного цикла.

1. Этап предварительной версии

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

2. Выпущено

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

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

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

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

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

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

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

Рассмотрим сценарий, в котором новое UserType свойство добавляется в User сущность. Например, метаданные версии 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-preview метаданные дополнены аддитивными изменениями. Эти изменения также можно сделать доступными в предыдущих версиях.

<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. Управление версиями