使用 OData Analytics 定義基本查詢

文章
01/10/2024

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

使用 Azure DevOps 的分析，您可以建構基本和篩選的查詢，以傳回感興趣的數據。您可以直接在瀏覽器或 Power BI 中執行這些查詢。

本文會建置 Azure Boards 分析的建構 OData 查詢和元數據參考中提供的資訊。此外，本文中的查詢著重於擷取工作追蹤實體集，不過，原則適用於查詢其他實體集。

在本文中，您將瞭解如何定義傳回下列數據的查詢：

項目計數（沒有其他資料）
項目和數據計數
針對區域或反覆項目路徑定義的屬性
選取的數據行或欄位
篩選的數據
傳回 [識別]、[區域路徑] 和 [反復項目路徑] 欄位的數據
依導覽屬性篩選
查詢日期範圍
巢狀展開語句
排序結果，orderby 選項

注意

所有 Azure DevOps Services 的生產環境中都會自動啟用及支援 Analytics 服務。 Power BI 整合及存取 Analytics Service 的 OData 摘要已正式推出。我們鼓勵您使用它，並提供意見反應給我們。可用的數據與版本相關。最新支援的版本是 v2.0，而最新的預覽版本是 v4.0-preview。如需詳細資訊，請參閱 OData API 版本控制。

注意

Azure DevOps Server 2020 和更新版本的所有新專案集合都會在生產環境中自動安裝並支援 Analytics 服務。 Power BI 整合及存取 Analytics Service 的 OData 摘要已正式推出。我們鼓勵您使用它，並提供意見反應給我們。如果您從 Azure DevOps Server 2019 升級，則可以在升級期間安裝 Analytics 服務。

可用的數據與版本相關。最新支援的版本是 v2.0，而最新的預覽版本是 v4.0-preview。如需詳細資訊，請參閱 OData API 版本控制。

注意

Azure DevOps Server 2019 的 Analytics 服務處於預覽狀態。您可以啟用或安裝專案集合。 Power BI 整合和分析服務的 OData 摘要存取處於預覽狀態。我們鼓勵您使用它，並提供意見反應給我們。

可用的數據與版本相關。最新支援的版本是 v2.0，而最新的預覽版本是 v4.0-preview。如需詳細資訊，請參閱 OData API 版本控制。

必要條件

存取：至少是具有基本存取權的項目成員。
許可權： 根據預設，項目成員具有查詢分析及建立檢視的許可權。
如需有關服務與功能啟用和一般數據追蹤活動之其他必要條件的詳細資訊，請參閱存取分析的許可權和必要條件。

注意

在本文中，已針對 Azure DevOps Services 定義 OData 查詢 URL。若要為內部部署伺服器建構類似的查詢，請參閱建構適用於分析的 OData 查詢中提供的指引。我們鼓勵您調整為組織和專案提供的查詢，以熟悉使用瀏覽器查詢 OData。

傳回項目計數（沒有其他資料）

若要瞭解組織或項目中定義的項目或實體數目，請指定 $apply=aggregate($count as Count) 查詢選項。例如，下列查詢會傳回為組織定義的專案、工作專案、區域路徑和用戶數目。

https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)

提示

執行查詢的用戶無法存取所有專案時，跨專案查詢會失敗。深入瞭解 Project 和組織範圍查詢中的需求。

項目計數

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value	
   0	
     @odata.id	null
     Count	    28

工作項目計數

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value	
  0	
     @odata.id	null
     Count	    1166

區域計數

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    70

用戶計數

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    16

傳回項目和數據計數

若要傳回項目計數以及項目的選取數據，請指定 $count=true 查詢選項。例如，下列查詢會傳回為項目定義的工作專案、區域路徑和用戶計數，以及指定的屬性。如需有效的屬性，請參閱 Azure Boards 分析與行事曆日期、專案和 Azure DevOps Analytics 的使用者元數據參考。

提示

如果您未指定要傳回的屬性，Analytics 會傳回針對指定實體類型定義的所有屬性。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail

區域或反覆項目屬性

若要查閱AreaSK區域路徑或反覆項目路徑的 或 IterationSK或其他屬性，請使用下列查詢。

傳回特定區域路徑的 AreaSK

下列查詢會指定傳回AreaSK針對 Fabrikam Fiber\Service Delivery\Internet Area Path 所定義的屬性。若要指定為 Areas 實體集定義的其他屬性，請參閱 Azure Boards Analytics、Areas 的元數據參考。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK

查詢會傳回下列數據。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
    }
  ]
}

傳回特定反覆項目路徑的反覆運算SK

下列查詢會指定傳回 IterationSK 針對 Fabrikam Fiber\Release 1\Sprint 3 反覆項目路徑所定義的屬性。若要指定為 Iterations 實體集定義的其他屬性，請參閱 Azure Boards Analytics 的元數據參考、反覆專案。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK

查詢會傳回下列數據。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
  "value": [
    {
      "IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
    }
  ]
}

傳回特定屬性或欄位

若要傳回特定屬性或工作專案欄位，請新增 $select 指定屬性名稱的子句。

例如，若要傳回 工作專案標識碼、 工作專案類型、標題和 工作項目狀態 ，請將下列子句新增至查詢。這個子句會指定對應至具名字段的屬性。

注意

屬性名稱不包含任何空格。如果您新增空格，您的查詢將會失敗。 OData 查詢需要注意間距和大小寫。若要瞭解自定義欄位屬性的標籤方式，請參閱 Azure Boards 的元資料參考、自定義屬性。

在此，我們指定傳回前三個工作專案。

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

分析會傳回下列數據。

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
   0	
      WorkItemId    462
      Title         "Test case"
      WorkItemType  "Test Case"
      State         "Design"
   1	
      WorkItemId	   491
      Title          "Change color settings"
      WorkItemType   "Shared Steps"
      State          "Active"
   2	
      WorkItemId	   461
      Title          "Test impediment"
      WorkItemType   "Impediment"
      State          "Open"

篩選您的資料

若要篩選實體集以傳回選取專案，請指定 $filter 指定項目必須符合之準則的子句。在最後一個查詢的基礎上，我們在這裡新增篩選子句，只傳回處於 [進行中] 狀態的功能工作項目類型。

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'&$select=WorkItemId,Title,AssignedTo,State

分析會傳回下列數據。

  
@odata.context	"https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value	
  0	
      WorkItemId	380
      Title	"Refresh web look, feel, performance factors"
      State	"In Progress"
  1	
      WorkItemId	480
      Title	"Customer Phone - Phase 1"
      State	"In Progress"
  2	
      WorkItemId	493
      Title	"Change initial view"
      State	"In Progress"
  3	
      WorkItemId	479
      Title	"Customer Web - Phase 1"
      State	"In Progress"
  4	
      WorkItemId	551
      Title	"Mobile feedback"
      State	"In Progress"

指定數個篩選子句

您可以使用 AND 和 OR 指定數個篩選子句。

例如，下列查詢會指定傳回屬於 [新增]、[認可] 或 [作用中] 狀態之使用者劇本、Bug 和待辦專案類型的工作專案（自定義工作專案類型）。視需要使用括號將篩選子句分組。

此外，您可以套用各種函式，例如contains、 startswithendswith 等等。請參閱支援的 OData 功能和子句、支援的函式。

傳回 [識別]、[區域路徑] 和 [反復項目路徑] 欄位的數據

Select 屬性與導覽屬性相關聯，而且無法使用語句直接存取 $select 。您必須使用 $expand 語句傳回感興趣的數據。這些屬性通常與自己的數個屬性相關聯。例如，使用 [身分識別] 字段，您可以指定以傳回使用者名稱或使用者電子郵件。

下表提供如何展開其中數個屬性的範例。

類型欄位	參考屬性	要包含的范例子句
Datetime	`DateSK`	`$expand=CreatedDate($select=Date)` 或 `$expand=CreatedDate($select=WeekStartingDate)`
身分識別	`UserSK`	`$expand=AssignedTo($select=UserName)` 或 `$expand=AssignedTo($select=UserEmail)`
區域	`AreaSK`	`$expand=Area($select=AreaName)` 或 `$expand=Area($select=AreaPath)`
反覆運算	`IterationSK`	`$expand=Iteration($select=IterationName)` 或 `$expand=Iteration($select=IterationPath)` 或 `$expand=Iteration($select=StartDate)`
專案	`ProjectSK`	`$expand=Project($select=ProjectName)`
球隊	`TeamSK`	`$expand=Teams($select=TeamName)`

若要指定需要展開的數個屬性，您可以在 comman 分隔清單內的單一 expand 子句中指定它們。

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

當您將導覽屬性指定為篩選準則的一部分時，您必須以所需的格式加以指定。

例如，下列子句會指定根據 針對專案定義的反覆專案 1 篩選工作專案。

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

在此範例中， Iteration 是導覽屬性名稱，並 IterationPath 對應至反覆運算的完整路徑。若要使用另一個實體做為篩選，請將導覽屬性放在後面接著斜線，後面接著要篩選的功能變數名稱。

而且，以下是完整的 OData 查詢：

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

以下是另一個範例，會傳回 Fabrikam Fiber\Service Delivery\Voice Area Path 下的前五個工作專案。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
  0	
     WorkItemId	361
     Title        "Hello World Web Site"
     WorkItemType	"Product Backlog Item"
     State        "Removed"
  1	
     WorkItemId	362
     Title        "Resume"
     WorkItemType	"Product Backlog Item"
     State        "New"
  2	
     WorkItemId	363
     Title        "Welcome back page"
     WorkItemType	"Product Backlog Item"
     State        "Done"
  3	
     WorkItemId	365
     Title        "Pause"
     WorkItemType	"Feature"
     State        "New"
  4	
     WorkItemId	374
     Title        "Fix performance issues"
     WorkItemType	"Task"
     State        "To Do"

提示

您無法直接在語句中使用 $select 導覽屬性。相反地，您必須使用 $expand。

先前反覆路徑的篩選範例不會傳回反覆專案路徑，因為它包含在相關實體中。若要傳回相關實體中的數據，請新增 $expand 語句：

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration

以下是傳回指派給工作項目標識碼 480 之資訊的範例。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
   
@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value	
  0	
      WorkItemId           480
      Title                "Customer Phone - Phase 1"
      WorkItemType	       "Feature"
      State	               "In Progress"
      Iteration	
          ProjectSK	       "56af920d-393b-4236-9a07-24439ccaa85c"
          IterationSK	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationId	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationName	   "Sprint 1"
          Number	            55297
          IterationPath	    "Fabrikam Fiber\\Release 1\\Sprint 1"
          StartDate	        "2022-01-17T00:00:00-08:00"
          EndDate	            "2022-02-04T23:59:59.999-08:00"
          IterationLevel1	    "Fabrikam Fiber"
          IterationLevel2	    "Release 1"
          IterationLevel3	    "Sprint 1"
          IterationLevel4	    null
          IterationLevel5	    null
          IterationLevel6	    null
          IterationLevel7	    null
          IterationLevel8	    null
          IterationLevel9	    null
          IterationLevel10	null
          IterationLevel11	null
          IterationLevel12	null
          IterationLevel13	null
          IterationLevel14	null
          Depth	            2
          IsEnded	        	true
      AnalyticsUpdatedDate	"2022-01-18T22:18:58.17Z"

如您所見，反覆項目路徑會在結果中展開，並傳回所有反覆項目數據。數據可能比您想要的數據多。

若要傳回較少的數據，請針對反覆專案新增 $select 語句：

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)

然後，它會傳回下列數據。

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "Name":"Sprint 55",
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55"
      }
    }
  ]
}

查詢日期範圍

下列範例會傳回變更日期大於 2021 年 1 月 1 日的工作專案。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z

下列範例會傳回在 2021 年 4 月 26 日至 4 月 30 日當周發生的變更日期的工作專案。

https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z

巢狀展開語句

在 OData 中，您可以巢狀 $expand 語句。例如，您可以撰寫上一個查詢語句來顯示反覆專案所屬的專案：

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)

它會傳回下列 JSON：

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
      "WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":" Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false,
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

您也可以合併 $expand 和 $select 語句。例如，您可以將上一個查詢變更為只傳回反覆專案名稱和反覆項目路徑：

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)

它會傳回下列 JSON：

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

請注意，此處的結果只會顯示 IterationId 和 IterationPath，而且 Project 是 JSON 結果中的巢狀物件。要注意的另一個重要專案是URL本身。使用 $select 語句和 $expand 子句時，您必須在之前 $expand使用分號（;) 。任何其他專案都會導致錯誤。

排序結果， `orderby` 選項

指定排序 $orderby 結果的選項，或指定傳回結果的順序。您可以使用關鍵詞 asc 或 desc，分別以遞增或遞減順序排序。顯示一些範例

排序方式	要包含的子句
工作項目識別碼	`/WorkItems?$orderby=WorkItemId`
工作專案標識碼遞減	`/WorkItems?$orderby=WorkItemId desc`
工作專案類型和狀態	`/WorkItems?$orderby=WorkItemType,State`

下一步

專案與組織範圍的查詢

分享方式：

使用 OData Analytics 定義基本查詢

必要條件

傳回項目計數（沒有其他資料）

項目計數

工作項目計數

區域計數

用戶計數

傳回項目和數據計數

區域或反覆項目屬性

傳回特定區域路徑的 AreaSK

傳回特定反覆項目路徑的反覆運算SK

傳回特定屬性或欄位

篩選您的資料

指定數個篩選子句

傳回 [識別]、[區域路徑] 和 [反復項目路徑] 欄位的數據

依導覽屬性篩選

查詢日期範圍

巢狀展開語句

排序結果， `orderby` 選項

下一步

意見反映

更多資源

分享方式：

使用 OData Analytics 定義基本查詢

必要條件

傳回項目計數（沒有其他資料）

項目計數

工作項目計數

區域計數

用戶計數

傳回項目和數據計數

區域或反覆項目屬性

傳回特定區域路徑的 AreaSK

傳回特定反覆項目路徑的反覆運算SK

傳回特定屬性或欄位

篩選您的資料

指定數個篩選子句

傳回 [識別]、[區域路徑] 和 [反復項目路徑] 欄位的數據

依導覽屬性篩選

查詢日期範圍

巢狀展開語句

排序結果， orderby 選項

下一步

相關文章

意見反映

更多資源

排序結果， `orderby` 選項