Azure API for 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®(Fast Healthcare Interoperability Resources) 사양은 리소스와 관련된 모든 리소스 및 검색 매개 변수에 대한 검색 매개 변수 집합을 정의합니다. 그러나 FHIR 사양에 의해 표준 검색 매개 변수로 정의되지 않은 리소스의 요소에 대해 검색할 수 있는 시나리오가 있습니다. 이 문서에서는 Azure API for FHIR에서 사용할 자체 검색 매개 변수 를 정의하는 방법을 설명합니다.
참고 항목
검색 매개 변수를 만들거나 업데이트하거나 삭제할 때마다 다시 인덱스 작업을 실행하여 프로덕션 환경에서 검색 매개 변수를 사용할 수 있도록 해야 합니다. 이 문서에서는 전체 FHIR 서버를 다시 인덱싱하기 전에 검색 매개 변수를 테스트하는 방법을 간략하게 설명합니다.
새 검색 매개 변수 만들기
새 검색 매개 변수 POST 를 만들려면 데이터베이스에 SearchParameter 대한 리소스입니다. 다음 코드 예제에서는 리소스에 US Core Race SearchParameter 를 Patient 추가하는 방법을 보여줍니다.
POST {{FHIR_URL}}/SearchParameter
{
"resourceType" : "SearchParameter",
"id" : "us-core-race",
"url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
"version" : "3.1.1",
"name" : "USCoreRace",
"status" : "active",
"date" : "2019-05-21",
"publisher" : "US Realm Steering Committee",
"contact" : [
{
"telecom" : [
{
"system" : "other",
"value" : "http://www.healthit.gov/"
}
]
}
],
"description" : "Returns patients with a race extension matching the specified code.",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "US",
"display" : "United States of America"
}
]
}
],
"code" : "race",
"base" : [
"Patient"
],
"type" : "token",
"expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}
참고 항목
검색 매개 변수를 데이터베이스에 게시하고 데이터베이스를 다시 인덱싱한 후 새 검색 매개 변수가 FHIR 서버의 기능 문에 표시됩니다. SearchParameter 기능 문에서 검색 매개 변수가 FHIR 서버에서 지원되는지 확인하는 유일한 방법은 기능 문에서 보는 것입니다. 검색 매개 변수를 찾을 수 있지만 기능 문에서 볼 수 없는 경우 검색 매개 변수를 인덱싱해야 합니다. 다시 인덱스 작업을 트리거하기 전에 여러 검색 매개 변수를 POST할 수 있습니다.
중요한 요소는 SearchParameter 다음과 같습니다.
url: 검색 매개 변수를 설명하는 고유 키입니다. HL7과 같은 많은 조직에서는 이전에 US Core 레이스 검색 매개 변수에 표시된 것처럼 정의하는 검색 매개 변수에 표준 URL 형식을 사용합니다.
code: 코드에 저장된 값은 검색할 때 사용하는 값입니다. 앞의 예제에서는 특정 인종의 모든 환자를 가져오기 위해 검색
GET {FHIR_URL}/Patient?race=<code>합니다. 코드는 검색 매개 변수가 적용되는 리소스에 대해 고유해야 합니다.base: 검색 매개 변수가 적용되는 리소스를 설명합니다. 검색 매개 변수가 모든 리소스에 적용되는 경우 사용할
Resource수 있습니다. 그렇지 않으면 모든 관련 리소스를 나열할 수 있습니다.형식: 검색 매개 변수의 데이터 형식을 설명합니다. 형식은 Azure API for FHIR에 대한 지원으로 제한됩니다. 즉, 지원되는 조합이 아니면 Special 형식의 검색 매개 변수를 정의하거나 복합 검색 매개 변수 를 정의할 수 없습니다.
식: 검색 값을 계산하는 방법을 설명합니다. 검색 매개 변수를 설명할 때는 사양에 필요하지 않더라도 식을 포함해야 합니다. 식이나 xpath 구문이 필요하고 Azure API for FHIR이 xpath 구문을 무시하기 때문입니다.
검색 매개 변수 테스트
다시 인덱스 작업을 실행할 때까지 프로덕션 환경에서 검색 매개 변수를 사용할 수 없지만 전체 데이터베이스를 다시 인덱싱하기 전에 검색 매개 변수를 테스트할 수 있습니다.
먼저 새 검색 매개 변수를 테스트하여 반환되는 값을 확인할 수 있습니다. ID를 입력하여 특정 리소스 인스턴스에 대해 다음 명령을 실행하면 검색 매개 변수 이름과 특정 환자에 대해 저장된 값이 포함된 값 쌍 목록을 가져옵니다. 여기에는 리소스에 대한 모든 검색 매개 변수가 포함됩니다. 반환된 목록을 스크롤하여 만든 검색 매개 변수를 찾을 수 있습니다. 이 명령을 실행해도 FHIR 서버의 동작은 변경되지 않습니다.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
예를 들어 환자에 대한 모든 검색 매개 변수를 찾으려면 다음을 사용합니다.
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
결과는 다음과 같습니다.
{
"resourceType": "Parameters",
"id": "8be24e78-b333-49da-a861-523491c3437a",
"meta": {
"versionId": "1"
},
"parameter": [
{
"name": "deceased",
"valueString": "http://hl7.org/fhir/special-values|false"
},
{
"name": "language",
"valueString": "urn:ietf:bcp:47|en-US"
},
{
"name": "race",
"valueString": "2028-9"
},
...
검색 매개 변수가 예상대로 표시되는 것을 확인하면 단일 리소스를 다시 인덱싱하여 요소로 검색을 테스트할 수 있습니다. 먼저 단일 리소스를 다시 인덱싱합니다.
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
이를 실행하면 해당 리소스 종류에 대해 정의한 특정 리소스의 검색 매개 변수에 대한 인덱스가 설정됩니다. 이렇게 하면 FHIR 서버가 업데이트됩니다. 이제 부분 인덱스 사용 헤더를 검색하고 true로 설정할 수 있습니다. 즉, 해당 형식의 모든 리소스가 인덱싱되지 않더라도 검색 매개 변수가 인덱싱된 리소스가 있는 결과를 반환합니다.
이 예제를 계속 진행하면 다음과 같이 한 명의 환자를 인덱싱하여 US Core Race SearchParameter 를 사용하도록 설정할 수 있습니다.
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
그런 다음 특정 인종을 가진 환자를 검색합니다.
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
검색 매개 변수가 예상대로 작동하는지 확인했으면 프로덕션 사용 사례에 대해 FHIR 서버에서 검색 매개 변수를 사용할 수 있도록 다시 인덱스 작업을 실행하거나 예약합니다.
검색 매개 변수 업데이트
검색 매개 변수를 업데이트하려면 검색 매개 변수의 새 버전을 만드는 데 사용합니다 PUT . 요청 본문 PUT 의 요소와 호출에 PUT 포함 SearchParameter ID id 해야 합니다.
참고 항목
검색 매개 변수의 ID를 모르는 경우 검색할 수 있습니다. 사용하면 GET {{FHIR_URL}}/SearchParameter 모든 사용자 지정 검색 매개 변수가 반환되고 목록을 스크롤하여 필요한 검색 매개 변수를 찾을 수 있습니다. 이름으로 검색을 제한할 수도 있습니다. 다음 예제에서는 .를 사용하여 USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRace이름을 검색할 수 있습니다.
PUT {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
{
"resourceType" : "SearchParameter",
"id" : "SearchParameter ID",
"url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
"version" : "3.1.1",
"name" : "USCoreRace",
"status" : "active",
"date" : "2019-05-21",
"publisher" : "US Realm Steering Committee",
"contact" : [
{
"telecom" : [
{
"system" : "other",
"value" : "http://www.healthit.gov/"
}
]
}
],
"description" : "New Description!",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "US",
"display" : "United States of America"
}
]
}
],
"code" : "race",
"base" : [
"Patient"
],
"type" : "token",
"expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}
결과는 업데이트 SearchParameter 되고 버전이 증가합니다.
Warning
데이터베이스에서 이미 인덱싱된 SearchParameters를 업데이트할 때는 주의해야 합니다. 기존 SearchParameter의 동작을 변경하면 예상 동작에 영향을 미칠 수 있습니다. 다시 인덱스 작업을 즉시 실행하는 것이 좋습니다.
검색 매개 변수 삭제
검색 매개 변수를 삭제해야 하는 경우 다음을 사용합니다.
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Warning
데이터베이스에서 이미 인덱싱된 SearchParameters를 삭제할 때는 주의해야 합니다. 기존 SearchParameter의 동작을 변경하면 예상 동작에 영향을 미칠 수 있습니다. 다시 인덱스 작업을 즉시 실행하는 것이 좋습니다.
다음 단계
이 문서에서는 검색 매개 변수를 만드는 방법을 알아보았습니다. 다음으로 FHIR 서버를 다시 인덱싱하는 방법을 알아볼 수 있습니다.
참고 항목
FHIR®은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.