使用 OData Analytics 定義基本查詢

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

您可以使用適用於 Azure DevOps 的 Analytics 來建構 OData 查詢，以傳回您感興趣的資料。您可以在瀏覽器或用戶端軟體（例如 Excel 或 Power BI）中執行這些查詢。

本文著重於擷取 Azure Boards 工作追蹤實體集的查詢，但原則適用於查詢其他實體集。如需詳細資訊，請參閱建構 OData 查詢以進行分析和Azure Boards Analytics 的中繼資料參考。

本教學課程會示範如何：

定義查詢可傳回項目計數，無論是否包含其數據。
選取以傳回特定屬性的資料。
依特定屬性篩選資料。
傳回導覽屬性的資料，例如 身分識別、 區域路徑和 反覆專案路徑。
使用 expand 子句和巢狀 expand 陳述式。
查詢日期範圍。
使用選項 orderby 來排序結果。

注意

Azure DevOps Services 內所有服務的生產環境中會自動啟用及支援 Analytics 服務。 Power BI 整合及存取 Analytics 服務的 OData 摘要已正式推出。建議您使用 Analytics OData 摘要並提供意見反應。

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

注意

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

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

必要條件

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

注意

當執行查詢的使用者無法存取所有專案時，跨專案查詢會失敗。如需需求的詳細資訊，請參閱專案和組織範圍的查詢。

注意

本文中的 OData 查詢會使用針對 Azure DevOps Services 定義的查詢 URL。 https://analytics.dev.azure.com/ 在查詢中替換您自己的組織和專案名稱，以便熟悉查詢 OData。

針對內部部署伺服器，您可以根據伺服器和專案集合來使用 URL https://<servername>/<ProjectCollectionName>/ 建構類似的查詢。如需詳細資訊，請參閱建構 Analytics 的 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)

上述查詢會傳回結果，例如下列組織中 fabrikam 專案的範例：

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

取得項目及其資料的數量計算

若要傳回項目計數以及項目的選取資料，請在陳述式中$count=true指定select查詢選項。下列查詢會傳回針對專案定義的工作專案、區域路徑和使用者計數，以及指定的屬性。如需有效的屬性，請參閱 Azure Boards 分析的元數據參考與 Azure DevOps 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

注意

若要傳回針對指定實體類型定義的所有屬性，您可以使用 $count=true，而不使用 select 子句。不過，如果您未包含 $select or $apply 子句，您會收到警告，例如 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。若要避免遇到使用限制，請務必在查詢中包含 $select or $apply 子句。

例如，下列查詢會要求 Fabrikam Fiber 專案中使用者的計數和使用者名稱：

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

查詢會傳回使用者計 5 數及其 使用者名稱。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Users(UserName)",
  "@odata.count": 5,
  "value": [
    {
      "UserName": "Microsoft.VisualStudio.Services.TFS"
    },
    {
      "UserName": "fabrikamfiber1@hotmail.com"
    },
    {
      "UserName": "Jamal Hartnett"
    },
    {
      "UserName": "fabrikamfiber5@hotmail.com"
    },
    {
      "UserName": "fabrikamfiber2@hotmail.com"
    }
  ]
}

選取特定屬性或欄位

若要傳回特定屬性或工作專案欄位，請新增 $select 指定屬性名稱的子句。例如，若要傳回工作專案的 [工作專案識別碼]、[ 工作專案類型]、[ 標題] 和 [狀態 ]，請將子 $select=WorkItemId,WorkItemType,Title,State 句新增至查詢。

$select 子句指定對應於具名欄位的屬性名稱。 OData 查詢中屬性名稱的間距和大小寫都需要仔細注意。雖然 工作專案標識碼 等屬性顯示名稱可以包含空格，但正式屬性名稱不能包含空格。

如需屬性名稱和標籤的詳細資訊，請參閱 Azure Boards的中繼資料參考。若要瞭解自訂欄位屬性的標籤方式，請參閱自訂屬性。

下列範例查詢會要求 Fabrikam Fiber 專案中前三個工作項目的識別碼、標題和狀態。

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

分析會傳回下列數據。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)",
  "value": [
    {
      "WorkItemId": 31,
      "Title": "About screen",
      "WorkItemType": "Task",
      "State": "New"
    },
    {
      "WorkItemId": 30,
      "Title": "Change background color",
      "WorkItemType": "Task",
      "State": "Active"
    },
    {
      "WorkItemId": 32,
      "Title": "Standardize on form factors",
      "WorkItemType": "Task",
      "State": "Active"
    }
  ]
}

篩選資料

若要篩選實體集以傳回特定專案，請新增子 $filter 句來指定專案必須符合的準則。下列篩選子句只會傳回處於<分钟>[進行中]狀態的功能工作項目類型。

/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

** 下列範例查詢指定只傳回屬於功能工作專案且處於進行中狀態的工作專案的工作專案識別碼、工作專案類型、標題和狀態。

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

指定數個篩選子句

您可以使用 and and or 在單一 $select 子句中指定數個篩選器。例如，下列查詢會指定型別為使用者故事、Bug或自訂型別待辦工作的工作專案的數個欄位，這些工作專案處於新增、認可或作用中狀態。視需要使用括號將篩選子句分組。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

查詢會傳回類似下列結果的資料：


{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,AssignedTo,State)",
  "value": [
    {
      "WorkItemId": 210,
      "Title": "Slow response on form",
      "State": "Active"
    },
    ...
    {
      "WorkItemId": 160,
      "Title": "Game store testing",
      "State": "New"
    }
  ]
}

您也可以套用各種函數，例如 contains 、startswith 和 endswith 在 $select 子句中。請參閱支援的功能。

查詢區域路徑或迭代路徑屬性

若要查詢特定區域路徑、迭代路徑或其他屬性的AreaSK、IterationSK，請使用下列查詢。

傳回特定區域路徑的 AreaSK

下列查詢會要求列出 AreaSK 區域路徑中定義的 Fabrikam Fiber\Production Planning\Web 屬性。若要查看 Areas 實體集的其他定義屬性，請參閱區域。

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

查詢會傳回下列數據。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    }
  ]
}

傳回特定反覆專案路徑的 IterationSK

下列查詢會傳回針對 IterationSK 反覆執行路徑定義的 Fabrikam Fiber\3Week Sprints\Sprint 3 屬性。若要查看疊代實體集的其他定義屬性，請參閱疊代。

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

導覽屬性代表實體類型之間的關聯性。當您將導覽屬性指定為篩選準則的一部分時，您必須指定導覽屬性的完整路徑。例如，下列子句會根據導覽屬性的指定Iteration路徑來篩選工作專案。

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

Iteration 是導航屬性， IterationPath 是感興趣的欄位。 Iteration/IterationPath 是 IterationPath 屬性的完整路徑。

下列範例查詢會指定完整Fabrikam Fiber\3Week Sprints\Sprint 3路徑，以從迭代路徑下的Iteration/IterationPath前五個工作專案要求資料。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

上述範例查詢不會傳回 Iteration 資料，因為 Iteration 是相關實體。導覽屬性的屬性，例如 Identity、Area 和 Iteration，無法直接使用 $select 陳述式來存取。您必須使用 $expand 語句從相關的實體傳回資料。

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

下列範例查詢會要求與工作專案識別碼 480 相對應的資訊，包括詳細資料 Iteration。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

查詢會傳回下列資料，其中包括展開屬性 Iteration 中的所有欄位。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        "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": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z"
      }
    }
  ]
}

在展開陳述式中使用 select

如果展開的屬性傳回的資料比您想要的多，請針對屬性新增 $select 陳述式。

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

例如，下列範例查詢只會從展開的IterationName屬性中選取IterationPath和Iteration資料。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

查詢會傳回下列數據。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath))",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

下表顯示如何使用 $expand 和 $select 子句來選取導覽屬性中的數個欄位。例如，您使用$expand=AssignedTo($select=UserName)來傳回導覽屬性中「指派給」屬性的Identity欄位。

類型欄位	參考屬性	範例子句
日期時間	`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)

使用巢狀展開語句

您可以使用巢狀 OData $expand 陳述式。例如，下列查詢會使用巢狀 $expand 陳述式來顯示疊代所在的專案。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

查詢會傳回下列資料：

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        "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": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

您可以新增 $select 陳述式，例如只傳回 IterationName 和 IterationPath 從 Iteration：

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

此查詢會傳回下列資料：

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath,Project))",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

結果只顯示來自 IterationName 的 IterationPath 和 Iteration，以及作為 Project 結果中的巢狀物件 Iteration。

注意

當您在$expand陳述式中巢狀$select子句時，必須在巢狀子句之前使用分號;以避免錯誤。

進行日期範圍查詢

下列範例查詢會傳回上次 變更日期 大於或等於 2025 年 1 月 1 日的工作專案。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

下列範例查詢會傳回最後一次 變更日期 發生在 2025 年 10 月 31 日至 11 月 7 日這週的工作項目。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z&ChangedDate le 2025-11-07Z

排序結果

指定 $orderby 排序結果的選項，或指定要傳回結果的順序。您可以使用關鍵字 asc 或 desc按遞增或降序排序。下表顯示一些範例。

排序方式	條款
工作項目識別碼	`/WorkItems?$orderby=WorkItemId`
工作專案ID遞減	`/WorkItems?$orderby=WorkItemId desc`
工作專案類型和狀態	`/WorkItems?$orderby=WorkItemType,State`

後續步驟

專案與組織範圍的查詢

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-17