項目和組織範圍的查詢

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

使用 Azure DevOps 的分析，您可以建構限定於專案或組織或集合的查詢。 您可以直接在瀏覽器或 Power BI 中執行這些查詢。

專案範圍查詢有助於回答單一項目的問題，而組織和集合範圍查詢可讓您回答跨專案界限的問題。 組織和集合範圍查詢需要更廣泛的用戶權力或仔細的範圍限制，以確保您的查詢不會因為許可權不足而遭到封鎖。

注意

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

必要條件

• 若要檢視分析數據和查詢服務，您必須是具有基本存取權或更高許可權的項目成員。 根據預設，所有專案成員都會獲得查詢分析的許可權，並定義分析檢視。
• 若要瞭解有關服務與功能啟用和一般數據追蹤活動的其他必要條件，請參閱 存取分析的許可權和必要條件。

重要

如果您沒有組織中所有專案的存取權，建議您將專案篩選套用至所有查詢。 將數據提取到 Power BI 或 Excel 等用戶端工具時，使用專案路徑語法是確保所有數據受到指定專案限制的最佳方式。 我們建議您只有在需要報告兩個或多個專案時，才使用組織範圍或集合範圍的查詢。

專案範圍的查詢

您可以將 OData URL 輸入至支援的網頁瀏覽器，以建構查詢。

專案層級 OData 查詢的基底 URL 如下列語法所示。

雲端 （Azure DevOps Services

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/

在提供的範例中，以您要查詢的組織名稱與項目名稱取代 {OrganizationName} 和 {ProjectName} 。

內部部署 （Azure DevOps Server

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/

在提供的範例中，進行下列取代：

• 包含 {ServerName}:{Port}/tfs/ 的 analytics.dev.azure.com
• {CollectionName} 使用您的專案集合名稱 （預設值為 DefaultCollection）
• {ProjectName} 具有您要查詢之項目的名稱。

注意

本文中提供的其餘範例是以 Azure DevOps Services URL 為基礎。 您必須在 Azure DevOps Server URL 中取代 ，以練習範例。

傳回工作專案的計數

例如，下列專案範圍查詢會傳回特定專案的工作專案計數。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count

例如，Fabrikam Fiber 專案的查詢會傳回 7126 個工作專案的計數。 已刪除的工作專案不會包含在計數中。

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count

7126

傳回項目區域路徑

同樣地，下列查詢字串會傳回特定項目的區域：

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Areas

這相當於組織範圍查詢的下列篩選：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas?
  $filter=Project/ProjectName eq '{ProjectName}'

例如，Fabrikam Fiber 專案的查詢會傳回為區域路徑定義的所有屬性，因為查詢中不會套用任何 $select 運算符。

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas

下列範例顯示針對單一區域路徑傳回的數據。

ProjectSK	"56af920d-393b-4236-9a07-24439ccaa85c"
AreaSK	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaId	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaName	"Service Delivery"
Number	55373
AreaPath	"Fabrikam Fiber\\Service Delivery"
AreaLevel1	"Fabrikam Fiber"
AreaLevel2	"Service Delivery"
AreaLevel3	null
AreaLevel4	null
AreaLevel5	null
AreaLevel6	null
AreaLevel7	null
AreaLevel8	null
AreaLevel9	null
AreaLevel10	null
AreaLevel11	null
AreaLevel12	null
AreaLevel13	null
AreaLevel14	null
Depth	1

使用 $expand 選項

搭配選項使用專案範圍查詢 $expand 時，您不需要提供其他篩選。

例如，下列專案範圍篩選：

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems?
  $expand=Parent

會自動篩選以強制執行安全性：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=ProjectName eq '{ProjectName}')

組織範圍的查詢

組織層級查詢的基底 URL 如下所示：

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0

搭配選項使用組織範圍的查詢 $expand 時，您必須提供另一個篩選條件。

例如，下列組織範圍的查詢會使用 $expand 來擷取所有工作專案的子系。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children

它需要另一個篩選條件來確認子系僅限於指定的專案：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

傳回所有工作專案的父代

下列查詢會使用 $expand 選項來擷取所有工作專案的父代。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent

它需要另一個篩選條件來確認父系僅限於指定的專案：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}')

如果沒有其他篩選條件，如果任何工作專案的父系參考您沒有讀取許可權之專案中的工作專案，要求將會失敗。

專案層級安全性限制

分析對與專案層級安全性相關的查詢語法有更多限制。

any或 all 篩選會套用至 上的$expand基底實體。 針對以專案為基礎的篩選，我們會在使用 $expand時明確忽略篩選：

例如，下列查詢：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

解譯為：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children

如果您無法存取所有專案，則和 將會失敗。

若要解決限制，您必須在 中 $filter新增額外的表達式：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}' and Children/any(r: r/ProjectName eq '{ProjectName}')
  &$expand=Children

$level只有在您可以存取集合中的所有專案，或使用專案範圍查詢時，才支援using：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Children($levels=2;$filter=ProjectName eq '{ProjectName}')

分析不支援使用 $it 子句之專案的任何跨層級參考。 例如，下列查詢會參考根工作專案的 ProjectName using $it alias，但不支援：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Links(
    $expand=TargetWorkItem;
    $filter=TargetWorkItem/Project/ProjectName eq $it/Project/ProjectName)

後續步驟

查詢匯總數據

相關文章

• 查詢指導方針