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

Примечание.

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

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

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