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

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

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

이 문서에서는 다음 방법을 설명합니다.

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

필수 조건

메타데이터 쿼리

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

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

• 엔터티 형식 및 엔터티 집합
• 속성 및 탐색 속성
• 서로게이트 키
• 나열된 목록
• 엔터티 집합
• 컨테이너
• 필터 함수, Org.OData.Capabilities.V1.FilterFunctions 사용
• 지원되는 집계, Org.OData.Aggregation.V1.ApplySupported와 함께
• Batch 지원 유형, Org.OData.Capabilities.V1.BatchSupportType와 함께

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/$metadata 

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

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/$metadata 

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

메타데이터 응답 해석

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

분석 메타데이터는 다음 기본 스키마를 정의합니다.

• Microsoft.VisualStudio.Services.Analytics.Model 는 엔터티 형식과 열거형 형식 및 해당 멤버를 정의합니다.
• 스키마는 Default 엔터티 컨테이너 및 엔터티 집합 및 지원되는 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>

자세한 내용은 Analytics OData 메타데이터를 참조하세요.

관련 엔터티 및 탐색 속성 가져오기

모든 엔터티 형식에는 쿼리를 필터링하는 데 사용할 수 있는 속성과 탐색 속성이 있습니다. 이러한 속성은 메타데이터에 각각 Property또는 NavigationPropertyEntityType 아래에 나열됩니다. 관련 엔터티를 사용하여 반복 경로, 영역 경로 또는 팀과 같은 더 많은 필터를 지정할 수 있습니다.

다음 코드 조각은 엔터티에 대한 WorkItem 메타데이터의 부분 보기를 보여줍니다. 속성은 작업 항목 필드 및 분석에서 캡처한 특정 데이터(예: LeadTimeDays 및 CycleTimeDays)에 해당합니다. 탐색 속성은 엔터티 형식에 대해 캡처된, 예를 들어 Revisions나 Links, Children, 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"/>
...

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

• 일정 날짜, 프로젝트 및 사용자 메타데이터 참조
• Azure Boards에 대한 메타데이터 참조
• Azure Pipelines에 대한 메타데이터 참조
• 테스트 계획에 대한 메타데이터 참조

엔터티 집합 조회

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

다음 URL 구문을 사용하여 특정 EntitySet(예: WorkItems, WorkItemSnapshot또는 PipelineRuns)을 쿼리합니다. <EntitySet>를 검색하려는 엔터티로 대체하고, <QueryOptions>를 쿼리 옵션으로 대체하십시오.

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

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

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

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

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

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

예: 특정 엔터티 집합 쿼리

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

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

{
@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"
   }
 ]
}

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"
   }
 ]
}

쿼리 옵션 사용

쿼리 옵션은 리소스에 대해 반환되는 데이터의 양을 제어하는 데 도움이 되는 쿼리 문자열 매개 변수입니다. 다음 표에 나열된 순서대로 쿼리 옵션을 지정합니다.

서버 측 페이징 이해하기

분석에서는 쿼리 결과가 10,000개의 레코드를 초과할 때 페이징을 강제합니다. 이 경우 데이터의 첫 번째 페이지와 다음 페이지를 가져오기 위해 따라야 할 링크가 표시됩니다. Power BI Desktop 또는 Excel과 같은 클라이언트 도구는 데이터를 끌어오면 필요한 모든 레코드를 @odata.nextLink 자동으로 따르고 로드합니다.

JSON 출력의 끝에서 @odata.nextLink 링크를 찾을 수 있습니다. 링크는 원래 쿼리 뒤에 $skip 또는 $skiptoken이 오는 것으로 보입니다. 예시:

{
  "@odata.context":"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/WorkItems?$skiptoken=10000"
}

다음 단계

관련 콘텐츠

• 분석이란?
• OData Analytics 쿼리 지침
• Azure DevOps에서 분석에 액세스하기 위한 권한 및 필수 구성 요소