匯入 FHIR 資料

import 作業可讓您將 FHIR® 資料內嵌至 FHIR 伺服器且輸送量高。

匯入作業模式

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

初始模式

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

• 僅支援 create 作業，亦可封鎖 API 寫入至 FHIR 伺服器 (如啟用)。

累加模式

• 最適合用於將資料定期載入 FHIR 伺服器，且不封鎖透過 API 執行的寫入。

• 讓您載入資源中繼資料的 lastUpdated 和 versionId (如存在於資源 JSON 內)。

  • 若匯入檔案並未指定 version 和 lastUpdated 欄位的值，則不保證能將資源匯入 FHIR 服務。

  • 若匯入檔案的資源 version 和 lastUpdated 欄位值有重複，則只會隨機選擇一個資源內嵌至 FHIR 服務。

• 可讓您內嵌虛刪除資源。 從適用於 FHIR 的 Azure API 遷移至 Azure 健康資料服務的 FHIR 服務時，此功能非常實用。

重要

import 作業不支援資源的條件式參考。

此外，若多個資源共用相同資源識別碼，則只會隨機匯入其中一個資源。 資源共用相同資源識別碼會記錄錯誤。

效能考量

為了實現 import 作業的最佳效能，請將以下因素納入考量：

• 使用大型檔案進行匯入。 單次 import 作業的檔案大小應超過 200 MB。 較小的檔案可能會造成匯入速度較慢。

• 在單一批次匯入 FHIR 資源檔案。 為了實現最佳效能，請以單次 import 作業，將您希望 FHIR 伺服器內嵌的所有 FHIR 資源檔案一次匯入。 在單一作業匯入所有檔案，可減少多個匯入作業建立與管理的負擔。

• 限制平行匯入作業的數量。 您可同時執行多個 import 作業，但這可能會影響匯入作業的整體輸送量。 FHIR 伺服器最多可平行處理 import 個作業。 若超出此上限，則 FHIR 伺服器可能會進行節流，或拒絕您的要求。

執行匯入作業

必要條件

• 您的 FHIR 伺服器需要 FHIR 資料匯入工具角色，才能使用 import 作業。

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

• 檔案內的所有資源都必須屬於相同類型。 每個資源類型可以有多個檔案。

• 資料必須來自 FHIR 服務的同一個租用戶。

• 單次 import 作業的檔案數量上限為 10,000。

呼叫 $import

向 <<FHIR service base URL>>/$import 進行 POST 呼叫，同時呈現要求標題和本文。

要求標頭

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

本文

參數名稱	描述	卡。	接受的值
inputFormat	表示資料來源格式名稱的字串。 僅支援 FHIR NDJSON 檔案。	1..1	application/fhir+ndjson
mode	匯入模式值	1..1	若是初始模式 import，請使用 InitialLoad 模式值。 若是增量模式 import，請使用 IncrementalLoad 模式值。 若未提供模式值，則預設會使用 `IncrementalLoad` 模式值。
input	輸入檔案的詳細資料。	1..*	包含三個元素的 JSON 陣列，如下表所示。

輸入元素名稱	描述	卡。	接受的值
type	輸入檔案的資源類型	1..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": "input",
            "part": [
                {
                    "name": "type",
                    "valueString": "Patient"
                },
                {
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/Patient.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "0x8D92A7342657F4F"
                }
            ]
        },
        {
            "name": "input",
            "part": [
                {
                    "name": "type",
                    "valueString": "CarePlan"
                },
                {
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/CarePlan.ndjson"
                }
            ]
        }
    ]
}

檢查 $import 狀態

啟動 $import 後，將傳回附帶 callback 連結的空白回應本文，回應標題為 Content-location，同時附上 202-Accepted 狀態碼。 儲存該回呼連結，以檢查匯入狀態。

匯入作業註冊會以等冪呼叫實作。 註冊的承載相同即為同一註冊，會影響同名檔案重新處理的能力。 避免就地更新檔案；若要更新資料，建議您使用不同檔案名稱，或者，若一定要就地更新同一個檔案，請在註冊承載內增加 Etag。

若要檢查匯入狀態，請以 GET 方法向前一步驟傳回的 callback 連結進行 REST 呼叫。

藉由下表解讀回應：

回應碼	回應本文	描述
202 已接受		作業仍在執行中。
200 OK	回應本文不含任何 error.url 項目	所有資源皆成功匯入。
200 OK	回應本文包含特定 error.url 項目	部分資源匯入時出現錯誤。 參閱位於 error.url 的檔案以了解詳細資料。 其餘資源皆成功匯入。
其他		出現嚴重錯誤，作業停止。 成功匯入的資源不會復原。

下表說明回應本文內的重要欄位：

欄位	描述
transactionTime	大量匯入作業的開始時間。
output.count	成功匯入資源計數。
error.count	因錯誤而未能匯入的資源計數。
error.url	內含錯誤詳細資料的檔案 URL。 每個輸入 URL 都有專屬 error.url。

{
    "transactionTime": "2021-07-16T06:46:52.3873388+00:00",
    "request": "https://importperf.azurewebsites.net/$Import",
    "output": [
        {
            "type": "Patient",
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/Patient.ndjson"
        },
        {
            "type": "CarePlan",
            "count": 199949,
            "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.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"
        }
    ]
}

內嵌虛刪除資源

增量模式 import 支援內嵌虛刪除資源。 您必須使用延伸模組，才能在 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 OK，但回應包含附帶 URL 的錯誤

行為：import 作業成功並傳回 200 OK。 然而，回應本文有 error.url。 位於 error.url 的檔案包含類似以下範例的 JSON 片段：

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

原因：NDJSON 檔案內的資源有 $import 不支援的條件式參考。

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

400 不正確的要求

行為：匯入作業失敗並傳回 400 Bad Request。 回應本文包含此內容：

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: No such host is known. (example.blob.core.windows.net:443)"
        }
    ]
}

解決方案：驗證 Azure 儲存體的連結是否正確。 檢查網路與防火牆設定，確認 FHIR 伺服器能存取該儲存體。 若您的服務位於虛擬網路，請確認該儲存體位於同一個虛擬網路，或是位於與 FHIR 服務虛擬網路對等互連的虛擬網路。

403 禁止

行為：匯入作業失敗並傳回 403 Forbidden。 回應本文包含此內容：

{
    "resourceType": "OperationOutcome",
    "id": "bd545acc-af5d-42d5-82c3-280459125033",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature."
        }
    ]
}

原因：FHIR 服務針對來源儲存體驗證使用受控識別。 此錯誤代表遺漏角色指派，或角色指派不正確。

解決方案：將儲存體 Blob 資料參與者角色指派給 FHIR 伺服器。 如需詳細資訊，請參閱指派 Azure 角色。

500 內部伺服器錯誤

行為：匯入作業失敗並傳回 500 Internal Server Error。 回應本文包含此內容：

{
    "resourceType": "OperationOutcome",
    "id": "0d0f007d-9e8e-444e-89ed-7458377d7889",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: The database '****' has reached its size quota. Partition or delete data, drop indexes, or consult the documentation for possible resolutions."
        }
    ]
}

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

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

下一步

將資料轉換成 FHIR

設定匯出設定及儲存體帳戶

將資料複製到 Azure Synapse Analytics

注意

FHIR® 是 HL7 的註冊商標，經 HL7 許可後使用。