インポート操作
インポート操作を使用すると、$import操作を使用して、高速医療相互運用性リソース (FHIR®) データを高スループットで FHIR サーバーに読み込むことができます。 インポートでは、FHIR サーバーへの初期データ読み込みと増分データ読み込みの両方がサポートされます。
$import操作の使用
注意
$importを使用するには、FHIR サーバーで FHIR データ インポーター ロールが必要です。
$importを使用するには、インポート設定の構成に関する記事の手順に従って FHIR サーバー を構成する 必要があります。 インポートする FHIR データは、Azure BLOB ストアの FHIR NDJSON 形式のリソース固有のファイルに格納する必要があります。
インポート操作の場合は、
- ファイル内のすべてのリソースは、同じ種類である必要があります。 リソースの種類ごとに複数のファイルがある場合があります。
- インポートするデータは、FHIR サービスと同じテナントに存在する必要があります。
- 操作ごとにインポートするファイルの最大数は 10,000 です。
メモ:
- インポート操作では、リソース内の条件付き参照はサポートされていません。
- インポート操作中に、複数のリソースが同じリソース ID を共有している場合、それらのリソースのうち 1 つだけがランダムにインポートされます。 同じリソース ID を共有しているリソースに対してログに記録されたエラーがあります。
$importの呼び出し
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 します。 増分インポート モードの場合は、mode 値を使用 IncrementalLoad します。 モード値が指定されていない場合、IncrementalLoad モードの値は既定で考慮されます。 |
| input | 入力ファイルの詳細。 | 1..* | 次の表で説明する 3 つの部分を含む JSON 配列。 |
| 入力パーツ名 | 説明 | カード。 | 指定可能な値 |
|---|---|---|---|
| type | 入力ファイルのリソースの種類 | 1..1 | 入力ファイルと一致する有効な FHIR リソースの種類 。 |
| URL | 入力ファイルの Azure ストレージ URL | 1..1 | 変更できない入力ファイルの URL 値。 |
| etag | ファイルの内容が変更されていないことを確認するために使用される Azure Storage 上の入力ファイルの Etag。 | 0..1 | 変更できない入力ファイルの Etag 値。 |
初期読み込みインポートのサンプル本文:
{
"resourceType": "Parameters",
"parameter": [
{
"name": "inputFormat",
"valueString": "application/fhir+ndjson"
},
{
"name": "mode",
"valueString": "InitialLoad"
},
{
"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が開始されると、コールバック リンクを含む空の応答本文が、状態コードと共に応答のヘッダーにContent-location202-Accepted返されます。 インポートの状態をチェックするには、このコールバック リンクを格納します。
インポートの状態をチェックするには、前の手順で返されたコールバック リンクへの メソッドを使用GETして REST 呼び出しを行います。
応答は、次の表を使用して解釈できます。
| 応答コード | 応答本文 | 説明 |
|---|---|---|
| 202 Accepted | 操作はまだ実行中です。 | |
| 200 OK | 応答本文に error.url エントリが含まれていない | すべてのリソースが正常にインポートされました。 |
| 200 OK | 応答本文に error.url エントリが含まれています | 一部のリソースのインポート中にエラーが発生しました。 詳細については、error.url にあるファイルを参照してください。 残りのリソースは正常にインポートされました。 |
| その他 | 致命的なエラーが発生し、操作が停止しました。 正常にインポートされたリソースがロールバックされていません。 |
次の表に、応答本文の重要なフィールドをいくつか示します。
| フィールド | 説明 |
|---|---|
| transactionTime | 一括インポート操作の開始時刻。 |
| 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": "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"
}
]
}
トラブルシューティング
インポート操作中に発生する可能性のあるいくつかのエラー コードに対するウォークスルー ソリューションを使用します。
200 OK ですが、応答の URL にエラーがあります
動作： インポート操作が成功し、 が返されます 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 Bad Request
動作： インポート操作が失敗し、 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 Storage へのリンクが正しいことを確認します。 ネットワークとファイアウォールの設定を確認して、FHIR サーバーがストレージにアクセスできることを確認します。 サービスが VNet 内にある場合は、ストレージが同じ VNet 内か、FHIR サービス VNet とピアリングされている VNet 内にあることを確認します。
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."
}
]
}
原因： ソース ストレージ認証にはマネージド ID を使用します。このエラーは、ロールの割り当てが見つからないか間違っている可能性があります。
ソリューション：RBAC ガイドに従って、ストレージ BLOB データ共同作成者ロールを FHIR サーバーに割り当てます。
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 サービスのストレージ制限に達しました。
ソリューション： データのサイズを小さくするか、ストレージ制限が高い Azure API for FHIR を検討してください。
次のステップ
この記事では、インポート操作で FHIR データを高スループットで FHIR サーバーにインポートする方法について説明しました。 データを FHIR に変換する方法、ストレージ アカウントを設定するための設定をエクスポートする方法、データをAzure Synapseに移動する方法の詳細については、「」を参照してください。
FHIR® は HL7 の登録商標であり、HL7 の許可を得て使用しています。