OData API 버전 관리

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

Analytics 서비스가 성숙함에 따라 사용자에게 일관성과 안정성을 제공하기 위해 최선을 다하고 있습니다. 따라서 Azure DevOps용 Analytics는 해당 버전을 위해 설계된 클라이언트와 호환되는 버전이 지정된 OData API를 제공합니다. 각 버전은 더 많은 기능과 호환성이 손상되지 않는 변경으로 향상될 수 있습니다. 호환되지 않거나 호환되지 않는 변경 내용은 이후 버전의 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 대해 프로덕션에서 자동으로 사용하도록 설정되고 지원됩니다. Power BI 통합 및 Analytics Service의 OData 피드 에 대한 액세스는 일반적으로 사용할 수 있습니다. 이를 사용하고 피드백을 제공하는 것이 좋습니다. 사용 가능한 데이터는 버전에 따라 다릅니다. 지원되는 최신 버전은 이며 v2.0최신 미리 보기 버전은 입니다 v4.0-preview. 자세한 내용은 OData API 버전 관리를 참조하세요.

미리 보기 버전

• v3.0-미리 보기
• v4.0-preview

릴리스된 버전

• v1.0
• v2.0

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

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

버전 수명 주기

OData API의 각 버전은 수명 주기 동안 세 단계를 거닐게 됩니다.

미리 보기

모든 호환성이 손상되는 변경 내용은 결합되어 향후 버전의 API에서 함께 릴리스됩니다. 이 기능을 가능한 한 빨리 사용할 수 있도록 미리 보기 모드에서 새 버전을 릴리스합니다. 버전이 미리 보기 모드인 동안에는 호환성이 손상되는 변경이 여전히 가능합니다. 또한 미리 보기 버전에 포함된 항목이 릴리스된 버전에 포함된다는 보장은 없습니다.

버전의 미리 보기는 릴리스된 후 최소 6주 동안 사용할 수 있습니다.

Released

미리 보기 버전이 릴리스에 충분히 완성되면 -preview 접미사 없이 사용할 수 있게 됩니다. 릴리스된 버전에는 호환성이 손상되는 변경이 도입되지 않지만 데이터 모델은 추가 기능으로 계속 증가할 수 있습니다. 릴리스된 버전은 최소 12개월 동안 지원됩니다.

사용되지 않음

사용되지 않는 버전은 더 이상 지원되지 않습니다. 사용되지 않는 버전에 대한 요청은 처리되지 않습니다. 더 이상 사용되지 않거나 지원되지 않는 버전을 요청하려고 하면 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>

호환성이 손상되는 변경의 예

이제 사용자 엔터티의 원래 구조로 되돌리기 이전에 사용 가능한 기능이 제거되는 시나리오를 고려합니다.

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

관련 문서

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