在 Azure DevOps 中建構 Analytics 的 OData 查詢

發行項
10/29/2024

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

Azure DevOps 的報告平臺分析可以回答有關您項目過去或目前狀態的量化問題。分析支援其元數據和實體集數據的 OData 查詢。透過從網頁瀏覽器執行簡單的查詢，您可以熟悉數據模型和查詢程式。

在本文中，您將瞭解下列內容：

如何建構雲端或內部部署的分析 OData 查詢
如何查詢分析元數據
如何查詢實體集的分析 OData
支援哪些查詢選項和建議的順序
強制執行伺服器端分頁時

您可以從任何支援的網頁瀏覽器查詢分析。如需可用來查詢分析的其他工具，請參閱分析查詢工具。

注意

OData 是應用層級通訊協定，可透過 RESTful 與數據互動（其中 REST=表示狀態傳輸）介面），支持數據模型的描述，以及根據這些模型編輯和查詢數據。實體數據模型（EDM）或元數據描述分析中可用的資訊，包括用來查詢數據以建置報表的實體、實體類型、屬性、關聯性和列舉。如需 OData 的概觀，請參閱歡迎使用 OData。

必要條件

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

用來查詢元數據的 URL 元件

分析會在元數據 URL 公開實體模型，其形式是附加 $metadata 至服務根 URL。分析可為 Azure DevOps 中的專案或整個組織提供服務根目錄。

您可以查詢中繼資料來查詢下列任何一個資料元素。

實體類型和實體集
屬性和導覽屬性
Surrogate 索引鍵
列舉清單
EntitySet
容器
篩選函式（Org.OData.Capabilities.V1.FilterFunctions）
支援的匯總（Org.OData.Aggregation.V1.ApplySupported）
批次支援（Org.OData.Capabilities.V1.BatchSupportType）

您使用的 URL 取決於您正在查詢 Azure DevOps Services （雲端）或內部部署 Azure DevOps Server 的數據。

雲端（Azure DevOps Services
內部部署 （Azure DevOps Server

若要查詢裝載在雲端中的組織或專案的元數據，請輸入URL語法，如網頁瀏覽器中所示。將和 {ProjectName} 取代{OrganizationName}為您組織名稱和您想要查詢的項目名稱。若要傳回組織的所有元數據，請勿指定項目名稱。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

注意

最新的 Analytics OData 版本為 v4.0-preview。您可以將此版本用於針對託管服務的所有查詢。如需分析版本和可用數據的詳細資訊，請參閱分析的數據模型。

以下是裝載在 Azure DevOps Services 上的 fabrikam 組織的範例。

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

若要查詢內部部署伺服器的元數據，請輸入URL語法，如網頁瀏覽器中所示。以您的內部部署名稱取代 {ServerName}和 {CollectionName} {ProjectName} 。若要傳回集合的所有元數據，請勿指定項目名稱。

https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata 
\_________________________________________________/\______________/\________/
                            |                              |            | 
     On-premises server, collection, project         OData version  return metadata

注意

以下是名為 fabrikam-devops 的伺服器範例，以及 DefaultCollection 裝載在 Azure DevOps Server 2022 上的：

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

解譯元數據回應

分析會傳回數據模型的 XML 檔案。使用瀏覽器搜尋函式來尋找感興趣的實體專屬資訊。

提示

視您使用的瀏覽器而定，此檔案可能或可能不會以可讀取的方式格式化。如果未格式化，您可以透過網頁瀏覽器搜尋到免費的線上 XML 格式器。

分析元數據中定義的兩個主要架構是 Microsoft.VisualStudio.Services.Analytics.Model，其定義實體類型和列舉型別及其成員，以及 Default 定義實體容器和實體集以及支援的 OData 篩選、轉換和自定義聚合函數的架構。如需詳細資訊，請參閱 Analytics 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>

所有實體類型都與屬性和導覽屬性相關聯。您可以使用這兩種類型的屬性來篩選實體集的查詢。這些會以或的形式列在的元數據中EntityTypeProperty。NavigationalProperty 您可以使用相關的實體來指定其他篩選，例如反覆專案路徑、區域路徑或 Teams。

下列代碼段提供實體元數據 WorkItem 的部分檢視。屬性會對應至工作專案欄位，以及分析所擷取的特定資料，例如 LeadTimeDays 和 CycleTimeDays。導覽屬性會對應至其他實體集，或針對實體類型擷取的特定分析數據，例如Revisions、 LinksChildren和 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"/>
...

查詢實體的 URL 元件

若要查詢分析數據和建置報表，您通常會查詢實體集。如需支持實體的概觀，請參閱 Analytics OData 元數據。

下列 URL 可用來查詢特定的 EntitySet，例如 WorkItems、 WorkItemSnapshot和 PipelineRuns。

雲端（Azure DevOps Services
內部部署 （Azure DevOps Server

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

以下是 fabrikam 組織的範例 ，其會傳回針對 Fabrikam Fiber 項目定義的工作項目計數。

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

此範例會傳回 1399 個工作專案。

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

以下是 fabrikam 伺服器 DefaultCollection 的範例，其會傳回針對 Fabrikam 專案定義的工作項目計數。

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

此範例會傳回 1399 個工作專案。

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

注意

如果您沒有包含 $select 或 $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 語句，並傳回所有專案、所有數據行和所有數據列。如果您有大量的記錄，可能需要幾秒鐘的時間。如果您有超過 10,000 個工作專案，則會強制執行伺服器驅動分頁。

若要避免發生使用量限制，請一律包含 $select 或 $apply 子句。

如需實體元數據屬性和關聯性資訊，請參閱下列文章：

範例：查詢特定實體集

若要查詢特定實體集，例如 WorkItems、 Areas或 Projects，請新增實體集的名稱： /WorkItems、 /Areas或 /Projects。如需實體集的完整清單，請參閱分析的數據模型。

雲端（Azure DevOps Services
內部部署 （Azure DevOps Server

例如，您可以查詢 /Projects 並選取以傳回 ProjectName 屬性，以取得為組織定義的項目清單。針對 fabrikam 組織，URL 如下所示。

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

分析會傳回為 fabrikam 組織定義的這些項目項目名稱。

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

以下範例會查詢Projects實體集，以傳回 fabrikam 伺服器上 DefaultCollection 上定義的所有項目名稱，

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

查詢選項

查詢選項是套用至資源的一組查詢字串參數，可協助控制URL中資源所傳回的數據量。

查詢選項應依照下表所列的順序來指定。

查詢選項	備註
`$apply`	您可以套用至查詢的轉換集，例如：`filter`、、`groupby`、、 `computeexpand,` `aggregate` `concat` 如需範例，請參閱使用分析匯總工作追蹤數據。
`$compute`	支援的 OData 函式，您可以指定要定義可用於、`$filter`或`$orderby`表示式的`$select`計算屬性。
`$filter`	使用來篩選傳回的資源清單。為 `$filter` 指定的表達式會針對集合中的每個資源進行評估，而且只有表達式評估為 true 的專案才會包含在回應中。表達式評估為 false 或 Null 的資源，或因許可權而無法使用的參考屬性，都會從回應中省略。如需範例，請參閱使用 Analytics 查詢工作追蹤數據。
`$orderby`	使用來指定應該傳回記錄的順序。如需範例，請參閱使用分析查詢工作追蹤數據。
`$top`/`$skip`	使用來限制傳回的記錄數目。如需範例，請參閱專案和組織範圍的查詢。
`$select`/`$expand`	使用 `$select` 來指定建置報表所需的數據行。使用 `$expand` 來巢狀其他查詢選項。每個 `expandItem` 都會相對於包含所展開之導覽或數據流屬性的實體進行評估。以分號分隔的查詢選項清單，以括弧括住導覽屬性名稱。允許的系統查詢選項為 `$filter`、、`$select`、、`$orderby$skip`、`$top`、`$count`、 `$search`和 `$expand`。如需範例，請參閱使用分析查詢工作追蹤數據。
`$skiptoken`	使用來略過指定的記錄數目。
`$count` 或 `$count=true`	輸入 `$count` 以只傳回記錄數目。輸入 `$count=true`可傳回記錄和查詢數據的計數。如需範例，請參閱使用分析匯總工作追蹤數據。

提示

避免在單一查詢中混用 $apply 和 $filter 子句。若要篩選查詢，您有兩個選項：（1）使用 $filter 子句或（2）使用 $apply=filter() 組合子句。這些選項中的每一個都適合自己使用，但將它們結合在一起可能會導致一些非預期的結果。

強制執行伺服器端分頁

分析會在查詢結果超過 10000 筆記錄時強制分頁。在此情況下，您將取得數據的第一頁，並連結以取得下一頁。連結（@odata.nextLink）可以在 JSON 輸出的結尾找到。看起來會像原始查詢後面接著 $skip 或 $skiptoken。例如：

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

注意

將數據提取至 Power BI Desktop 或 Excel 等用戶端工具時，工具會自動遵循下一個連結並載入所有必要的記錄。

下一步

使用 OData Analytics 建構基本查詢

共用方式為

在 Azure DevOps 中建構 Analytics 的 OData 查詢

必要條件

用來查詢元數據的 URL 元件

解譯元數據回應

查詢實體的 URL 元件

範例：查詢特定實體集

查詢選項

強制執行伺服器端分頁

下一步

意見反應

其他資源

共用方式為

在 Azure DevOps 中建構 Analytics 的 OData 查詢

必要條件

用來查詢元數據的 URL 元件

解譯元數據回應

相關實體和導覽屬性

查詢實體的 URL 元件

範例：查詢特定實體集

查詢選項

強制執行伺服器端分頁

下一步

相關文章

意見反應

其他資源