使用 OData Analytics 定義基本查詢

發行項
03/27/2025

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

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

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

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

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

注意

所有 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 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)

提示

執行查詢的用戶無法存取所有專案時，跨專案查詢會失敗。如需進一步了解專案與組織範圍查詢中的需求。

項目計數

@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區域路徑 所定義的。若要指定為 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"
    }
  ]
}

傳回特定迭代路徑的 IterationSK

下列查詢指定傳回為 Fabrikam Fiber\Release 1\Sprint 3疊代路徑 定義的 IterationSK 屬性。若要指定為 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 語法直接存取。您必須使用 $expand 語句傳回感興趣的數據。這些屬性通常與其他屬性相關聯。例如，使用 [身分識別] 字段，您可以指定以傳回使用者名稱或使用者電子郵件。

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

類型欄位	參考屬性	要包含的範例條款
日期時間	`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)`

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

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

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

例如，下列子句會指定根據專案中定義的Iteration 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 區域路徑下的前五個工作項目。

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`
工作專案ID遞減	`/WorkItems?$orderby=WorkItemId desc`
工作專案類型和狀態	`/WorkItems?$orderby=WorkItemType,State`

下一步

專案與組織範圍的查詢

共用方式為

使用 OData Analytics 定義基本查詢

必要條件

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

項目計數

工作項目數量

區域計數

用戶計數

返回項目和資料計數

區域或迭代屬性

傳回特定區域路徑的 AreaSK

傳回特定迭代路徑的 IterationSK

傳回特定屬性或欄位

篩選您的資料

指定數個篩選子句

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

依導覽屬性篩選

查詢日期範圍

巢狀展開語句

排序結果， `orderby` 選項

下一步

意見反應

其他資源

共用方式為

使用 OData Analytics 定義基本查詢

必要條件

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

項目計數

工作項目數量

區域計數

用戶計數

返回項目和資料計數

區域或迭代屬性

傳回特定區域路徑的 AreaSK

傳回特定迭代路徑的 IterationSK

傳回特定屬性或欄位

篩選您的資料

指定數個篩選子句

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

依導覽屬性篩選

查詢日期範圍

巢狀展開語句

排序結果， orderby 選項

下一步

相關文章

意見反應

其他資源

排序結果， `orderby` 選項