本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 資料轉換功能
以下每項功能都會記錄其用途、運作方式、C-CDA 和 CSV 來源之間的差異，以及使用時機。
+ [轉換設定檔和版本控制](#data-transformation-profiles)
+ [資料轉換 AI 代理器](#data-transformation-ai-agent)
+ [同步 （即時） 轉換和預覽](#data-transformation-sync)
+ [大量 （非同步） 轉換任務](#data-transformation-bulk-jobs)
+ [驗證](#data-transformation-validation)
+ [OID-to-URI映射](#data-transformation-oid-mapping)
+ [證明](#data-transformation-provenance)
+ [漂移偵測](#data-transformation-drift-detection)
+ [MCP 存取](#data-transformation-mcp)
## 轉換設定檔和版本控制
轉換描述檔是來源格式如何轉換為 FHIR R4 的可重複使用定義。它會保留轉換邏輯 (C-CDA 的速度範本，CSV 的 YAML 映射組態），並建立一次，並在您帳戶中的所有資料存放區和轉換任務中重複使用。將定義 （設定檔） 與執行 （任務） 分開，表示您撰寫並測試轉換一次，然後將相同的發佈版本套用至任意數量的任務。
### 建立 設定檔
您以下列三種方式之一建立設定檔：
+ 從入門或基本描述檔：從工作描述檔開始，而不是從空白描述檔開始。對於 C-CDA， AWS 入門設定檔是預先建置的 AWS 定義設定檔，可立即處理常見的 C-CDA 文件格式。對於 CSV，您在建立設定檔時在 Amazon S3 中提供範例檔案，然後調用 AI 代理器來分析它們並產生 YAML 映射組態。
+ 透過複製：複製任何現有的設定檔作為新設定檔的起點。
+ 從原始映射：直接提供 Velocity 範本 (C-CDA) 或 YAML 映射 (CSV)。這是透過 CI/CD 管道部署版本控制設定檔的路徑 （請參閱 [開發套件和 入門 AWS CLI](data-transformation-getting-started-cli.md))。
**重要**
使用 SampleData 建立 CSV 設定檔會註冊範例位置，但不會執行 AI 代理程式。若要產生 YAML 映射，您必須在建立後呼叫 UpdateProfileWithAgent。代理程式會在此時分析您的範例檔案，並產生基本設定檔。
### 版本生命週期
設定檔最多可有一個草稿和最多 99 個已發佈的版本：
+ 新的設定檔一開始是草稿 （版本 0)：您可以自由編輯的可變工作副本。
+ 發佈草稿會建立不可變的編號版本 (v1、v2 等，最多 v99)。發佈的版本永遠不會變更。
+ 轉換任務一律會針對最新發佈的版本執行。由於草稿是分開的，因此您可以在生產任務繼續針對上次發佈的版本執行時繼續編輯：進行中編輯不會影響執行轉換。
+ 具有已發佈版本和較新未發佈編輯的設定檔處於未發佈變更狀態；已發佈版本會保持作用中狀態，直到您再次發佈為止。
### 比較和復原
由於每個已發佈的版本都會保留，因此您可以查看轉換邏輯在版本歷史記錄中的變化。復原不會刪除任何內容：它會從先前的快照建立新的版本，因此會保留完整的歷史記錄和稽核線索。
### 何時使用版本控制
在執行生產任務之前發佈版本，以便將任務固定為已檢閱的邏輯。當變更產生非預期的輸出時，請使用轉返，並比較 以確認實際變更的內容。
## 資料轉換 AI 代理器
資料轉換 AI 代理器消除了編寫和維護 FHIR 映射的手動工作。您不會手動撰寫轉換邏輯，而是描述您想要的結果，而代理程式會產生或更新基礎邏輯：C-CDA 的 Velocity 範本，CSV 的 YAML 映射組態。代理程式內嵌在 的設定檔編輯器中 AWS 管理主控台 ，也可以透過 UpdateProfileWithAgent API 和做為 MCP 工具使用，因此您可以從 AWS 管理主控台、程式碼或 MCP 相容 IDE 使用代理程式。
### 代理程式執行的操作
+ 從資料產生轉換邏輯。對於 CSV，代理程式會分析您在設定檔建立時提供的範例檔案，並產生基本設定檔 ：推斷目標 FHIR 資源和欄位，因此您可以從工作草稿開始，而不是空白設定檔。對於 C-CDA，它會根據您的文件量身打造 AWS 入門設定檔。
+ 編輯自然語言的轉換邏輯。描述純語言的變更，且代理程式會更新基礎範本或映射。例如：
+ 「為藥物資源新增映射。」
+ 「從 languageCommunication 區段映射患者偏好的語言。」
+ 「將預設狀態設定為 Washington for Patient 資源。」
+ 「將 RACE\_CD 資料欄映射至 FHIR 延伸模組。」
+ 「狀態entered-in-error略過記錄。」
+ 在套用之前解釋和檢閱。代理程式會將提議的變更顯示為受影響範本或映射的差異，供您檢閱，並只在接受後套用。發佈的設定檔上沒有任何變更，客服人員只會對草稿版本進行變更。
+ 反覆精簡。在多個轉彎中使用代理程式來調整映射，直到轉換後的輸出正確為止，使用同步轉換 API 在轉彎之間針對範例資料預覽結果。
### C-CDA 工作流程 （速度範本）
代理程式會編輯 Velocity 範本，定義 C-CDA 區段對應至 FHIR 資源的方式。要求它新增資源映射、變更區段的解譯方式、設定預設值或處理文件變化，並更新範本並傳回差異。您可以在發佈之前針對範例 C-CDA 文件預覽轉換。
### CSV 工作流程 (YAML 映射）
當您使用範例檔案建立 CSV 設定檔，然後調用代理程式時，它會分析檔案中的標頭、範例值和資料模式，然後提議包含下列項目的 YAML 映射組態：
+ column-to-FHIR 欄位映射、
+ 日期格式偵測和重新格式化為 FHIR 日期/時間格式，
+ 值轉譯 （例如，M → 男性、INTE → IMP)、
+ 資料表之間的主要/外部索引鍵關係、
+ 彙總規則，可將子資料表資料列摺疊為父資源上的 FHIR 陣列，
+ 代理程式對您的資料所做的任何假設和任何問題。
您可以接受、拒絕或精簡每個提議的映射，並可以要求客服人員進一步調整。代理程式會從您檔案的範例推斷映射，而不是完整資料集，因此提供代表您資料的範例，並在大規模轉換之前檢閱建議的映射。
### 代理程式接受的輸入
您可以使用自然語言輸入與客服人員通訊。某些組合包括：
+ 指示、
+ 範例來源資料 (C-CDA 區段或 CSV 結構描述），
+ 結構描述文件、
+ 先前轉換的 FHIR 驗證錯誤。
### 手動編輯
您不需要使用代理程式。您可以隨時直接編輯 Velocity 範本和 YAML 映射，並在相同的設定檔上混合手動編輯與客服人員撰寫的變更。
## 同步 （即時） 轉換和預覽
同步轉換會轉換單一輸入並立即傳回 FHIR 結果，而不是透過 Amazon S3 執行非同步任務。它有兩個用途：在您撰寫設定檔時進行測試，以及在請求/回應流程中執行小型的互動式轉換。
### 運作方式
+ 您可以針對設定檔提交一個輸入 (C-CDA 文件或一組 CSV 檔案），並在回應中收到轉換為 FHIR 套件的 FHIR 資源。
+ 此操作只能透過 REST API 使用：它不會以 AWS CLI 或 SDK 命令公開。請參閱 [存取資料轉換代理程式](data-transformation.md#data-transformation-accessing)。
+ 您可以在同步呼叫上啟用偏離偵測，方法是將 DriftDetectionEnabled 設定為 true，以便在回應中查看設定檔尚未擷取的來源元素：在映射上迭代時很有用。
### 大小限制
同步轉換接受每個請求最多 1 MB 的 C-CDA 輸入和最多 1 MB 的合併 CSV 輸入。對於較大的資料集，請使用大量轉換任務。
### 在 中預覽 AWS 管理主控台
在 中編寫設定檔時 AWS 管理主控台，同步轉換可支援即時預覽：一端是來源，另一端則是轉換後的 FHIR 輸出，而預覽會在您精簡映射時更新。在發佈之前，請使用它來確認輸出是否正確。
### 何時使用同步與大量
使用同步轉換，根據代表性文件和延遲敏感的每次請求轉換來驗證設定檔，例如即時摘要，在文件送達時轉換文件。針對大型資料集和直接擷取至 HealthLake 資料存放區，請使用大量轉換任務 （下方）。
## 大量 （非同步） 轉換任務
大量轉換任務會使用已發佈的設定檔從 Amazon S3 轉換大型資料集，在監控進度的同時以非同步方式執行。這是遷移和將資料載入 HealthLake 資料存放區的生產路徑。如需 IAM 許可設定，請參閱[此頁面](https://docs.aws.amazon.com/healthlake/latest/devguide/getting-started-setting-up.html)。
### 運作方式
+ 將任務指向來源檔案的 Amazon S3 字首，選擇已發佈的設定檔，然後選擇輸出目的地。任務會掃描輸入、轉換每個檔案 (C-CDA) 或一組資料列 (CSV)，然後寫入結果。
+ 沒有要佈建的基礎設施：任務會自動擴展。
### 輸出模式
+ 獨立：將轉換後的 FHIR 寫入 Amazon S3 位置。使用 StartDataTransformationJob API。
+ 複合 （轉換和擷取）：在單一步驟中轉換來源檔案，並將產生的 FHIR 資源直接擷取到 HealthLake 資料存放區，以便立即查詢資料。使用 StartFHIRImportJob API 搭配 ProfileId、InputFormat 和選用的 DriftDetectionEnabled 參數。資料存放區必須處於 ACTIVE 狀態。如需完整範例，請參閱步驟 7：轉換並擷取至 HealthLake 資料存放區。
### 容錯處理
系統會略過並記錄格式不正確的輸入，而不是使批次失敗，因此單一錯誤檔案永遠不會停止大型任務。失敗的輸入會寫入 JSON 錯誤檔案，其中包含輸入檔案路徑和錯誤訊息，因此您可以檢閱並重新處理。
### 輸出配置
服務會使用任務 ID，在您的輸出 Amazon S3 URI 下建立任務範圍資料夾。在該資料夾中：
+ converted/：FHIR NDJSON 輸出檔案 （每個輸入檔案一個，例如 converted/patient-record.ndjson)。
+ ERROR/：失敗輸入的錯誤詳細資訊 （具有 inputFile 和 errorMessage 欄位的 JSON 檔案，例如 ERROR/bad-file.json)。
+ Manifest.json：具有彙總指標的任務摘要 （掃描、轉換、失敗、產生資源的檔案）。
+ jobLevelDriftResult.json:如果啟用偏離偵測，則為任務的彙總偏離報告。
+ driftDetectionPerFileResults/：針對已啟用偏離偵測的 C-CDA 任務，每個檔案偏離報告 （例如 driftDetectionPerFileResults/patient-record\_driftMetrics.json)，因此您可以檢查個別來源檔案的涵蓋範圍，而不只是任務層級彙總。
### 監控
透過任務詳細資訊頁面或 DescribeDataTransformationJob API 追蹤執行 AWS 管理主控台 中的任務：狀態、處理的檔案 (CSV 的資料列）、產生的資源和失敗。Amazon CloudWatch 也提供任務指標和日誌。
## 驗證
資料轉換代理程式會在轉換生命週期的多個點進行驗證，因此問題會在轉換失敗或不合規的輸出發生之前被攔截。
+ 來源驗證：檢查 C-CDA 輸入是否格式正確且符合 C-CDA 規格。錯誤包括位置詳細資訊和修補指引，因此您可以在執行大型任務之前修正來源問題。ValidateSource操作可透過 REST API 預先篩選輸入。
+ 範本/映射驗證： 會獨立於任何資料驗證設定檔的 Velocity 範本 (C-CDA) 或 YAML 映射 (CSV)，因此您可以在發佈或執行任務之前確認轉換邏輯格式正確。
+ 輸出 FHIR 驗證：檢查產生的資源是否符合 FHIR R4，以便下游 FHIR APIs 和資料存放區接受輸出。
總而言之，由於可避免的原因，任務失敗的頻率會降低：來源驗證會擷取錯誤的輸入、映射驗證會擷取錯誤的邏輯，而輸出驗證會確認結果符合標準。
## OID-to-URI映射
C-CDA 文件使用 OIDs（物件識別符） 識別程式碼系統：舊版數值識別符，例如 `2.16.840.1.113883.6.1`(LOINC)。FHIR 預期現代系統 URIs例如 `http://loinc.org`。如果透過未映射傳輸 OIDs，則產生的系統值無法互通，下游 FHIR 工具也無法解析程式碼。資料轉換代理程式會在轉換期間映射它們。
+ **預先建置的映射**：會自動套用常見醫療保健 OIDs映射 （例如 LOINC、SNOMED CT、ICD-10、RxNorm)，無需設定。
+ **自訂映射**：為來源特定的程式碼系統新增自己的 OID-to-URI 映射，以便專屬或本機系統正確解析。
這適用於 C-CDA 來源，其中 OIDs 是識別程式碼系統的原生方式。
## 證明
受監管的醫療保健工作流程需要回答「此資料來自何處，如何產生？」 任何資源。在任務上啟用來源時，Data Transformation Agent 會為每個轉換產生 FHIR Provenance 資源，為每個輸出資源提供可查詢的完整歷程記錄回其來源。
### 原始伺服器鏈
Provenance → DocumentReference → 來源檔案。Provenance 資源參考 DocumentReference，記錄來源檔案的 Amazon S3 URI 和 SHA-1 檢查總和。檢查總和可讓您證明輸出衍生自特定、未變更的來源檔案。如果需要該資訊，也會提供代表 AWS HealthLake Data Transformation 做為實體的裝置資源。
### 記錄層級定位器
Provenance 不僅會解析來源檔案，還會解析其中的確切位置，而且定位器會因來源格式而有所不同：
+ **C-CDA**：指向資源衍生來源元素的 XPath。
+ **CSV**：來源記錄的資料表名稱、主索引鍵和資料列編號。
### 擷取的欄位
每個 Provenance 資源都會記錄來源檔案 URI 和檢查總和、用於轉換的設定檔版本、時間戳記和記錄層級定位器。
### 一致性和使用
Provenance 資源符合美國 Core Provenance 設定檔，因此它們與美國 Core-aware 工具互通。當您需要合規的可稽核性，或需要將可疑的輸出資源追蹤回產生它的確切來源元素時，請啟用來源。Provenance 預設為啟用；將 ProvenanceEnabled 設定為 false 以停用它。
## 漂移偵測
轉換可以在無提示地捨棄設定檔尚未映射的來源資料時成功。該間隙的漂移偵測表面。這是一個報告：啟用時，它會比較來源包含的內容與設定檔實際產生的內容，並記錄剩餘的內容。
### 報告包含的內容
+ 轉換的整體涵蓋率。
+ 未映射來源區段和元素的排名清單，因此您可以優先考慮影響程度最高的差距。
+ 未產生的任何預期資源。
+ 完整可追溯回來源檔案和元素位置 (C-CDA 的檔案名稱和 OID，CSV 的資料列）。
### 如何使用偏離偵測
漂移偵測可在兩種轉換模式中使用，因此無論您是在單一檔案上反覆運算或驗證完整的資料集，都可以使用它：
+ 同步 （即時）：在 TransformData 請求上將 DriftDetectionEnabled 設定為 true，以在單一檔案上執行偏離偵測，並在 API 回應中取得結果。這是在您撰寫描述檔時檢查涵蓋範圍的最快方法：轉換一個代表性文件、查看描述檔遺漏的內容、精簡映射，然後再試一次。
+ 大量 （非同步）：在轉換任務上啟用偏離偵測，以測量整個資料集的涵蓋範圍。報告會在任務的 Amazon S3 輸出位置中寫入為 jobLevelDriftResult.json 對於 C-CDA 任務，每個檔案偏離報告也會寫入 driftDetectionPerFileResults/ 資料夾，因此您可以精確找出個別來源檔案中的涵蓋範圍差距。
## MCP 存取
模型內容通訊協定 (MCP) 將資料轉換代理程式公開給以 IDE 為基礎的 AI 代理程式作為可呼叫工具，因此開發人員可以從其 IDE 中的助理編寫設定檔、執行轉換和調查失敗： 而無需切換到 AWS 管理主控台。
+ 設定檔和任務管理 APIs：所有資料轉換代理程式設定檔和任務管理 APIs都可以做為 MCP 工具使用，因此您可以從任何 MCP 相容用戶端建立、編輯、發佈和執行任務。
+ 任何 MCP 用戶端：適用於與 MCP 相容的 IDEs 和助理，包括 Kiro 和 Cursor。
+ 持久性工作階段： 支援多迴轉工作階段，因此偵錯或編寫對話會保留內容。
**注意**
同步轉換操作 (TransformData) 和來源驗證 (ValidateSource) 僅 REST，可能不會顯示為 MCP 工具。您的代理程式可以代表您建構和執行 REST 呼叫：請參閱步驟 3：使用請求格式的同步轉換進行測試。
由於 MCP 與設定檔 AWS CLI 和任務操作的 和 SDKs 共用相同的 API 表面，因此在 IDE 中工作和處理程式碼或 之間，這些工作流程沒有能力差距 AWS 管理主控台。[MCP 入門](data-transformation-getting-started-mcp.md) 如需設定和範例工作流程，請參閱 。