데이터를 Azure API for FHIR용 FHIR로 변환

아티클
09/27/2024

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® 서비스의 $convert-data 사용자 지정 엔드포인트는 다양한 데이터 형식에서 FHIR로의 데이터 변환을 위한 것입니다. Liquid 템플릿 엔진과 FHIR 변환기 프로젝트의 템플릿을 기본 템플릿으로 사용합니다. 필요에 따라 이러한 변환 템플릿을 사용자 지정할 수 있습니다.

현재 $convert-data 사용자 지정 엔드포인트는 4가지 형식의 데이터 변환을 지원합니다.

원본 데이터 형식	대상 데이터 형식
C-CDA	FHIR
HL7v2	FHIR
JSON	FHIR
FHIR STU3	FHIR R4

참고 항목

$convert-data 엔드포인트는 레거시 형식의 원시 의료 데이터를 FHIR 형식으로 변환하기 위한 ETL(내보내기, 변환, 로드) 파이프라인 내의 구성 요소로 사용될 수 있습니다. 하지만 그 자체는 ETL 파이프라인이 아닙니다. FHIR 데이터를 FHIR 서버에 유지할 준비를 하려면 전체 워크플로에 Logic Apps 또는 Azure Data Factory와 같은 ETL 엔진을 사용하는 것이 좋습니다. 워크플로에는 데이터 읽기 및 수집, 데이터 유효성 검사, $convert-data API 호출, 데이터 전/후처리, 데이터 보강 및 데이터 중복 제거가 포함될 수 있습니다.

$convert-data 엔드포인트 사용

$convert-data 작업은 서비스의 일부로 실행되도록 FHIR 서비스에 통합됩니다. 서버에서 $convert-data를 사용하도록 설정한 후 https://<<FHIR service base URL>>/$convert-data를 사용하여 서버에 API 호출을 보내 데이터를 FHIR로 변환할 수 있습니다.

매개 변수 리소스

$convert-data는 다음 표에 설명된 대로 요청 본문에서 매개 변수 리소스를 사용합니다. API 호출 요청 본문에는 다음 매개 변수가 포함됩니다.

매개 변수 이름	설명	허용되는 값
inputData	변환할 데이터입니다.	`Hl7v2`의 경우: 문자열 `Ccda`의 경우: XML `Json`의 경우: JSON `FHIR STU3`의 경우: JSON
inputDataType	입력 데이터 형식입니다.	`HL7v2`, `Ccda`, `Json`, `Fhir`
templateCollectionReference	ACR(Azure Container Registry)의 OCI 이미지 템플릿 컬렉션에 대한 참조입니다. 변환에 사용할 Liquid 템플릿이 포함된 이미지입니다. 기본 템플릿에 대한 참조이거나 FHIR 서비스에 등록된 사용자 지정 템플릿 이미지일 수 있습니다. 템플릿을 사용자 지정하고, ACR에 템플릿을 호스팅하고, FHIR 서비스에 등록하는 방법에 대해 자세히 알아보려면 다음을 참조하세요.	기본/샘플 템플릿의 경우: HL7v2 템플릿: `microsofthealth/fhirconverter:default` `microsofthealth/hl7v2templates:default` C-CDA 템플릿: `microsofthealth/ccdatemplates:default` JSON 템플릿: `microsofthealth/jsontemplates:default` FHIR STU3 템플릿: `microsofthealth/stu3tor4templates:default` 사용자 지정 템플릿의 경우: <RegistryServer>/<imageName>@<imageDigest>, <RegistryServer>/<imageName>:<imageTag>
rootTemplate	데이터를 변환하는 동안 사용할 루트 템플릿입니다.	HL7v2의 경우: "ADT_A01", "ADT_A02", "ADT_A03", "ADT_A04", "ADT_A05", "ADT_A08", "ADT_A11", "ADT_A13", "ADT_A14", "ADT_A15", "ADT_A16", "ADT_A25", "ADT_A26", "ADT_A27", "ADT_A28", "ADT_A29", "ADT_A31", "ADT_A47", "ADT_A60", "OML_O21", "ORU_R01", "ORM_O01", "VXU_V04", "SIU_S12", "SIU_S13", "SIU_S14", "SIU_S15", "SIU_S16", "SIU_S17", "SIU_S26", "MDM_T01", "MDM_T02" C-CDA의 경우: "CCD", "ConsultationNote", "DischargeSummary", "HistoryandPhysical", "OperativeNote", "ProcedureNote", "ProgressNote", "ReferralNote", "TransferSummary" JSON의 경우: "ExamplePatient", "Stu3ChargeItem" FHIR STU3": STU3 리소스, 이름(예: "Patient", "Observation", "Organization").

참고 항목

FHIR STU3~R4 템플릿은 STU3 리소스와 FHIR R4 표준의 동등한 리소스 간 필드 차이에 대한 매핑만 제공하는 "diff" Liquid 템플릿입니다. 일부 STU3 리소스는 R4에서 이름이 변경되거나 제거되었습니다. STU3에서 R4로 변환을 위한 리소스 차이점 및 제약 조건을 참조하세요.

참고 항목

JSON 템플릿은 미리 정의된 JSON 메시지 유형을 준수하는 "기본" 템플릿이 아니라 사용할 샘플 템플릿입니다. JSON에는 HL7v2 메시지 또는 C-CDA 문서와 달리 표준화된 메시지 유형이 없습니다. 기본 템플릿 대신 사용자 지정 템플릿에 대한 시작 가이드로 사용할 수 있는 몇 가지 샘플 템플릿을 제공합니다.

Warning

기본 템플릿은 MIT 라이선스에 따라 릴리스되며 Microsoft 지원에서 지원하지 않습니다.

기본 템플릿은 시작하는 데 도움을 주기 위해서만 제공됩니다. Azure API for FHIR 버전을 업데이트하면 업데이트될 수 있습니다. 변환 동작을 확인하고 Azure Container Registry에서 템플릿의 자체 복사본을 호스팅하고, API 호출에서 사용할 Azure API for FHIR에 해당 템플릿을 등록해야 합니다. 이는 Azure API for FHIR의 여러 버전에서 일관된 데이터 변환 동작을 위해 필요합니다.

샘플 요청

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputData",
            "valueString": "MSH|^~\\&|SIMHOSP|SFAC|RAPP|RFAC|20200508131015||ADT^A01|517|T|2.3|||AL||44|ASCII\nEVN|A01|20200508131015|||C005^Whittingham^Sylvia^^^Dr^^^DRNBR^D^^^ORGDR|\nPID|1|3735064194^^^SIMULATOR MRN^MRN|3735064194^^^SIMULATOR MRN^MRN~2021051528^^^NHSNBR^NHSNMBR||Kinmonth^Joanna^Chelsea^^Ms^^D||19870624000000|F|||89 Transaction House^Handmaiden Street^Wembley^^FV75 4GJ^GBR^HOME||020 3614 5541^PRN|||||||||C^White - Other^^^||||||||\nPD1|||FAMILY PRACTICE^^12345|\nPV1|1|I|OtherWard^MainRoom^Bed 183^Simulated Hospital^^BED^Main Building^4|28b|||C005^Whittingham^Sylvia^^^Dr^^^DRNBR^D^^^ORGDR|||CAR|||||||||16094728916771313876^^^^visitid||||||||||||||||||||||ARRIVED|||20200508131015||"
        },
        {
            "name": "inputDataType",
            "valueString": "Hl7v2"
        },
        {
            "name": "templateCollectionReference",
            "valueString": "microsofthealth/fhirconverter:default"
        },
        {
            "name": "rootTemplate",
            "valueString": "ADT_A01"
        }
    ]
}

샘플 응답

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:9d697ec3-48c3-3e17-db6a-29a1765e22c6",
      "resource": {
        "resourceType": "Patient",
        "id": "9d697ec3-48c3-3e17-db6a-29a1765e22c6",
        ...
        ...
      "request": {
        "method": "PUT",
        "url": "Location/50becdb5-ff56-56c6-40a1-6d554dca80f0"
      }
    }
  ]
}

템플릿 사용자 지정

Visual Studio Code용 FHIR Converter 확장을 사용하여 필요에 따라 템플릿을 사용자 지정할 수 있습니다. 이 확장은 대화형 편집 환경을 제공하며 Microsoft에서 게시한 템플릿 및 샘플 데이터를 쉽게 다운로드할 수 있게 해줍니다. 자세한 내용은 확장의 설명서를 참조하세요.

참고 항목

Visual Studio Code용 FHIR 변환기 확장을 HL7v2, C-CDA 및 JSON Liquid 템플릿에 사용할 수 있습니다. FHIR STU3에서 R4 Liquid로 템플릿은 현재 지원되지 않습니다.

템플릿 호스트 및 사용

ACR에서 고유한 템플릿 복사본을 호스트하는 것이 좋습니다. $convert-data 작업에서 템플릿의 자체 복사본을 호스팅하고 이를 사용하려면 4단계가 필요합니다.

Azure Container Registry로 템플릿을 푸시합니다.
Azure API for FHIR 인스턴스에서 관리 ID를 사용합니다.
Azure API for FHIR 관리 ID에 ACR 액세스를 제공합니다.
Azure API for FHIR에서 ACR 서버 등록
필요에 따라 보안 액세스를 위해 ACR 방화벽을 구성합니다.

Azure Container Registry로 템플릿 푸시

ACR 인스턴스를 만든 후 FHIR 변환기 확장에서 FHIR 변환기: 푸시 템플릿 명령을 사용하여 사용자 지정된 템플릿을 ACR에 푸시할 수 있습니다. 또는 템플릿 관리 CLI 도구를 사용할 수 있습니다.

Azure API for FHIR에서 관리 ID 사용

Azure Portal에서 Azure API for FHIR 서비스의 인스턴스로 이동한 다음 ID 블레이드를 선택합니다. Azure API for FHIR에서 관리 ID를 사용하려면 상태를 켜기로 변경합니다.

Azure API for FHIR에 ACR 액세스 제공

액세스 제어(IAM) 블레이드로 이동합니다.
추가를 선택한 다음 역할 할당 추가를 선택하여 역할 할당 추가 페이지를 엽니다.
AcrPull 역할을 할당합니다.

Azure Portal에서 역할을 할당하는 방법에 대한 자세한 내용은 Azure 기본 제공 역할을 참조하세요.

Azure API for FHIR에서 ACR 서버 등록

Azure Portal을 사용하거나 CLI를 사용하여 ACR 서버를 등록할 수 있습니다.

Azure Portal을 사용하여 ACR 서버 등록

Azure API for FHIR 인스턴스의 데이터 변환 아래에서 아티팩트 블레이드로 이동합니다. 현재 등록된 ACR 서버 목록이 표시됩니다. 추가를 선택한 다음 드롭다운 메뉴에서 레지스트리 서버를 선택합니다. 등록을 적용하려면 저장을 선택해야 합니다. 변경 내용을 적용하고 인스턴스를 다시 시작하는 데 몇 분 정도 걸릴 수 있습니다.

CLI를 사용하여 ACR 서버 등록

Azure API for FHIR에 최대 20개의 ACR 서버를 등록할 수 있습니다.

필요한 경우 Azure PowerShell에서 Azure Health Data Services CLI를 설치합니다.

az extension add -n healthcareapis

다음 예에 따라 Azure API for FHIR에 ACR 서버를 등록합니다.

단일 ACR 서비스 등록

az healthcareapis acr add --login-servers "fhiracr2021.azurecr.io" --resource-group fhir-test --resource-name fhirtest2021

여러 ACR 서비스 등록

az healthcareapis acr add --login-servers "fhiracr2021.azurecr.io fhiracr2020.azurecr.io" --resource-group fhir-test --resource-name fhirtest2021

ACR 방화벽 구성

포털에서 Azure Storage 계정에 대해 네트워킹을 선택합니다.

컨테이너 레지스트리의 화면 이미지.

선택한 네트워크를 선택합니다.

방화벽 섹션의 주소 범위 상자에 IP 주소를 지정합니다. 인터넷 또는 온-프레미스 네트워크에서의 액세스를 허용하기 위한 IP 범위를 추가합니다.

다음 표에서는 Azure API for FHIR 서비스가 프로비전된 Azure 지역의 IP 주소를 확인할 수 있습니다.

Azure 지역	공용 IP 주소
오스트레일리아 동부	20.53.47.210
브라질 남부	191.238.72.227
캐나다 중부	20.48.197.161
인도 중부	20.192.47.66
미국 동부	20.62.134.242, 20.62.134.244, 20.62.134.245
미국 동부 2	20.62.60.115, 20.62.60.116, 20.62.60.117
프랑스 중부	51.138.211.19
독일 북부	51.116.60.240
독일 중서부	20.52.88.224
일본 동부	20.191.167.146
일본 서부	20.189.228.225
한국 중부	20.194.75.193
미국 중북부	52.162.111.130, 20.51.0.209
북유럽	52.146.137.179
카타르 중부	20.21.36.225
남아프리카 공화국 북부	102.133.220.199
미국 중남부	20.65.134.83
동남 아시아	20.195.67.208
스웨덴 중부	51.12.28.100
스위스 북부	51.107.247.97
영국 남부	51.143.213.211
영국 서부	51.140.210.86
미국 중서부	13.71.199.119
서유럽	20.61.103.243, 20.61.103.244
미국 서부 2	20.51.13.80, 20.51.13.84, 20.51.13.85
미국 서부 3	20.150.245.165

참고 항목

이전 단계는 FHIR 데이터를 내보내는 방법 문서에 설명된 구성 단계와 유사합니다. 자세한 내용은 Azure Storage로의 안전한 내보내기를 참조하세요.

확인

templateCollectionReference 매개 변수에 템플릿 참조를 지정하여 $convert-data API를 호출합니다.

<RegistryServer>/<imageName>@<imageDigest>

다음 단계

이 문서에서는 Azure API for FHIR의 데이터 변환에 대해 알아보았습니다. Azure API for FHIR 관련 GitHub 프로젝트에 대한 자세한 내용은 다음을 참조하세요.

Azure API for FHIR 관련 GitHub 프로젝트

참고 항목

FHIR®은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.

다음을 통해 공유

데이터를 Azure API for FHIR용 FHIR로 변환

$convert-data 엔드포인트 사용

매개 변수 리소스

샘플 요청

샘플 응답

템플릿 사용자 지정

템플릿 호스트 및 사용

Azure Container Registry로 템플릿 푸시

Azure API for FHIR에서 관리 ID 사용

Azure API for FHIR에 ACR 액세스 제공

Azure API for FHIR에서 ACR 서버 등록

Azure Portal을 사용하여 ACR 서버 등록

CLI를 사용하여 ACR 서버 등록

단일 ACR 서비스 등록

여러 ACR 서비스 등록

ACR 방화벽 구성

확인

다음 단계

피드백

추가 리소스