本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # HealthLake 的 FHIR R4 `$davinci-data-export`操作 `$davinci-data-export` 操作是一種非同步 FHIR 操作，可用來從中匯出醫療保健資料 AWS HealthLake。此操作支援多種匯出類型，包括成員屬性 (ATR)、PDex 提供者存取、Payer-to-Payer和成員存取 APIs。它是標準 FHIR `$export`操作的特殊版本，旨在符合 DaVinci 實作指南的要求。 ## 主要功能 + *非同步處理*：遵循標準 FHIR 非同步請求模式 + *群組層級匯出*：匯出特定群組資源中成員的資料 + *多種匯出類型*：支援 ATR （成員屬性）、PDex 提供者存取、Payer-to-Payer和成員存取 APIs + *全方位設定檔支援*：包括美國核心、CARIN 藍色按鈕和 PDex 設定檔 + *彈性篩選*：支援依病患、資源類型和時間範圍進行篩選 + *NDJSON 輸出*：以換行分隔 JSON 格式提供資料 ## 操作端點 ``` GET [base]/Group/[id]/$davinci-data-export POST [base]/Group/[id]/$davinci-data-export ``` ## 請求參數 | 參數 | 基數 | Description | | --- | --- | --- | | patient | 0..\* | 要匯出其資料的特定成員。省略時，會匯出群組中的所有成員。 | | \_type | 0..1 | 要匯出的以逗號分隔的 FHIR 資源類型清單。省略時，會包含指定匯出類型的所有支援資源類型。對於 ATR 匯出，這預設為 8 個屬性資源類型。對於 PDex 匯出，這包括所有屬性資源類型，以及美國核心、CARIN 藍色按鈕和 PDex 設定檔中的臨床和宣告資源類型。 | | \_since | 0..1 | 僅包含在此日期和時間之後更新的資源。 | | \_until | 0..1 | 僅包含在此日期和時間之前更新的資源。 | | exportType | 0..1 | 要執行的匯出類型。有效值：hl7.fhir.us.davinci-atr、hl7.fhir.us.davinci-pdex、hl7.fhir.us.davinci-pdex.p2p、hl7.fhir.us.davinci-pdex.member。預設：hl7.fhir.us.davinci-atr。 | | \_includeEOB2xWoFinancial | 0..1 | 指定是否要在移除財務資料時包含 CARIN BB 2.x ExplanationOfBenefit 資源。預設：false。 | | \_security | 0..\* | 依meta.security編碼值篩選匯出的資源。使用 system\|code 格式 （管道字元必須以 URL 編碼為 %7C)。提供多個值時，資源必須符合所有值 (AND 語意）。使用 system\|（追蹤管道、無程式碼） 來比對來自指定系統的任何程式碼。 | | \_tag | 0..\* | 依meta.tag編碼值篩選匯出的資源。使用與 相同的system\|code格式和 AND 語意\_security。同時指定 \_tag \_security和 時，資源必須符合兩個篩選條件。 | ### 支援的資源類型 支援的資源類型取決於您指定的匯出類型。對於 ATR 匯出，支援下列資源類型： + `Group` + `Patient` + `Coverage` + `RelatedPerson` + `Practitioner` + `PractitionerRole` + `Organization` + `Location` 對於 PDex 匯出 (Provider Access、Payer-to-Payer 和 Member Access)，除了上述類型之外，還支援所有臨床和宣告資源類型。如需支援資源類型的完整清單，請參閱[美國核心實作指南 (STU 6.1)](https://hl7.org/fhir/us/core/STU6.1/)、[CARIN 藍色按鈕實作指南](https://hl7.org/fhir/us/carin-bb/)，以及 [Da Vinci 預先授權支援實作指南](https://hl7.org/fhir/us/davinci-pas/)。 ## 匯出類型 `$davinci-data-export` 操作支援下列匯出類型。您可以使用 `exportType` 參數指定匯出類型。 | 匯出類型 | 用途 | 資料範圍 | 時間限制 | | --- | --- | --- | --- | | hl7.fhir.us.davinci-atr | 成員屬性清單 | 屬性相關資源 | 無 | | hl7.fhir.us.davinci-pdex | 提供者存取 API | 屬性患者的臨床和宣告資料 | 5 年 | | hl7.fhir.us.davinci-pdex.p2p | Payer-to-Payer交換 | 保險轉換的歷史成員資料 | 5 年 | | hl7.fhir.us.davinci-pdex.member | 成員存取 API | 成員自己的運作狀態資料 | 5 年 | **注意** 對於 PDex 匯出，5 年時間限制不適用於 ATR 資源類型 (`Group`、`Patient`、`Coverage`、`RelatedPerson`、`Practitioner`、`PractitionerRole``Organization`、)`Location`。無論年齡為何，一律包含這些資源。 ### ATR (hl7.fhir.us：//.davinci-atr) 使用 ATR 匯出類型，您可以匯出成員屬性清單資料。使用此匯出類型來擷取群組內成員的屬性相關資源。如需詳細資訊，請參閱 [Da Vinci ATR 匯出操作](https://build.fhir.org/ig/HL7/davinci-atr/OperationDefinition-davinci-data-export.html)。 支援的資源類型 `Group`, `Patient`, `Coverage`, `RelatedPerson`, `Practitioner`, `PractitionerRole`, `Organization`, `Location` 時間篩選 不會套用時間篩選。無論日期為何，都會匯出所有相符的資源。 ### PDex 匯出類型 所有 PDex 匯出類型共用相同的支援設定檔和篩選邏輯。如需詳細資訊，請參閱 [Da Vinci PDex 提供者存取 API](https://build.fhir.org/ig/HL7/davinci-epdx/provider-access-api.html)。支援下列設定檔： + 美國核心 3.1.1、6.1.0 和 7.0.0 + PDex 事前授權 （不支援成員存取） + CARIN BB 2.x 基礎描述檔：住院機構、門診機構、專業NonClinician、口頭、藥學 對於 PDex 匯出，會自動為群組中的每個病患探索臨床和宣告資源。您不需要在群組資源中明確參考這些資源。操作會搜尋屬於歸因病患的所有病患室資源 `Condition` `Coverage`（例如 `Observation`、`MedicationRequest`、、`RelatedPerson`、 和 `ExplanationOfBenefit`)。只有 `Patient`、 `Group`和非non-patient-compartment ATR 類型 (`Practitioner`、`PractitionerRole`、`Organization`、`Location`) 需要群組中的明確參考。 提供者存取 (`hl7.fhir.us.davinci-pdex`) 讓網路內提供者擷取歸因患者的患者資料。 Payer-to-Payer(`hl7.fhir.us.davinci-pdex.p2p`) 當患者變更保險時，啟用付款人之間的資料交換。 成員存取 (`hl7.fhir.us.davinci-pdex.member`) 可讓成員存取自己的運作狀態資料。此匯出類型可能包含宣告資源中的財務資料。 ## 設定檔支援和包含邏輯 對於 PDex 匯出， `$davinci-data-export`操作會使用 `meta.profile`元素中的設定檔宣告來決定匯出中要包含哪些資源。 ### ExplanationOfBenefit 資源處理 `ExplanationOfBenefit` (EOB) 資源會根據其`meta.profile`宣告從 PDex 匯出中包含或排除： + 具有 CARIN BB 1.x 設定檔的 ExplanationOfBenefit 資源會從匯出中排除。 + 匯出會排除未設定 ExplanationOfBenefit 資源。 `meta.profile` + 一律包含具有 CARIN BB 2.x Basis 描述檔的 ExplanationOfBenefit 資源。 + 根據預設，會排除具有包含財務資料的 CARIN BB 2.x 設定檔的 ExplanationOfBenefit 資源。設定 `_includeEOB2xWoFinancial=true` 時，它們會包含在財務資料分割中，並將資源轉換為對應的基礎設定檔。 + 一律包含具有 PDex 預先授權設定檔的 ExplanationOfBenefit 資源。 ### 財務資料轉換 當您設定 時`_includeEOB2xWoFinancial=true`，此操作會透過移除財務資料，將 [CARIN BB 2.x](https://hl7.org/fhir/us/carin-bb/) ExplanationOfBenefit 資源轉換為其對應的 Basis 設定檔。例如，`C4BB ExplanationOfBenefit Oral`資源會轉換為 `C4BB ExplanationOfBenefit Oral Basis`，這會根據 FHIR 規格從記錄分割財務資料。 下列財務資料元素會在轉換期間移除： + `total` 元素上的所有切片 + 具有`amounttype`配量的所有`adjudication`元素 + 包含金額資訊的所有`item.adjudication`元素 此操作也會在轉換期間更新設定檔中繼資料： + `meta.profile` 已更新為 Basis 設定檔正式 URL + 版本已更新為 CARIN BB 2.x Basis 版本 + 不會修改資料存放區中的現有資源 + 匯出的資源不會保留回資料存放區 ### 設定檔偵測規則 操作使用下列規則來偵測和驗證設定檔： + 版本偵測是以`meta.profile`正式 URLs為基礎 + 如果任何宣告的設定檔符合匯出條件，則會包含資源 + 設定檔驗證會在匯出處理期間進行 ## PDex 匯出的五年時間篩選 對於所有 PDex 匯出類型，HealthLake 會根據資源上次更新的時間套用 5 年的時間篩選條件。暫時篩選條件適用於所有資源，但下列核心屬性資源類型除外，無論使用期限為何，一律會匯出這些資源： + `Patient` + `Coverage` + `Organization` + `Practitioner` + `PractitionerRole` + `RelatedPerson` + `Location` + `Group` 這些管理和人口統計資源是豁免的，因為它們提供匯出資料的基本內容。ATR 匯出不受任何時間篩選的限制。 ## 請求範例 下列範例示範如何開始不同匯出類型的匯出任務。 *ATR 匯出* ``` GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Group,Patient,Coverage,Practitioner,Organization&exportType=hl7.fhir.us.davinci-atr POST https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Group,Patient,Coverage,Practitioner,Organization&exportType=hl7.fhir.us.davinci-atr Content-Type: application/json { "DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role", "JobName": "attribution-export-job", "OutputDataConfig": { "S3Configuration": { "S3Uri": "s3://your-export-bucket/EXPORT-JOB", "KmsKeyId": "arn:aws:kms:region:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab" } } } ``` *使用 ExplanationOfBenefit 財務資料移除來匯出供應商存取* ``` GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Observation,Condition,MedicationRequest,ExplanationOfBenefit&exportType=hl7.fhir.us.davinci-pdex&_includeEOB2xWoFinancial=true ``` *Payer-to-Payer匯出* ``` GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Coverage,ExplanationOfBenefit,Condition,Procedure&exportType=hl7.fhir.us.davinci-pdex.p2p&_includeEOB2xWoFinancial=true ``` *特定病患的成員存取匯出* ``` GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Observation,Condition,ExplanationOfBenefit,MedicationRequest&exportType=hl7.fhir.us.davinci-pdex.member&patient=Patient/example-patient-id ``` ## 回應範例 ``` { "datastoreId": "eaee622d8406b41eb86c0f4741201ff9", "jobStatus": "SUBMITTED", "jobId": "48d7b91dae4a64d00d54b70862f33f61" } ``` ## 資源關係 操作會根據其在成員屬性清單中的關係匯出資源： ``` Group (Attribution List) ├── Patient (Members) ├── Coverage → RelatedPerson (Subscribers) ├── Practitioner (Attributed Providers) ├── PractitionerRole → Location └── Organization (Attributed Providers) ``` **注意** 上述資源關係圖適用於 ATR 匯出。對於 PDex 匯出，臨床和宣告資源會透過病患搜尋自動探索，且不需要群組資源中的明確參考。 ### 資源來源 | 資源 | 來源位置 | Description | | --- | --- | --- | | Patient | Group.member.entity | 屬於屬性清單成員的患者 | | Coverage | Group.member.extension:coverageReference | 導致病患成員資格的涵蓋範圍 | | Organization | Group.member.extension:attributedProvider | 患者所屬的組織 | | Practitioner | Group.member.extension:attributedProvider | 患者所屬的個別從業人員 | | PractitionerRole | Group.member.extension:attributedProvider | 患者所屬的從業人員角色 | | RelatedPerson | Coverage.subscriber | 涵蓋範圍的訂閱者 | | Location | PractitionerRole.location | 與從業人員角色相關聯的位置 | | Group | 輸入端點 | 屬性清單本身 | ## 任務管理 檢查任務狀態 `GET [base]/export/[job-id]` 取消任務 `DELETE [base]/export/[job-id]` ### 任務生命週期 + `SUBMITTED` - 已收到任務並排入佇列 + `IN_PROGRESS` - 任務正在主動處理 + `COMPLETED` - 任務成功完成，檔案可供下載 + `FAILED` - 任務發生錯誤 ## 輸出格式 + *檔案格式*：NDJSON （換行分隔 JSON) + *檔案組織*：每個資源類型的個別檔案 + *副檔名*：.ndjson + *位置*：指定的 S3 儲存貯體和路徑 ## 錯誤處理 針對下列情況， 操作會傳回具有 OperationOutcome 的 HTTP 400 錯誤請求： 授權錯誤 在 中指定的 IAM 角色`DataAccessRoleArn`沒有足夠的許可來執行匯出操作。如需所需 S3 和 KMS 許可的完整清單，請參閱[設定匯出任務的許可](getting-started-setting-up.md#setting-up-export-permissions)。 參數驗證錯誤 + `patient` 參數的格式不是 `Patient/id,Patient/id,...` + 一或多個病患參考無效或不屬於指定的群組 + `exportType` 參數值不是支援的匯出類型 + `_type` 參數包含指定匯出類型不支援的資源類型 + `_type` 參數缺少`hl7.fhir.us.davinci-atr`匯出類型所需的資源類型 (`Group`、`Patient`、`Coverage`) + `_includeEOB2xWoFinancial` 參數值不是有效的布林值 資源驗證錯誤 + 指定的群組資源不存在於資料存放區中 + 指定的群組資源沒有成員 + 一或多個群組成員參考資料存放區中不存在的患者資源 ## 安全性和授權 + 適用標準 FHIR 授權機制 + 資料存取角色必須具有 S3 和 KMS 操作所需的 IAM 許可。如需所需許可的完整清單，請參閱[設定匯出任務的許可](getting-started-setting-up.md#setting-up-export-permissions)。 ## 最佳實務 + *資源類型選擇*：僅請求所需的資源類型，以將匯出大小和處理時間降至最低 + *以時間為基礎的篩選*：使用 `_since` 參數進行增量匯出 + *病患篩選*：當您只需要特定成員的資料時，請使用 `patient` 參數 + *任務監控*：定期檢查大型匯出的任務狀態 + *錯誤處理*：針對失敗的任務實作適當的重試邏輯 + *暫時篩選條件感知*：對於 PDex 匯出，請在選取資源類型時考慮 5 年暫時篩選條件 + *財務資料移除*：當您需要沒有財務資訊的宣告資料`_includeEOB2xWoFinancial=true`時使用 + *設定檔管理*：確保資源具有適當的設定檔宣告、在擷取之前針對目標設定檔進行驗證，並使用設定檔版本控制來控制匯出行為 ## 限制 + 參數中最多可指定 500 名病患 `patient` + 匯出僅限於群組層級操作 + 僅支援每個匯出類型的預先定義資源類型集 + 輸出一律為 NDJSON 格式 + PDex 匯出僅限於 5 年的臨床和宣告資料 + 財務資料轉換僅適用於 CARIN BB 2.x ExplanationOfBenefit 設定檔 ## 其他資源 + [Da Vinci 成員屬性清單 IG](https://build.fhir.org/ig/HL7/davinci-atr/) + [Da Vinci 付款人資料交換 IG](https://hl7.org/fhir/us/davinci-pdex/) + [CARIN 消費者導向付款人資料交換 IG](https://build.fhir.org/ig/HL7/carin-bb/) + [美國核心實作指南](https://www.hl7.org/fhir/us/core/) + [FHIR 大量資料存取規格](https://hl7.org/fhir/uv/bulkdata/)