Azure DevOps에서 분석에 대한 OData 쿼리 생성

아티클
03/20/2024

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

Azure DevOps의 보고 플랫폼인 Analytics는 프로젝트의 과거 또는 현재 상태에 대한 정량적 질문에 답변할 수 있습니다. Analytics는 메타데이터 및 엔터티 집합 데이터의 OData 쿼리를 지원합니다. 웹 브라우저에서 간단한 쿼리를 실행하면 데이터 모델 및 쿼리 프로세스에 익숙해 질 수 있습니다.

이 문서에서는 다음을 알아봅니다.

클라우드 또는 온-프레미스에 대한 Analytics OData 쿼리를 생성하는 방법
분석 메타데이터를 쿼리하는 방법
엔터티 집합에 대한 Analytics OData를 쿼리하는 방법
지원되는 쿼리 옵션 및 권장되는 시퀀스
서버 쪽 페이징이 적용되는 경우

지원되는 웹 브라우저에서 분석을 쿼리할 수 있습니다. 분석을 쿼리하는 데 사용할 수 있는 다른 도구는 분석 쿼리 도구를 참조 하세요.

참고 항목

RESTful(REST=Representational State Transfer) 인터페이스를 통해 데이터와 상호 작용하기 위한 애플리케이션 수준 프로토콜인 OData는 데이터 모델에 대한 설명과 해당 모델에 따른 데이터 편집 및 쿼리를 지원합니다. EDM(엔터티 데이터 모델) 또는 메타데이터는 보고서를 작성하기 위해 데이터를 쿼리하는 데 사용하는 엔터티, 엔터티 형식, 속성, 관계 및 열거형을 포함하여 Analytics에서 사용할 수 있는 정보를 설명합니다. OData에 대한 개요는 OData 시작 항목을 참조하세요.

필수 조건

액세스: 최소한 기본 액세스 권한이 있는 프로젝트의 멤버여야 합니다.
사용 권한: 기본적으로 프로젝트 멤버는 분석을 쿼리하고 뷰를 만들 수 있는 권한이 있습니다.
서비스 및 기능 사용 및 일반 데이터 추적 활동과 관련된 기타 필수 구성 요소에 대한 자세한 내용은 Analytics에 액세스하기 위한 사용 권한 및 필수 구성 요소를 참조 하세요.

메타데이터를 쿼리하는 URL 구성 요소

분석은 서비스 루트 URL에 추가하여 $metadata 형성된 메타데이터 URL에 엔터티 모델을 노출합니다. Analytics는 Azure DevOps에서 프로젝트 또는 전체 조직에 대한 서비스 루트를 제공합니다.

메타데이터를 쿼리하여 다음 데이터 요소를 조회할 수 있습니다.

엔터티 형식 및 엔터티 집합
속성 및 탐색 속성
서로게이트 키
열거형 목록
EntitySet
컨테이너
필터 함수(Org.OData.Capabilities.V1.FilterFunctions)
지원되는 집계(Org.OData.Aggregation.V1.ApplySupported)
Batch 지원(Org.OData.Capabilities.V1.BatchSupportType)

사용하는 URL은 Azure DevOps Services(클라우드) 또는 온-프레미스 Azure DevOps Server에 대한 데이터를 쿼리하는지 여부에 따라 달라집니다.

클라우드 (Azure DevOps Services
온-프레미스 (Azure DevOps Server)

클라우드에서 호스트되는 조직 또는 프로젝트에 대한 메타데이터를 쿼리하려면 웹 브라우저에서 아래와 같이 URL 구문을 입력합니다. {ProjectName} 조직 이름과 쿼리할 프로젝트의 이름으로 바꿉 {OrganizationName} 습니다. 조직에 대한 모든 메타데이터를 반환하려면 프로젝트 이름을 지정하지 마세요.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

참고 항목

최신 Analytics OData 버전은 v4.0-preview입니다. 호스트된 서비스에 대한 모든 쿼리에 이 버전을 사용할 수 있습니다. 분석 버전 및 사용 가능한 데이터에 대한 자세한 내용은 분석용 데이터 모델을 참조 하세요.

다음은 Azure DevOps Services에서 호스트되는 fabrikam 조직의 예입니다.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

온-프레미스 서버에 대한 메타데이터를 쿼리하려면 웹 브라우저에서 아래와 같이 URL 구문을 입력합니다. 를 {CollectionName} {ProjectName} 온-프레미스 이름으로 대체{ServerName}합니다. 컬렉션에 대한 모든 메타데이터를 반환하려면 프로젝트 이름을 지정하지 마세요.

https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata 
\_________________________________________________/\______________/\________/
                            |                              |            | 
     On-premises server, collection, project         OData version  return metadata

참고 항목

Azure DevOps Server 2022에서 명명 fabrikam-devops 되고 DefaultCollection 호스트되는 서버에 대한 예는 다음과 같습니다.

https://fabrikam-devops/DefaultCollection/_odata/v4.0-preview/$metadata

메타데이터 응답 해석

Analytics는 데이터 모델의 XML 파일을 반환합니다. 브라우저 검색 함수를 사용하여 관심 있는 엔터티와 관련된 정보를 찾습니다.

팁

사용 중인 브라우저에 따라 이 파일의 서식은 읽을 수 있는 방식으로 포맷될 수도 있고 그렇지 않을 수도 있습니다. 서식이 지정되지 않은 경우 웹 브라우저 검색을 통해 무료 온라인 XML 포맷터를 찾을 수 있습니다.

분석 메타데이터에 정의된 두 가지 주요 스키마는 Microsoft.VisualStudio.Services.Analytics.Model엔터티 형식과 열거 형식 및 해당 멤버를 정의하는 스키마와 Default 엔터티 컨테이너 및 엔터티 집합 및 지원되는 OData 필터, 변환 및 사용자 지정 집계 함수를 정의하는 스키마입니다. 자세한 내용은 Analytics OData 메타데이터를 참조하세요.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

모든 엔터티 형식은 속성 및 탐색 속성과 연결됩니다. 이러한 유형의 속성을 모두 사용하여 엔터티 집합의 쿼리를 필터링할 수 있습니다. 이러한 항목은 as a Property 또는 NavigationalProperty. 아래의 메타데이터에 EntityType 나열됩니다. 관련 엔터티를 사용하여 반복 경로, 영역 경로 또는 Teams와 같은 추가 필터를 지정합니다.

다음 코드 조각은 엔터티에 대한 WorkItem 메타데이터의 부분 보기를 제공합니다. 속성은 작업 항목 필드뿐만 아니라 분석에서 캡처한 특정 데이터(예: LeadTimeDays 및 CycleTimeDays)에 해당합니다. 탐색 속성은 다른 엔터티 집합 또는 엔터티 형식(예: Revisions, LinksChildren및Parent)에 대해 캡처된 특정 분석 데이터에 해당합니다.

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

엔터티를 쿼리하는 URL 구성 요소

분석 데이터를 쿼리하고 보고서를 작성하려면 일반적으로 엔터티 집합을 쿼리합니다. 지원되는 엔터티에 대한 개요는 Analytics OData 메타데이터를 참조하세요.

다음 URL은 특정 EntitySet(예: WorkItems, WorkItemSnapshot및 PipelineRuns)을 쿼리하는 데 사용됩니다.

클라우드 (Azure DevOps Services
온-프레미스 (Azure DevOps Server)

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

다음은 Fabrikam 파이버 프로젝트에 대해 정의된 작업 항목 수를 반환하는 fabrikam 조직의 예입니다.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

이 예제에서는 1399개 작업 항목을 반환합니다.

{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
   "@odata.id": null,
   "Count": 1399
   }
 ]
}

Fabrikam 프로젝트에 대해 정의된 작업 항목 수를 반환하는 fabrikam 서버 DefaultCollection의 예는 다음과 같습니다.

https://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

이 예제에서는 1399개 작업 항목을 반환합니다.

{
"@odata.context": "http://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
      "@odata.id": null,
      "Count": 44
   }
 ]
}

참고 항목

또는 $apply 절을 $select 포함하지 않으면 엔터티 집합에서 select 문을 수행하고 모든 열과 모든 행을 반환하는 것과 같은 경고 "VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060." 가 표시됩니다. 레코드 수가 많은 경우 몇 초 정도 걸릴 수 있습니다. 작업 항목이 10,000개 이상인 경우 서버 기반 페이징이 적용됩니다.

사용량 제한으로 실행하지 않도록 하려면 항상 또는 $apply 절을 $select 포함합니다.

엔터티 메타데이터 속성 및 관계 정보는 다음 문서를 참조하세요.

예: 특정 엔터티 집합 쿼리

와 같은 WorkItemsAreas특정 엔터티 집합을 쿼리하거나 Projects엔터티 집합/WorkItems/Areas의 이름을 추가하려면 , 또는 /Projects. 엔터티 집합의 전체 목록은 분석용 데이터 모델을 참조 하세요.

클라우드 (Azure DevOps Services
온-프레미스 (Azure DevOps Server)

예를 들어 속성을 쿼리 /Projects 하고 선택하여 ProjectName 조직에 대해 정의된 프로젝트 목록을 가져올 수 있습니다. fabrikam 조직의 경우 URL은 아래와 같습니다.

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analytics는 fabrikam 조직에 대해 정의된 프로젝트의 프로젝트 이름을 반환합니다.

{
@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

다음은 fabrikam 서버의 DefaultCollection에 정의된 모든 프로젝트의 이름을 반환하도록 엔터티 집합을 쿼리 Projects 하는 예제입니다.

https://fabrikam/DefaultCollection/_odata/v4.0-preview/Projects?$select=ProjectName

이 예제에서는 세 개의 프로젝트 이름을 반환합니다.

{
"@odata.context": "http://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
"value": [
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Florida"
   }
 ]
}

쿼리 옵션

쿼리 옵션은 URL의 리소스에 대해 반환되는 데이터의 양을 제어하는 데 도움이 되는 리소스에 적용되는 쿼리 문자열 매개 변수 집합입니다.

쿼리 옵션은 다음 표에 나열된 순서대로 지정해야 합니다.

쿼리 옵션	주의
`$apply`	쿼리에 적용할 수 있는 변환 집합(예: `filter`, , `groupbyaggregate`, ) `expand,` `compute` `concat` 예를 들어 분석을 사용하여 집계 작업 추적 데이터를 참조 하세요.
`$compute`	또는`$filter$orderby` 식에서 사용할 수 있는 계산 속성을 정의하기 위해 지정할 수 있는 `$select`지원되는 OData 함수입니다.
`$filter`	반환되는 리소스 목록을 필터링하는 데 사용합니다. 지정된 `$filter` 식은 컬렉션의 각 리소스에 대해 평가되며 식이 true로 평가되는 항목만 응답에 포함됩니다. 식이 false 또는 null로 평가되거나 권한으로 인해 사용할 수 없는 참조 속성이 응답에서 생략되는 리소스입니다. 예를 들어 분석을 사용하여 작업 추적 데이터 쿼리를 참조 하세요 .
`$orderby`	레코드를 반환할 시퀀스를 지정하는 데 사용합니다. 예를 들어 분석을 사용하여 작업 추적 데이터 쿼리를 참조 하세요.
`$top`/`$skip`	반환되는 레코드 수를 제한하는 데 사용합니다. 예제는 Project 및 조직 범위 쿼리를 참조 하세요.
`$select`/`$expand`	보고서를 작성하는 데 필요한 열을 지정하는 데 사용합니다 `$select` . 다른 쿼리 옵션을 중첩하는 데 사용합니다 `$expand` . 각각 `expandItem` 은 확장 중인 탐색 또는 스트림 속성을 포함하는 엔터티를 기준으로 평가됩니다. 탐색 속성 이름에 괄호로 묶인 쿼리 옵션의 세미콜론으로 구분된 목록입니다. 허용되는 시스템 쿼리 옵션은 `$filter`, `$select`,`$orderby`, `$skip`, `$search$top$count`및 .`$expand` 예를 들어 분석을 사용하여 작업 추적 데이터 쿼리를 참조 하세요.
`$skiptoken`	지정된 수의 레코드를 건너뛰는 데 사용합니다.
`$count` 또는 `$count=true`	레코드 수만 반환하려면 입력 `$count` 합니다. 레코드 수와 쿼리된 데이터를 모두 반환하려면 입력 `$count=true`합니다. 예를 들어 분석을 사용하여 집계 작업 추적 데이터를 참조 하세요.

팁

단일 쿼리에서 혼합 $apply 및 $filter 절을 사용하지 않습니다. 쿼리를 필터링하려면 두 가지 옵션이 있습니다. (1) 절을 $filter 사용하거나 (2) 조합 절을 $apply=filter() 사용합니다. 이러한 각 옵션은 자체적으로 잘 작동하지만 함께 결합하면 예기치 않은 결과가 발생할 수 있습니다.

서버 쪽 페이징 적용

분석에서는 쿼리 결과가 10000개 레코드를 초과할 때 페이징을 강제합니다. 이 경우 데이터의 첫 번째 페이지와 다음 페이지를 가져오기 위해 따라야 할 링크가 표시됩니다. 링크(@odata.nextLink)는 JSON 출력의 끝에서 찾을 수 있습니다. 원래 쿼리 뒤에 오거나 $skiptoken.$skip와 같이 표시됩니다. 예시:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

참고 항목

Power BI Desktop 또는 Excel과 같은 클라이언트 도구로 데이터를 끌어올 때 도구는 자동으로 다음 링크를 따라 필요한 모든 레코드를 로드합니다.

다음 단계

OData Analytics를 사용하여 기본 쿼리 생성

다음을 통해 공유

Azure DevOps에서 분석에 대한 OData 쿼리 생성

필수 조건

메타데이터를 쿼리하는 URL 구성 요소

메타데이터 응답 해석

엔터티를 쿼리하는 URL 구성 요소

예: 특정 엔터티 집합 쿼리

쿼리 옵션

서버 쪽 페이징 적용

다음 단계

피드백

추가 리소스

다음을 통해 공유

Azure DevOps에서 분석에 대한 OData 쿼리 생성

필수 조건

메타데이터를 쿼리하는 URL 구성 요소

메타데이터 응답 해석

관련 엔터티 및 탐색 속성

엔터티를 쿼리하는 URL 구성 요소

예: 특정 엔터티 집합 쿼리

쿼리 옵션

서버 쪽 페이징 적용

다음 단계

관련된 문서

피드백

추가 리소스