分析的數據模型

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

Azure DevOps 的 Analytics 數據模型是由實體集所組成，其成員 （實體） 包含您可以篩選、彙總和摘要的屬性。 此外，它們還包含 將實體與其他實體建立關聯的導覽屬性 ，以提供其他屬性的存取權，以供選取、篩選和分組。

瞭解 Analytics 資料模型

Analytics 服務提供結構化方法，透過 OData 端點存取 Azure DevOps 數據。 此資料模型可讓您：

• 查詢工作追蹤資料：存取工作項目、區域、迭代和相關中繼資料
• 分析管線資訊：查詢建置和發行管線資料
• 測試結果報告：存取測試執行和規劃資料
• 建立自訂報表：建置 Power BI 報表和其他分析解決方案

綱要命名空間

Analytics 資料模型在兩個結構描述命名空間上運作：

• Microsoft.VisualStudio.Services.Analytics.Model
• Microsoft.VisualStudio.Services.Analytics

這些命名空間會組織實體並定義其結構，確保不同 Azure DevOps 功能之間的資料存取模式一致。

實體集和實體類型

實體類型是具有索引鍵的具名結構化型別。 他們會定義每個實體的具名屬性和關聯性。 EntityType 的鍵源自於基本屬性的子集，例如 WorkItemId、PipelineId、ReleasePipelineId，以及該實體類型的其他屬性。

實體集是實體的具名集合。 例如，WorkItems 是一個包含 WorkItem 實體的實體集。 實體的索引鍵可唯一識別實體集內的實體。 如果多個實體集使用相同的實體類型，索引鍵值的相同組合可能會出現在多個實體集中並識別不同的實體，每個實體集都會顯示此索引鍵組合。 每個實體都有不同的實體標識碼。實體集提供數據模型的進入點。

實體集會在 OData 元數據中描述，並依專案而有所不同。 您可以藉由要求專案的 OData 元數據，來探索實體集、實體類型和屬性的完整清單。 若要瞭解如何，請參閱 建構分析的 OData 查詢。

複合實體

複合實體支援特定場景。 系統從更簡單的實體組成它們，通常需要更多的運算資源來產生，並且可能會傳回更大的結果集。 若要達到最佳效能並避免不必要的節流，請確定您查詢情境所需的正確實體。

例如， WorkItemSnapshot 結合 WorkItemRevisions 和 Dates ，讓每個日期每個工作專案都有一個修訂。 此表示法支援 OData 查詢，這些查詢著重於一組已篩選工作專案的趨勢資料。 不過，您不應該使用此複合實體來查詢工作專案的目前狀態。 相反地，您應該使用 WorkItems 實體集來產生執行速度更快的查詢。

同樣地，某些實體可能包含所有歷史值，而其他實體可能只包含目前的值。 WorkItemRevisions 包含所有工作專案歷程記錄，而在需要關注當前值的情況下，不應該使用這些記錄。

關係

若要產生更複雜的查詢結果，您可以使用關聯性來合併實體。 您可以使用關聯性來展開、篩選或摘要數據。

某些導覽屬性會產生單一實體，而其他則會產生實體的集合。 下圖顯示選取實體及其導覽屬性。 為了清楚起見，已省略一些複合實體和關聯性。

瞭解實體關係

Analytics 資料模型會使用數種類型的關係：

• 一對多：單一父實體與多個子實體相關，例如，一個區域對多個工作項目。
• 多對一：多個實體與單一父實體相關，例如，許多工作項與一個範疇。
• 一對一：單一實體與一個其他實體相關
• 多對多：多個實體與多個其他實體有關聯（例如，工作項目與標籤）

關聯鍵

實體關聯性也會表示為外鍵，讓外部工具可以聯結實體。 這些屬性具有後綴 「SK」 而且是整數或 GUID 數據類型。 日期屬性具有具有下列格式的對應整數日期索引鍵屬性： YYYYMMDD。

工​​作跟蹤實體類型和實體組合

指定的 API 版本支援下列實體類型和實體集。 如需完整的參考，請參閱 Azure Boards Analytics 的工作追蹤元數據參考。

用於報告的關鍵工作追蹤實體

建立報表時，請考慮以下主要實體集：

• 目前狀態報告：用於 WorkItems 目前的工作項目狀態
• 歷史趨勢報告：用於 WorkItemSnapshot 一段時間內的趨勢分析
• 詳細的變更追蹤：使用 WorkItemRevisions 來獲取完整歷史記錄
• 看板特定報告：用於 WorkItemBoardSnapshot 看板分析

使用 Analytics 資料模型的最佳做法

效能優化

1. 選擇正確的實體：使用當前狀態的實體來進行狀態報告，使用快照型實體來分析趨勢。
2. 儘早篩選：在實體層級套用篩選器，而不是在資料擷取之後套用篩選器
3. 限制資料範圍：使用日期篩選器限制歷史資料查詢
4. 使用適當的聚合： 盡可能利用內置的聚合功能

查詢設計模式

目前狀態查詢

/WorkItems?$filter=State ne 'Closed'&$select=WorkItemId,Title,State

歷程趨勢查詢

/WorkItemSnapshot?$filter=DateSK ge 20241001&$select=WorkItemId,State,DateSK

關係導覽

/WorkItems?$expand=Area($select=AreaPath),AssignedTo($select=UserName)

要避免的常見陷阱

• 針對目前狀態使用修訂實體：如果WorkItemRevisions已足夠，則不要使用WorkItems
• 過度擴展關係：只展開必要的導航屬性
• 缺少篩選器：一律篩選大型實體集以提高效能
• 忽略複合實體：使用複合實體，例如 WorkItemSnapshot 進行趨勢分析

版本考量

不同的 API 版本提供不同的功能：

• v1.0：基本工作追蹤實體
• v2.0：新增流程和增強的過濾功能
• v3.0-preview：已新增管線和測試實體
• v4.0-preview：增強的複合實體和其他流程指標

根據您的報告要求和您需要存取的實體選擇合適的版本。

相關文章

• OData Analytics 查詢指導方針
• WIT 分析
• 匯總數據
• 探索 Analytics OData 元數據
• 工作追蹤、處理序和專案限制
• 分析視圖數據集設計
• 建構 OData 查詢以用於分析
• 分析安全性和權限