FHIR 데이터 가져오기
import 작업을 통해 처리량이 높은 FHIR 서버에 FHIR® 데이터를 수집할 수 있습니다.
가져오기 작업 모드
import 작업은 초기 모드와 증분 모드의 두 가지 모드를 지원합니다. 각 모드에는 다양한 기능과 사용 사례가 있습니다.
초기 모드
빈 FHIR 서버에 FHIR 리소스를 로드하기 위한 것입니다.
create작업만 지원하고 사용하도록 설정한 경우 API가 FHIR 서버에 쓰는 것을 차단합니다.
증분 모드
주기적으로 FHIR 서버에 데이터를 로드할 수 있도록 최적화되었으며 API를 통한 쓰기를 차단하지 않습니다.
리소스 JSON에 있는 경우 리소스 메타데이터에서
lastUpdated및versionId를 로드할 수 있습니다.가져오기 파일에
version및lastUpdated필드 값이 지정되지 않은 경우 FHIR 서비스에서 리소스 가져오기가 보장되지 않습니다.가져오기 파일에
version및lastUpdated필드 값이 중복된 리소스가 있는 경우 FHIR 서비스에서 하나의 리소스만 임의로 수집됩니다.
일시 삭제된 리소스를 수집할 수 있습니다. 이 기능은 Azure API for FHIR에서 Azure Health Data Services의 FHIR 서비스로 마이그레이션할 때 유용합니다.
Important
import 작업은 리소스의 조건부 참조를 지원하지 않습니다.
또한 여러 리소스가 동일한 리소스 ID를 공유하는 경우 해당 리소스 중 하나만 임의로 가져옵니다. 동일한 리소스 ID를 공유하는 리소스에 대한 오류가 기록됩니다.
성능 고려 사항
import 작업으로 최상의 성능을 얻으려면 다음 요소를 고려합니다.
큰 파일을 가져오기에 사용합니다. 단일
import작업의 파일 크기는 200MB를 초과해야 합니다. 파일이 작을수록 가져오는 데 시간이 오래 걸릴 수 있습니다.FHIR 리소스 파일을 단일 일괄 처리로 가져옵니다. 최적의 성능을 위해 FHIR 서버에서 수집하려는 모든 FHIR 리소스 파일을 한 번의
import작업으로 가져옵니다. 한 번의 작업으로 모든 파일을 가져오면 여러 가져오기 작업을 만들고 관리하는 오버헤드가 줄어듭니다.병렬 가져오기 작업의 수를 제한합니다. 동시에 여러
import작업을 실행할 수 있지만 여러 작업을 실행하면 가져오기 작업의 전체 처리량에 영향을 줄 수 있습니다. FHIR 서버는 최대 5개의 병렬import작업을 처리할 수 있습니다. 이 제한을 초과하면 FHIR 서버가 요청을 제한하거나 거부할 수 있습니다.
가져오기 작업 수행
필수 조건
import작업을 사용하려면 FHIR 서버에 대한 FHIR 데이터 수신자 역할이 필요합니다.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 Storage URL | 1..1 | 입력 파일의 URL 값. 이 값은 수정할 수 없습니다. |
| etag | Azure Storage에 있는 입력 파일의 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 링크가 있는 빈 응답 본문이 202-Accepted 상태 코드와 함께 Content-location 응답 헤더에 반환됩니다. 콜백 링크를 저장하여 가져오기 상태를 확인합니다.
가져오기 작업 등록은 idempotent 호출로 구현됩니다. 동일한 등록 페이로드는 동일한 등록을 생성하므로 동일한 이름의 파일을 다시 처리하는 기능에 영향을 줍니다. 현재 위치에서 파일을 업데이트하지 않고 업데이트된 데이터에 다른 파일 이름을 사용하거나 동일한 파일 이름으로 현재 위치에서 업데이트할 수 없는 경우 등록 페이로드에 e-태그를 추가하는 것이 좋습니다.
가져오기 상태를 확인하려면 이전 단계에서 반환된 callback 링크에 GET 메서드를 사용하여 REST 호출을 수행합니다.
아래 표를 사용하여 응답을 해석합니다.
| 응답 코드 | 응답 본문 | 설명 |
|---|---|---|
| 202 수락됨 | 작업이 아직 진행 중입니다. | |
| 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"
}
]
}
일시 삭제된 리소스 수집
증분 모드 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 작업이 성공적으로 완료되면 리소스에 대한 기록 검색을 수행하여 일시 삭제된 리소스의 유효성을 검사합니다. 삭제된 리소스의 ID를 알고 있는 경우 예제에서 URL 패턴을 사용합니다.
<FHIR_URL>/<resource-type>/<resource-id>/_history
리소스의 ID를 모르는 경우 리소스 종류에 대한 기록 검색을 수행합니다.
<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 Storage에 대한 링크가 올바른지 확인합니다. 네트워크 및 방화벽 설정에서 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 서비스는 원본 스토리지 인증에 관리 ID를 사용합니다. 이 오류는 누락되거나 잘못된 역할 할당을 나타냅니다.
해결 방법:Storage 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 서비스의 저장 한도에 도달했습니다.
해결 방법: 데이터 크기를 줄이거나 스토리지 제한이 더 높은 Azure API for FHIR을 고려합니다.
다음 단계
Azure Synapse Analytics에 데이터 복사
참고 항목
FHIR®은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.