OData API 버전 관리

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

Azure DevOps용 Analytics는 특정 버전을 위해 설계된 클라이언트와 호환되는 버전이 지정된 OData API를 제공합니다. 각 버전에는 향상된 기능과 변경되지 않는 변경 내용이 포함될 수 있으며, 이후 버전에서는 호환성이 손상되는 변경 내용이 도입될 수 있습니다.

API 버전은 요청 경로의 _odata 요소를 따르며 v1.0, v2.0, v3.0-preview 또는 v4.0-preview와 같은 지원되는 버전 중 하나일 수 있습니다.

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

참고 항목

Analytics 서비스는 모든 Azure DevOps Services에 대해 프로덕션에서 자동으로 사용하도록 설정되고 지원됩니다. Analytics Service의 OData 피드에 대한 Power BI 통합 및 액세스는 일반적으로 사용할 수 있습니다. 이를 사용하고 피드백을 제공하는 것이 좋습니다. 사용 가능한 데이터는 버전에 따라 다릅니다. 지원되는 최신 버전은 v2.0최신 미리 보기 버전입니다 v4.0-preview. 자세한 내용은 OData API 버전 관리를 참조 하세요.

버전 간 차이점

v1.0 및 v2.0: 릴리스된 버전의 OData API는 안정적이며 호환성이 손상되는 변경은 포함하지 않습니다. v2.0에는 v1.0에 비해 향상된 기능과 더 많은 기능이 포함되어 있습니다.

v3.0-preview 및 v4.0-preview: 미리 보기 버전에는 호환성이 손상되는 변경 내용이 포함될 수 있으며 최종 릴리스에서 동일한 기능이 보장되지 않습니다. 릴리스된 버전에서는 아직 사용할 수 없는 새로운 기능 및 향상된 기능에 대한 초기 액세스를 제공합니다.

특정 버전을 선택하는 이유는 무엇인가요?

• 안정성: 호환성이 손상되는 변경 없이 안정적이고 안정적인 API가 필요한 경우 릴리스된 버전(v1.0 또는 v2.0) 중 하나를 선택해야 합니다.
• 새로운 기능: 최신 기능 및 향상된 기능을 활용하려면 미리 보기 버전(v3.0-preview 또는 v4.0-preview) 중 하나를 선택할 수 있습니다. 그러나 이러한 버전에는 호환성이 손상되는 변경 내용이 포함될 수 있으며 변경될 수 있습니다.
• 호환성: 선택한 버전이 기존 클라이언트 및 시스템과 호환되는지 확인합니다. API 버전은 요청 경로의 _odata 요소를 따르며 v1.0, v2.0, v3.0-preview 또는 v4.0-preview와 같은 지원되는 버전 중 하나일 수 있습니다.

각 버전에서 지원되는 엔터티 집합

각 API 버전에서 지원되는 EntitySets에 대한 자세한 내용은 분석, 엔터티에 대한 데이터 모델을 참조 하세요.

버전 수명 주기

OData API의 각 버전은 수명 주기 동안 다음 세 단계를 수행합니다.

1. 미리 보기 단계

이후 버전의 API에서 모든 호환성이 손상되는 변경 내용을 결합하고 릴리스합니다. 이 기능을 가능한 한 빨리 사용할 수 있도록 미리 보기 모드에서 새 버전을 릴리스합니다. 버전이 미리 보기 모드에 있는 동안에도 호환성이 손상되는 변경이 가능하며 미리 보기 버전에 포함된 내용이 릴리스 버전에 포함된다는 보장은 없습니다. 버전 미리 보기는 릴리스 후 최소 6주 동안 사용할 수 있습니다.

2. 릴리스됨

미리 보기 버전이 완성되고 릴리스 준비가 되면 -preview 접미사 없이 사용할 수 있게 됩니다. 릴리스된 버전에는 주요 변경 내용이 포함되지 않지만 데이터 모델은 더 많은 기능으로 확장될 수 있습니다. 릴리스된 버전은 최소 12개월 동안 지원됩니다.

3. 사용되지 않음

사용되지 않는 버전은 더 이상 지원되지 않으며 이러한 버전에 대한 요청은 처리되지 않습니다. 더 이상 사용되지 않거나 지원되지 않는 버전을 요청하려고 하면 HTTP 410 응답 코드와 다음과 같은 메시지가 표시됩니다.

분석용 {version} OData 엔드포인트는 지원되지 않습니다. 권장되는 최신 버전에 대한 정보는 다음에서 확인할 수 있습니다. https://go.microsoft.com/fwlink/?linkid=856818

호환성이 손상되는 변경과 호환되지 않는 변경 내용

Analytics에서 노출하는 데이터 모델은 서비스와 해당 클라이언트 간의 계약을 정의합니다. OData 사양에 따라 클라이언트는 데이터 모델에 대한 추가 변경에 관대해야 합니다. 호환성이 손상되는 변경 내용은 이후 버전에서 도입됩니다. 자세한 내용은 OData 버전 4.0 5부: 버전 관리를 참조 하세요.

참고 항목

시스템은 사용자 지정 작업 항목 필드의 버전을 지정하지 않습니다. 시스템은 사용자 지정 작업 항목 필드의 버전을 지정하지 않습니다. 작업 항목 또는 사용자 지정 필드의 유형을 제거하거나 변경하면 모델 변경 내용이 손상될 수 있습니다. 모든 작업 항목 및 해당 수정 내용은 현재 사용자 지정 필드 구성을 반영합니다.

변경되지 않는 변경의 예

새 UserType 속성이 엔터티에 추가되는 시나리오를 User 고려합니다. 예를 들어 v1.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>

v4.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 는 호환성이 손상되는 변경이므로 API 버전 v2.0 까지는 필드가 제거되지 않습니다. 데이터 모델의 버전 v1.0 에는 필드가 계속 포함됩니다 UserType .

관련된 문서

• 분석용 데이터 모델
• OData 버전 4.0 5부: 버전 관리