Azure Data Manager for Energy 的原生分析功能,透過分析消費區(ACZ)提供,使能源數據對分析與人工智慧來說更為便利。 ADME 將選定的 OSDU® 資料同步至客戶擁有的儲存體中,採用開放的 Delta Parquet 格式,讓資料可與 Microsoft Fabric、Azure Databricks、Snowflake 及其他相容的分析平台搭配使用,無需建立與維護自訂資料管線。
Analytics Consumption Zone (ACZ) 會將 Azure Data Manager for Energy 選定的實體數據匯出到 Azure Data Lake Storage Gen2 帳戶。 ACZ 以開放式 Delta Parquet 格式寫入 Azure Data Manager for Energy 資料。 像 Microsoft Fabric 和 Azure Databricks 這類服務可以直接讀取此格式。
要啟用 ACZ,請參閱 啟用分析消費區。
什麼是ACZ?
ACZ 是一個受管理的同步層。 它會將你的 Azure Energy Data Manager 的實體資料匯出到你擁有的 Azure Data Lake Storage Gen2 儲存帳戶。 接著你可以將這些資料連接到分析、報告和機器學習工具。
設定 ACZ 分為兩個部分。 你只需在 Azure 入口網站中的 Azure Data Manager for Energy 資源上啟用 ACZ一次。 然後你透過 ACZ API 建立一個或多個 ACZ 實例 。 每個 ACZ 實例都是資料分割中的匯出配置,定義 ACZ 匯出的種類及寫入位置。 ACZ 只匯出你建立的 ACZ 實例資料。
ACZ 的主要特徵:
- 客戶自有儲存:您可以建立並管理一個 Data Lake Storage Gen2 儲存帳戶,資料會存放在那裡。 我們建議使用與您的 Azure Data Manager for Energy 執行個體位於相同區域的儲存體帳戶。 如果你有資料駐留要求,你必須負責在適當區域選擇一個儲存帳戶。
- 開放格式:您的資料以 Delta Parquet 格式匯出。 分析引擎廣泛支援此格式。
- 選擇性同步:您可以選擇要同步的實體類型。選項包括目錄類型及 Wellbore Domain 資料管理 Service(DDMS)類型(預覽)。
- 歷史與增量同步:你會從 ACZ 獲得現有資料的初步快照。 接著,ACZ 會在變更發生時同步這些變更。
- 入口網站與 API 管理:你可以在 Azure 入口中啟用 ACZ,並透過 REST API 建立和管理 ACZ 實例。
Architecture
下圖顯示了 ACZ 的資料流程。
ACZ 運作方式
支援實體類型
Note
井筒 DDMS 匯出目前處於預覽階段。 目錄匯出功能已正式可用。 關於適用於預覽版 Azure 功能的法律條款,請參閱 Microsoft Azure 預覽版補充使用條款。
ACZ 會同步 Azure Data Manager for Energy 實體類型中的兩個類別。
| 類別 | Description | 範例類型 |
|---|---|---|
| 目錄類型 | 儲存服務的主要資料與參考資料 |
osdu:wks:master-data--Well:*、osdu:wks:reference-data--UnitOfMeasure:* |
| 井筒 DDMS 類型(預覽) | 來自 Wellbore DDMS 的實體 | osdu:wks:work-product-component--WellLog:* |
ACZ 也可以透過 entitlements export(預覽)匯出 OSDU 權利會員資料。
當你建立 ACZ 實例時,你可以透過提供以下條件來指定要同步的實體類型:
-
catalogKinds:目錄類型模式列表(例如,osdu:wks:master-data--Well:*)。 -
wellboreDDMSKinds:Wellbore DDMS 種類模式清單 (例如osdu:wks:work-product-component--WellLog:*)。
這些種類模式做為篩選條件,可決定 ACZ 要匯出並保持同步的 Azure Data Manager for Energy 記錄。
使用 allCatalogSync 旗標
這個 allCatalogSync 旗標是一個可選的布林參數,你可以在建立 ACZ 實例時指定它。 當設定為 true時,它會同步資料分割區中所有目錄類型。
關鍵行為:
-
allCatalogSync是在要求主體中 區段configuration指定的。 - 當
allCatalogSync: true時,ACZ 會自動匯出所有目錄類型。 - 設定中的
catalogKinds和wellboreDDMSKinds陣列對於目錄資料會被忽略。 - 井筒 DDMS 的大量檔案下載 不受此旗標設定影響。 只有在
wellboreDDMSKinds中明確列出的類型才會下載檔案。
範例配置:
// Selective catalog sync - only Wells and Fields
{
"allCatalogSync": false,
"configuration": {
"catalogKinds": [
"osdu:wks:master-data--Well:*",
"osdu:wks:master-data--Field:*"
]
}
}
// Sync all catalog kinds using allCatalogSync flag
{
"allCatalogSync": true,
"configuration": {
// catalogKinds is ignored when allCatalogSync is true
}
}
// Sync all catalog kinds, but Wellbore DDMS files only for specified kinds
{
"allCatalogSync": true,
"configuration": {
"wellboreDDMSKinds": [
"osdu:wks:work-product-component--WellLog:*"
]
}
}
版本類型
當你建立 ACZ 實例時,你可以選擇如何處理實體版本。
| 類型 | Description |
|---|---|
| LATEST_VERSION | 僅匯出每個實體的最新版本。 預設並建議使用。 |
| ALL_VERSIONS | 匯出每個實體的所有版本。 保留完整版本的歷史紀錄。 |
生命週期狀態
每個 ACZ 會經過以下狀態:
| 現況 | Description |
|---|---|
| 現役 | 運作中。 ACZ 會逐步同步變更。 |
| 失敗 | 錯誤導致設定或同步中斷。 |
| ACCESS_DENIED | ACZ 無法存取目的地的 Data Lake Storage Gen2 儲存帳戶。 |
歷史概況
當你建立新的 ACZ 實例時,服務會擷取一個歷史快照。 此快照匯出所有符合設定實體類型(catalogKindswellboreDDMSKinds和 )的現有紀錄。 快照會依序進入以下狀態:
| 現況 | Description |
|---|---|
| 處理中 | 正在積極匯出資料。 |
| 完成 | 所有歷史資料皆已匯出。 |
| 失敗 | 發生錯誤。 |
快照結束後,ACZ 會切換到增量模式。 它能以近乎即時的方式捕捉新紀錄與更新紀錄。
ACZ 如何處理資料變更
ACZ 會將 Azure 能源資料管理器中建立、更新及刪除的紀錄傳播到 Delta 資料表。
- Creations and Updates:當您建立紀錄或更改其資料區塊時,Azure 能源資料管理員會建立新版本。 ACZ 偵測到變更並寫入新一列到 Delta 資料表。
- 僅中繼資料更新:當 PATCH 操作在未建立新版本的情況下更改存取控制清單、法律資訊或標籤時,ACZ 會更新現有版本對應的資料列。
-
虛刪除:當您在適用於能源的 Azure 資料管理員中虛刪除記錄時,ACZ 會將
isActive欄位設為False,而不是移除該列。 對於使用ALL_VERSIONS的 ACZ 實例,所有儲存的記錄版本都被標記為非活躍。 軟刪除會保留歷程記錄,供稽核與時間穿梭查詢使用。 - Purges:當您在 Azure Data Manager for Energy 中清除記錄時,ACZ 會從 Delta 資料表中永久移除該記錄。 該列會被刪除,無法從 ACZ 資料中恢復。
Note
ACZ 會寫入原始(青銅)層,而一個資料表可以包含同一記錄 ID 和版本的多列。 ACZ 不會移除這些重複項目。 當你建立下游資料表時,請選擇每個 id的最新活躍資料列。
Warning
ACZ 是從 Azure Data Manager for Energy 到 Data Lake Storage Gen2 的單向只讀同步:
- 資料流只會從 Azure Data Manager for Energy 流向 Data Lake Storage Gen2。
- 請勿修改、刪除或直接在 Data Lake Storage Gen2 的 ACZ 資料夾中新增檔案。
- 手動更改 ACZ 資料會導致同步損壞並造成資料不一致。
- ACZ 會管理所有 Delta Lake 作業 (交易記錄、檢查點和壓縮)。
在分析和報告方面,將匯出的資料視為唯讀。 所有資料修改必須在 Azure 能源資料管理器中進行。
辨識新、已更新及已刪除的紀錄
ACZ 在其資料表中未啟用 Delta Lake 變更資料摘要。 如果您自行啟用此功能,每次記錄更新都會顯示為先刪除、再插入。 若要循序漸進地處理變更,請使用ingestTime作為浮水印。 ACZ 在寫入資料列變更時都會重新整理 ingestTime,包括:
- 新記錄與新記錄版本。
- 僅包含元資料的更新,例如標籤的變更,且不會產生新的記錄版本。
- 軟刪除。 ACZ 設定
isActive為False。
已清除的記錄會從 Delta 資料表中移除。 若要從下游資料表移除遭到清除的記錄,請定期將其與目前的 ACZ 資料表比對,或重新建置下游資料表。
Note
使用 ingestTime 而非 modifyTime 來偵測變更。
modifyTime在 Azure 能源資料管理員中反映紀錄更新,且在紀錄軟刪除時不會改變。
參考實作請參見 ADME ACZ Silver Layer 範例筆記本。
資料輸出格式
ACZ 會使用 Parquet 編碼檔案 (),以 DELTA_PARQUET 格式寫入資料。 Delta Lake 支援原子性、一致性、隔離與持久性交易。 它也支援時間旅行和高效的增量讀取。
Data Lake Storage Gen2 資料夾結構
ACZ 會將資料寫入你建立 ACZ 實例時指定的儲存帳號。 可選 basePath 屬性的第一個區段是容器,任何額外的區段都是該容器中的資料夾。 第一個區段必須是有效的容器名稱。 關於命名規則,請參見「 命名與引用容器、blobs 與元資料」。 如果你沒有指定基礎路徑,ACZ 會使用一個名為 <aczId>. 的容器。 如果容器不存在,ACZ 會建立該容器,並將資料寫入名為 <aczId>的資料夾。 範例請參見 「建立 ACZ 實例」。
<storage-account>/
└── <container>/ ← first segment of basePath, or <aczId>
└── [<more basePath folders>/]
└── <aczId>/
├── osducatalog/ ← Delta table, partitioned by kind
│ └── _delta_log/
├── wellboreDDMS/ ← Wellbore DDMS bulk files (Parquet and JSON)
│ ├── work-product-component--WellLog/
│ └── work-product-component--WellboreTrajectory/
└── entitlements/ ← Delta table (preview), only when entitlements export is enabled
Note
自 2026 年 10 月版本起,新的 ACZ 實例會將 Wellbore DDMS 實體資料夾存放在 wellboreDDMS 下。 在 2026 年 10 月發行版本發佈之前建立的 ACZ 執行個體會保留先前的配置,Wellbore DDMS 執行個體資料夾直接置於<aczId>/底下。 若要查看 ACZ 執行個體建立的時間,請參閱 Get ACZ API 回覆中的createdTs值。
如需權利資料表的詳細資訊,請參閱分析使用量區 (預覽版) 中的權利匯出。
金鑰詳細資料
| 元素 | Description |
|---|---|
| 頂層資料夾 | 一個名為 <aczId> 的資料夾,每個 ACZ 實例各有一個,位於由 basePath 定義的容器與資料夾中。 |
osducatalog/ |
所有目錄類型共用一張 Delta 表格。 依類別劃分(例如, kind=osdu:wks:master-data--Well:1.0.0)。 |
_delta_log/ |
三角洲湖交易記錄。 追蹤所有資料表變更,以支援 ACID 交易與時間移動。 |
| DDMS 實體資料夾 | 每種 Wellbore DDMS 實體類型各有一個資料夾(例如,work-product-component--WellLog)。 從 2026 年 10 月版本開始,這些資料夾都位於 wellboreDDMS/ 之下。 依實體類型與記錄 ID 儲存 Parquet 與 JSON 檔案。 這些資料夾不是 Delta 表格;要找到記錄的檔案,請使用 osducatalog 中的 fileDownloadFolder 欄位。 |
| Parquet 檔案 | 以 Snappy 壓縮的資料檔案。 更新會產生新檔案。 ACZ 會執行 VACUUM ,並 OPTIMIZE 壓縮小型檔案並移除舊檔案。 ACZ API 回覆中的maintenance屬性顯示這些維護活動的狀態及最後一次成功執行記錄。 |
ACZ 定期對其 Delta 資料表執行維護作業,包括 VACUUM,以移除較舊的資料檔案。 時間旅行查詢只能讀取最近的表格版本。 為了保留更長的歷史紀錄,請定期將資料複製到你自己的儲存空間。 如果你對資料表歷程記錄有特定需求,請 提出支援請求。
Delta 表結構
Delta 表格包含以下欄位:
| Field | 類型 | Description |
|---|---|---|
id |
String | OSDU® 紀錄識別碼。 |
version |
String | 版本號碼。 |
kind |
String | 完整限定的 OSDU® 種類。 |
data |
String | 資料區塊(JSON)。 |
meta |
String | 元資料(JSON)。 |
acl |
String | 存取控制清單。 |
legal |
String | 法律標籤。 |
tags |
String | 使用者自訂標籤。 |
createUser |
String | 建立記錄的使用者。 |
createTime |
Timestamp | 建立此紀錄的時間。 |
modifyUser |
String | 最後修改紀錄的使用者。 只有 Schema 版本 2。 |
modifyTime |
Timestamp | 記錄上次修改的時間。 只有 Schema 版本 2。 |
ingestTime |
Timestamp | ACZ 擷取記錄的時間。 |
isActive |
布林值 |
True 如果已啟用。 若已虛刪除,則為 False。 |
Note
Wellbore DDMS 種類的資料列也包括fileDownloadTime、fileDownloadState和fileDownloadFolder,這些列會追蹤 Wellbore DDMS 執行個體資料夾中的記錄大量檔案。
結構描述版本
ACZ API 回應中的 catalogSchemaVersion 屬性顯示 ACZ 實例所使用的結構描述:
| 版本 | Description |
|---|---|
| 1 | 較早的結構描述。
modifyUser 和 modifyTime 不是獨立的欄位。 它們只在 data 欄位中的 JSON 裡。 |
| 2 | 新 ACZ 實例目前的 schema。 新增頂層 modifyUser 和 modifyTime 欄位。 |
現有的 ACZ 實例會保留原有的 schema 版本。 要使用目前的架構,請建立一個新的 ACZ 實例。 沒有從版本 1 移轉到版本 2 的途徑。
權益匯出(預覽)
ACZ 可選擇性地將 OSDU 會員資格資料匯出至 entitlements Delta Lake 表格,與目錄資料並列。 你可以利用這些數據在下游分析平台實施權限感知篩選。 ACZ 未設定或強制執行下游的列級安全性。
權利項目匯出預設為關閉。 要啟用它,請 建立支援請求。 如需詳細資料,請參閱分析使用量區(預覽版) 中的授權權益匯出。
界限與進入
限制
| Constraint | Limit |
|---|---|
| 每個資料分割區的最大 ACZ 實例數 | Three |
| ACZ 名稱唯一性 | 必須在資料分割區內是唯一的 |
| 目標格式 | 僅限 Delta Parquet |
| 儲存體類型 | 僅限 Data Lake Storage Gen2 |
| 分層支援 | 開發者與標準層級 |
| 進行中的歷史快照 | 每個資料分割區一次處理一個。 等 ACZ 實例的歷史快照完成後再建立另一個。 |
| ACZ 定義變更 | 不支援。 要更改種類或其他設定,請建立一個新的 ACZ 實例。 每個 ACZ 實例都有自己的識別碼和輸出路徑。 |
| 目的地儲存網路存取 | ACZ 目前要求目的地儲存體帳戶允許公用網路存取。 使用防火牆 IP 規則限制存取、停用公共網路存取或私有端點的儲存帳號則不被支援。 支援使用私有端點的 Azure Data Manager for Energy 實例。 |
身份驗證與授權
ACZ 要求:
-
API 存取:要呼叫 ACZ API,您必須屬於
users@{data-partition-id}.dataservices.energy、users.datalake.ops@{data-partition-id}.dataservices.energy和service.entitlements.user@{data-partition-id}.dataservices.energy群組。 - 儲存存取:受管理身份需要在 Data Lake Storage Gen2 容器上扮演 Storage Blob 資料貢獻者角色(或等效角色)。
- Azure Data Manager for Energy access:當你在 Azure portal 啟用 ACZ 時,受控識別會分配給 Azure Data Manager for Energy 資源。 相關步驟請參見 啟用 Analytics Consumption Zone。
備份與還原
ACZ 不包含在適用於能源的 Azure 資料管理員的備份與還原中。 如果你從備份還原 Azure Data Manager for Energy 資源或資料分割區,你儲存帳戶中的 ACZ 資料就不再與還原後的資料相符。 在還原完成後建立新的 ACZ 執行個體會產生新的歷史快照。
商務持續性和災害復原
ACZ 未納入 Azure Data Manager for Energy 的跨區域災難復原。 區域故障轉移後,ACZ 可能無法恢復同步,或可能遺失故障轉移期間的變更。 在故障切換過程中進行的歷史快照可能無法完成。 若要還原 ACZ,請建立新的 ACZ 執行個體 (會產生新的歷史快照)。
準備事項:
- 為您的目的地 Data Lake Storage Gen2 帳戶設定冗餘。 ACZ 會寫入你指定的儲存體帳戶,不會將其複寫到其他位置。 如需了解選項,請參閱 Azure 儲存體 備援。
- 保留您需要用來重新建立 ACZ 執行個體的 ACZ 設定,例如種類、
basePath和儲存體帳戶。
欲了解更多資訊,請參閱 Azure Data Manager for Energy 中的可靠性。