Azure API for FHIR에서 FHIR 데이터 내보내기
Important
Azure API for FHIR은 2026년 9월 30일에 사용 중지됩니다. 해당 날짜까지 마이그레이션 전략에 따라 Azure Health Data Services FHIR 서비스로 전환합니다. Azure API for FHIR의 사용 중지로 인해 2025년 4월 1일부터 신규 배포가 허용되지 않습니다. Azure Health Data Services FHIR 서비스는 고객이 다른 Azure 서비스에 통합하여 FHIR, DICOM 및 MedTech 서비스를 관리할 수 있도록 하는 Azure API for FHIR의 진화된 버전입니다.
대량으로 내보내기 기능을 사용하면 FHIR 사양에 따라 FHIR 서버에서 데이터를 내보낼 수 있습니다.
$export 사용하기 전에 Azure API for FHIR을 사용하도록 구성해야 합니다. 내보내기 설정을 구성하고 Azure Storage 계정을 만들려면 내보내기 데이터 구성 페이지를 참조하세요.
참고 항목
Azure API for FHIR과 동일한 구독의 스토리지 계정만 $export 작업의 대상으로 등록할 수 있습니다.
$export 명령 사용
내보내기용 Azure API for FHIR을 구성한 후 $export 명령을 사용하여 서비스에서 데이터를 내보낼 수 있습니다. 데이터는 내보내기를 구성하는 동안 지정한 스토리지 계정에 저장됩니다. FHIR 서버에서 $export 명령을 호출하는 방법을 알아보려면 HL7 FHIR $export 사양에 대한 설명서를 읽어보세요.
잘못된 상태로 중단된 작업
어떤 경우에는 작업이 잘못된 상태에 갇히게 될 가능성이 있습니다. 특히 스토리지 계정 권한이 제대로 설정되지 않은 경우에 발생할 수 있습니다. 내보내기 유효성을 검사하는 한 가지 방법은 스토리지 계정을 검사 해당 컨테이너(즉, ndjson파일)가 있는지 확인하는 것입니다. 실행 중인 다른 내보내기 작업이 없는 경우 현재 작업이 잘못된 상태로 중단될 가능성이 있습니다. 취소 요청을 전송하여 내보내기 작업을 취소하고 작업을 다시 큐에 다시 큐에 표시해야 합니다. 잘못된 상태의 내보내기 기본 실행 시간은 10분 후에 중지되고 새 작업으로 이동하거나 내보내기를 다시 시도합니다.
Azure API For FHIR은 다음 수준에서 $export 지원합니다.
- 시스템:
GET https://<<FHIR service base URL>>/$export>> - 환자:
GET https://<<FHIR service base URL>>/Patient/$export>> - 환자 그룹* - Azure API for FHIR은 모든 관련 리소스를 내보내지만 그룹의 특성을 내보내지는 않습니다.
GET https://<<FHIR service base URL>>/Group/[ID]/$export>>
내보내기에서 데이터는 각각 하나의 형식의 리소스를 포함하는 여러 파일로 내보내집니다. 개별 파일의 리소스 수는 제한됩니다. 최대 리소스 수는 시스템 성능을 기반으로 합니다. 현재 5,000으로 설정되어 있지만 변경할 수 있습니다. 그 결과 리소스 종류에 대한 여러 파일을 가져올 수 있습니다. 파일 이름은 'resourceName-number-number.ndjson' 형식을 따릅니다. 파일 순서는 데이터베이스의 리소스 순서에 해당하지 않습니다.
참고 항목
Patient/$export 리소스 Group/[ID]/$export 가 둘 이상의 리소스 구획에 있거나 여러 그룹에 있는 경우 중복 리소스를 내보낼 수 있습니다.
또한 큐에 있는 동안 위치 헤더에서 반환된 URL을 통해 내보내기 상태 검사 실제 내보내기 작업 취소와 함께 지원됩니다.
ADLS Gen2로 FHIR 데이터 내보내기
현재 ADLS Gen2 사용 스토리지 계정에 대한 $export 지원하며, 다음과 같은 제한 사항이 있습니다.
- 사용자는 계층 구조 네임스페이스를 활용할 수 없지만 컨테이너 내의 특정 하위 디렉터리로 내보내기를 대상으로 지정할 수 있는 방법은 없습니다. 특정 컨테이너를 대상으로 하는 기능만 제공합니다(각 내보내기마다 새 폴더를 만드는 경우).
- 내보내기가 완료되면 동일한 컨테이너로의 후속 내보내기가 새로 만든 폴더 내에 있으므로 해당 폴더로 아무것도 내보내지 않습니다.
설정 및 매개 변수
헤더
$export 작업에 대해 설정해야 하는 두 가지 필수 헤더 매개 변수가 있습니다. 값은 현재 $export 사양에 의해 정의됩니다.
- 수락 - application/fhir+json
- Prefer - respond-async
쿼리 매개 변수
Azure API for FHIR은 다음 쿼리 매개 변수를 지원합니다. 이러한 매개 변수는 모두 선택 사항입니다.
| 쿼리 매개 변수 | FHIR 사양으로 정의하시겠습니까? | 설명 |
|---|---|---|
| _outputFormat | 예 | 현재 FHIR 사양에 맞게 애플리케이션/fhir+ndjson, application/ndjson 또는 ndjson의 세 가지 값을 지원합니다. 모든 내보내기 작업이 반환 ndjson 되고 전달된 값은 코드 동작에 영향을 주지 않습니다. |
| _since | 예 | 제공된 시간 이후 수정된 리소스만 내보낼 수 있습니다. |
| _type | 예 | 포함할 리소스 유형을 지정할 수 있습니다. 예를 들어 _type=Patient는 환자 리소스만 반환합니다. |
| _typefilter | 예 | 세분화된 필터링을 요청하려면 _type 매개 변수와 함께 _typefilter 사용할 수 있습니다. _typeFilter 매개 변수의 값은 결과를 추가로 제한하는 쉼표로 구분된 FHIR 쿼리 목록입니다. |
| _컨테이너 | 아니요 | 데이터를 내보낼 구성된 스토리지 계정 내의 컨테이너를 지정합니다. 컨테이너를 지정하면 데이터가 해당 컨테이너로 폴더로 내보내집니다. 컨테이너를 지정하지 않으면 데이터를 새 컨테이너로 내보냅니다. |
| _까지 | 아니요 | 제공된 시간까지 수정된 리소스만 내보낼 수 있습니다. 이 매개 변수는 시스템 수준 내보내기만 적용할 수 있습니다. 이 경우 기록 버전을 사용하지 않도록 설정하거나 제거하지 않은 경우 내보내기에서 실제 스냅샷 보기를 보장하거나, 즉 시간 여행을 사용하도록 설정합니다. |
| includeAssociatedData | 아니요 | 기록 및 일시 삭제된 리소스를 내보낼 수 있습니다. 이 필터는 '_typeFilter' 쿼리 매개 변수에서 작동하지 않습니다. 기록/최신 버전이 아닌 리소스를 내보내려면 값을 '_history'으로 포함합니다. 일시 삭제된 리소스를 내보내려면 값을 '_deleted'으로 포함합니다. |
| _isparallel | 아니요 | "_isparallel" 쿼리 매개 변수를 내보내기 작업에 추가하여 처리량을 향상시킬 수 있습니다. 병렬 처리를 사용하려면 값을 true로 설정해야 합니다. 이 매개 변수를 사용하면 내보내기 수명 동안 요청 단위 사용량이 증가할 수 있습니다. |
참고 항목
$export 작업에는 상태 성공으로 불완전한 내보내기가 발생할 수 있는 알려진 문제가 있습니다. is_parallel 플래그를 사용할 때 문제가 발생합니다. 2024년 2월 13일부터 _isparallel 쿼리 매개 변수로 실행된 내보내기 작업이 이 문제의 영향을 받았습니다.
Azure Storage로 안전하게 내보내기
Azure API for FHIR은 보안 내보내기 작업을 지원합니다. 아래 두 옵션 중 하나를 선택합니다.
Azure API for FHIR을 Microsoft 신뢰할 수 있는 서비스로 허용하여 Azure Storage 계정에 액세스할 수 있습니다.
Azure API for FHIR과 연결된 특정 IP 주소가 Azure Storage 계정에 액세스할 수 있도록 허용합니다. 이 옵션은 스토리지 계정이 동일한 위치에 있는지 또는 Azure API for FHIR의 위치와 다른 위치에 있는지에 따라 두 가지 구성을 제공합니다.
Azure API for FHIR을 Microsoft 신뢰할 수 있는 서비스로 허용
Azure Portal에서 스토리지 계정을 선택한 다음 네트워킹 블레이드를 선택합니다. 방화벽 및 가상 네트워크 탭에서 선택한 네트워크를 선택합니다.
Important
관리 ID를 사용하여 Azure API for FHIR에 대한 스토리지 계정에 대한 액세스 권한을 부여했는지 확인합니다. 자세한 내용은 내보내기 설정 구성 및 스토리지 계정 설정을 참조하세요.
예외 섹션에서 신뢰할 수 있는 Microsoft 서비스 허용 상자를 선택하여 이 스토리지 계정에 액세스하고 설정을 저장합니다.
이제 FHIR 데이터를 스토리지 계정으로 안전하게 내보낼 준비가 되었습니다. 스토리지 계정은 선택한 네트워크에 있으며 공개적으로 액세스할 수 없습니다. 파일에 액세스하려면 스토리지 계정에 대해 프라이빗 엔드포인트를 사용하도록 설정하고 사용하거나 짧은 기간 동안 스토리지 계정에 대한 모든 네트워크를 사용하도록 설정할 수 있습니다.
Important
사용자 인터페이스는 나중에 업데이트되어 Azure API for FHIR 및 특정 서비스 인스턴스에 대한 리소스 유형을 선택할 수 있도록 합니다.
특정 IP 주소가 다른 Azure 지역에서 Azure Storage 계정에 액세스하도록 허용
Azure Portal에서 Azure Data Lake Storage Gen2 계정으로 이동합니다.
왼쪽 메뉴에서 네트워킹을 선택합니다.
선택한 가상 네트워크 및 IP 주소에서 사용을 선택합니다.
방화벽 섹션의 주소 범위 상자에서 IP 주소를 지정합니다. 인터넷 또는 온-프레미스 네트워크에서의 액세스를 허용하기 위한 IP 범위를 추가합니다. FHIR 서비스가 프로비전되는 Azure 지역의 다음 표에서 IP 주소를 찾을 수 있습니다.
Azure 지역 공용 IP 주소 오스트레일리아 동부 20.53.44.80 캐나다 중부 20.48.192.84 미국 중부 52.182.208.31 미국 동부 20.62.128.148 미국 동부 2 20.49.102.228 미국 동부 2 EUAP 20.39.26.254 독일 북부 51.116.51.33 독일 중서부 51.116.146.216 일본 동부 20.191.160.26 한국 중부 20.41.69.51 미국 중북부 20.49.114.188 북유럽 52.146.131.52 남아프리카 공화국 북부 102.133.220.197 미국 중남부 13.73.254.220 동남 아시아 23.98.108.42 스위스 북부 51.107.60.95 영국 남부 51.104.30.170 영국 서부 51.137.164.94 미국 중서부 52.150.156.44 서유럽 20.61.98.66 미국 서부 2 40.64.135.77
특정 IP 주소가 동일한 지역의 Azure Storage 계정에 액세스하도록 허용
동일한 지역의 IP 주소에 대한 구성 프로세스는 클래스리스 INTER-Do기본 라우팅(CIDR) 형식의 특정 IP 주소 범위(즉, 100.64.0.0/10)를 사용한다는 점을 제외하고 이전 절차와 같습니다. 작업 요청을 할 때마다 FHIR 서비스의 IP 주소가 할당되므로 IP 주소 범위(100.64.0.0~100.127.255.255)를 지정해야 합니다.
참고 항목
10.0.2.0/24 범위 내에서 개인 IP 주소를 사용할 수 있지만 이러한 경우 작업이 성공할 것이라는 보장은 없습니다. 작업 요청이 실패하는 경우 다시 시도할 수 있지만 100.64.0.0/10 범위 내에서 IP 주소를 사용할 때까지는 요청이 성공하지 않습니다.
IP 주소 범위에 대한 이 네트워크 동작은 기본적으로 설계되었습니다. 또는 다른 지역에서 스토리지 계정을 구성할 수도 있습니다.
다음 단계
이 문서에서는 $export 명령을 사용하여 FHIR 리소스를 내보내는 방법을 알아보았습니다. 다음으로 식별되지 않은 데이터를 내보내는 방법을 알아보려면 다음을 참조하세요.
FHIR®은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.