匯入 FHIR 資料

您可以使用 import 作業將 FHIR® 資料匯入高效能 FHIR 伺服器。

匯入作業模式

此 import 作業支援兩種模式：初始和累加。 每個模式都有不同的功能和使用案例。

初始模式

• 適用於將 FHIR 資源載入空的 FHIR 伺服器。

• 封鎖 API 對 FHIR 伺服器的寫入操作。

累加模式

• 已針對定期將數據載入 FHIR 伺服器優化，且不會封鎖透過 API 的寫入。

• 可讓您在資源 JSON 中存在資源元數據時，從資源元數據載入 lastUpdated 和 versionId 值。

• 可讓您以非順序版本的順序載入資源。 非循序導入資源的注意事項

  • 如果匯入檔案中未指定 version 和 lastUpdated 欄位的值，則無法保證會匯入 FHIR 服務中的所有資源。
  • 如果匯入檔案具有重複 version 的資源和 lastUpdated 域值，則 FHIR 服務中只會隨機內嵌一個資源。
  • 在平行執行期間，如果多個資源分享相同的資源標識符，則隨機只匯入其中一個資源。

下表顯示匯入模式之間的差異。

领域	初始模式	累加模式
能力	將數據初始載入 FHIR 服務	將數據持續匯入 FHIR 服務（增量或近乎即時）。
並行 API 呼叫	封鎖並行寫入作業	在 FHIR 伺服器上執行 API CRUD 作業時，可以同時內嵌數據。
擷取已建立版本的資源	不支援	可在維護資源歷程記錄的同時，在單一批次中擷取多個版本的 FHIR 資源。
保留 lastUpdated 欄位值	不支援	在導入過程中，保留 FHIR 資源中的 lastUpdated 欄位值。
帳單管理	不會產生任何費用	根據已成功擷取的資源產生費用。 依照 API 定價產生收費。

效能考量

若要使用 import 作業達到最佳效能，請考慮下列因素。

• 使用大型檔案進行匯入。 匯入的最佳 NDJSON 檔案大小是 >=50 MB（或 >=20 K 資源，沒有上限）。 請考慮將較小的檔案結合在一起。

• 將 FHIR 資源文件匯入為單一批次。 為了獲得最佳效能，請匯入您想要在一個 import 作業中內嵌在 FHIR 伺服器中的所有 FHIR 資源檔。 在一個作業中匯入所有檔案，可減少建立和管理多個匯入作業的額外負荷。 最佳方式是，單一匯入中檔案的大小總計應該是大（>=100 GB 或 >=100M 資源，沒有上限）。

• 限制平行匯入作業的數目。 您可以同時執行多個 import 作業，但這可能會影響 import 操作的整體吞吐量。

執行匯入作業

先決條件

• 若要使用 import 作業，您需要擁有 FHIR 伺服器上的 FHIR 資料匯入者 角色。

• 設定 FHIR 伺服器。 FHIR 數據必須儲存在 Azure Blob 存放區上 FHIR NDJSON 格式的資源特定檔案中。 如需詳細資訊，請參閱 設定匯入設定。

• 數據必須位於與 FHIR 服務相同的租戶。

• 若要取得存取令牌，請參閱 存取令牌

進行通話

使用下列請求標頭和正文進行 POST 到 <<FHIR service base URL>>/$import 的呼叫。

請求標頭

Prefer:respond-async
Content-Type:application/fhir+json

身體

下表描述主體參數和輸入。

參數名稱	說明	基數	接受的值
inputFormat	表示數據來源格式名稱的字串。 僅支援 FHIR NDJSON 檔案。	1..1	application/fhir+ndjson
mode	匯入模式值。	1..1	針對初始模式匯入，請使用 InitialLoad 模式值。 針對累加模式匯入，請使用 IncrementalLoad 模式值。 如果您未提供模式值，預設 IncrementalLoad 會使用模式值。
allowNegativeVersions	允許 FHIR 伺服器為具有明確 lastUpdated 值的資源記錄指派負版本，而且當輸入不符合存放區中現有正版本連續空間時，未指定任何版本。	0..1	若要啟用此功能，請傳遞 true。 默認為 false。
errorContainerName	字串，表示將記錄匯入程式期間發生錯誤之容器的名稱。	0..1	錯誤記錄的自定義容器名稱。 名稱應介於 3-63 個字元之間，且只包含小寫字母、數位和連字元。 如果未指定，則會使用預設容器。
input	輸入檔案的詳細數據。	1..*	具有下表所述三個部分的 JSON 陣列。

輸入元件名稱	說明	基數	接受的值
type	輸入檔的資源類型。	0..1	符合輸入檔的有效 FHIR 資源類型 。 此欄位為選擇性欄位。
url	輸入檔案的 Azure 記憶體 URL。	1..1	輸入檔的 URL 值。 無法修改值。
etag	Azure 儲存體中輸入檔案的 ETag。 用來確認註冊之後 import 檔案內容未變更。	0..1	輸入檔的 ETag 值。

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputFormat",
            "valueString": "application/fhir+ndjson"
        },
        {
            "name": "mode",
            "valueString": "<Use "InitialLoad" for initial mode import / Use "IncrementalLoad" for incremental mode import>"
        }, 
        {
            "name": "allowNegativeVersions",
            "valueBoolean": true
        },
        {
            "name": "errorContainerName",
            "valueString": "import-error-logs"
        },
        {
            "name": "input",
            "part": [
                { 
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/filename.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "\"0x8D92A7342657F4F\""
                }
            ]
        }
    ]
}

檢查匯入狀態

啟動import作業後，會在回應標頭中傳回一個空白回應本文，其中包含callback連結與Content-location狀態代碼。 callback儲存連結以檢查匯入狀態。

作業的 import 註冊會實作為等冪呼叫。 相同的註冊承載會產生相同的註冊，這會影響重新處理具有相同名稱的檔案的能力。 避免就地更新檔案。 相反地，建議您對更新的數據使用不同的檔名。 或者，如果同一個檔名的就地更新是不可避免的，請在註冊承載中新增ETag。

若要檢查匯入狀態，請使用 方法GET對上一個步驟中傳回的連結進行 REST 呼叫callback。

使用此數據表解譯回應。

回應碼	回應主體	說明
202 Accepted		作業仍在執行中。
200 OK	The response body doesn't contain any error.url entry	已成功匯入所有資源。
200 OK	The response body contains some error.url entry	匯入某些資源時發生錯誤。 如需詳細資訊，請參閱 位於的 error.url檔案。 其餘資源已順利匯入。
Other		發生嚴重錯誤，且作業已停止。 已成功匯入的資源不會回復。

下表描述回應主體中的重要欄位：

領域	說明
transactionTime	大量 import 作業的開始時間。
output.count	已成功匯入的資源計數。
error.count	因為發生錯誤而未匯入的資源計數。
error.url	包含錯誤詳細資料的檔案URL。 每個 error.url 實例都是輸入 URL 的唯一實例。

{
    "transactionTime": "2021-07-16T06:46:52.3873388+00:00",
    "request": "https://importperf.azurewebsites.net/$Import",
    "output": [
        {
            "type": <null in case type parameter in not populated in request. If provided, resource name will be added>,
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/filename.ndjson"
        }
    ],
    "error": [
        { 
        "type": "OperationOutcome",
        "count": 51,
        "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson",
        "url": "https://example.blob.core.windows.net/fhirlogs/CarePlan06b88c6933a34c7c83cb18b7dd6ae3d8.ndjson"
        }
    ]
}

匯入虛刪除的資源

增量模式匯入支援匯入軟刪除的資源。 您必須使用擴充功能在 FHIR 服務中匯入虛刪除的資源。

將擴充套件新增至資源，以通知 FHIR 服務該資源已軟刪除。

{"resourceType": "Patient", "id": "example10", "meta": { "lastUpdated": "2023-10-27T04:00:00.000Z", "versionId": 4, "extension": [ { "url": "http://azurehealthcareapis.com/data-extensions/deleted-state", "valueString": "soft-deleted" } ] } }

import作業成功完成之後，請在資源上執行歷程記錄搜尋，以驗證軟刪除的資源。 如果您知道已刪除資源的識別碼，請使用下列範例中的URL模式。

<FHIR_URL>/<resource-type>/<resource-id>/_history

如果您不知道資源的標識碼，請對資源類型執行歷程記錄搜尋。

<FHIR_URL>/<resource-type>/_history

匯入作業疑難排解

以下是作業失敗時 import 所發生的錯誤訊息，以及解決問題的建議動作。

200 確定，但回應中URL發生錯誤

操作 import 成功並返回 200 OK。 不過，error.url 存在於回應的本文中。 位於位置的 error.url 檔案包含類似下列範例的 JSON 片段。

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "details": {
                "text": "Given conditional reference '{0}' doesn't resolve to a resource."
            },
            "diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
        }
    ]
}

原因：NDJSON 檔案包含資源，其中的條件式參考不受 import 支援。

解決方案：將 NDJSON 檔案內的條件式參考修改為一般的參考。

400 錯誤的請求

操作 import 失敗並返回 400 Bad Request。 回應正文包含診斷內容

匯入作業失敗，原因如下：已知沒有這類主機。 （example.blob.core.windows.net:443） 解決方案：確認 Azure 記憶體的連結正確無誤。 檢查網路和防火牆設定以確保 FHIR 伺服器可以存取儲存。 如果您的服務位於虛擬網路中，請確保儲存位於相同虛擬網路或位於與 FHIR 服務的虛擬網路對等的虛擬網路中。

SearchParameter 資源無法透過匯入進行處理解決方案：當透過匯入程序引入搜尋參數資源時，匯入操作會傳回 HTTP 400 錯誤。 此變更旨在防止搜尋參數在透過匯入操作攝取時處於無效狀態。

403 禁止存取

操作 import 失敗並返回 403 Forbidden。 回應正文包含診斷內容。

匯入作業失敗，原因如下：伺服器無法驗證要求。 請確保授權標頭的值已正確格式化，包括簽名。 原因：FHIR 服務使用託管身分進行來源儲存驗證。 此錯誤代表遺漏角色指派，或角色指派不正確。 解決方案：將儲存 Blob 資料貢獻者角色指派給 FHIR 伺服器。 如需詳細資訊，請參閱 指派 Azure 角色。

500 內部伺服器錯誤

操作 import 失敗並返回 500 Internal Server Error。 回應正文包含診斷內容

匯入作業失敗，原因如下：資料庫 『****』 已達到其大小配額。 資料分割或刪除資料、卸除索引，或參閱可能解決方式的文件。

原因：達到 FHIR 服務的儲存體限制。

解決方案：縮減資料大小，或考慮採用適用於 FHIR 的 Azure API，其儲存空間限制較大。

423 鎖定

行為：import 操作失敗並返回 423 Locked 。 回應本文包含此內容：

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Service is locked for initial import mode."
        }
    ]
}

原因：FHIR 服務配置為初始導入模式，阻止了其他操作。

解決方案：關閉FHIR服務的初始導入模式，或選擇增量模式。

局限性

• 每個 import 作業允許的檔案數目上限為 10,000。
• FHIR 伺服器中攝取的具有相同 lastUpdated 欄位值 (最多毫秒) 的檔案數量不能超過 10,000。
• SearchParameter 資源類型不支援導入操作。
• 導入操作不支援資源中的條件引用。

後續步驟

將數據轉換成 FHIR

設定匯出設定並設定記憶體帳戶

將數據複製到 Azure Synapse Analytics

備註

FHIR® 是 HL7 的註冊商標，在 HL7 的許可下使用。