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®(Fast Healthcare Interoperability Resources) 검색 작업을 사용하는 예제입니다 POST . 검색에 대한 자세한 내용은 FHIR 검색 개요를 참조하세요.
검색 결과 매개 변수
_포함하다
_include 는 리소스의 지정된 매개 변수를 포함하는 리소스를 검색합니다. 예를 들어 리소스를 검색 MedicationRequest 하여 매개 변수patient인 특정 환자의 reference 처방전에 대한 정보를 포함하는 리소스만 찾을 수 있습니다. 다음 예제에서는 에서 참조MedicationRequests되는 모든 MedicationRequests 환자와 모든 환자를 끌어온다.
GET [your-fhir-server]/MedicationRequest?_include=MedicationRequest:patient
참고 항목
_include 및 _revinclude 100개 항목으로 제한됩니다.
_revinclude
_revinclude 를 사용하면 반대 방향을 .로 _include검색할 수 있습니다. 예를 들어 환자를 검색한 다음 환자를 참조하는 모든 만남을 역방향으로 포함할 수 있습니다.
GET [your-fhir-server]/Patient?_revinclude=Encounter:subject
_요소
_elements 는 불필요한 데이터를 생략하여 응답 크기를 줄이기 위해 검색 결과를 필드의 하위 집합으로 좁혀 줍니다. 매개 변수는 기본 요소의 쉼표로 구분된 목록을 허용합니다.
GET [your-fhir-server]/Patient?_elements=identifier,active
이 요청에서 각 리소스에 식별자 및 환자의 활성 상태만 포함된 환자 번들이 제공됩니다. 이 응답의 SUBSETTED 리소스에는 불완전한 결과 집합임을 나타내는 값이 포함됩니다meta.tag.
검색 한정자
:안
:not 을 사용하면 특성이 true가 아닌 리소스를 찾을 수 있습니다. 예를 들어 성별이 여성이 아닌 환자를 검색할 수 있습니다.
GET [your-fhir-server]/Patient?gender:not=female
반환 값으로, 빈 값(성별 없이 지정된 항목)을 포함하여 성별이 여성이 아닌 모든 환자 항목을 가져옵니다. 이것은 특정 성별이 없는 항목을 포함하지 않기 때문에 성별이 남성인 환자를 검색하는 것과 다릅니다.
:없어진
:missing 는 값이 있을 때 지정된 요소에 대한 값이 없는 모든 리소스를 반환하고 값이 true있으면 지정된 요소를 포함하는 모든 리소스를 false반환합니다. 단순 데이터 형식 요소 :missing=true 의 경우 요소가 확장과 함께 있지만 빈 값이 있는 모든 리소스에서 일치합니다. 다음 예제에서는 생년월일에 누락된 모든 Patient 리소스를 찾는 방법을 보여 줍니다.
GET [your-fhir-server]/Patient?birthdate:missing=true
:정확한
:exact 는 매개 변수에 string 사용되며 대/소문자 연결과 같이 매개 변수와 정확하게 일치하는 결과를 반환합니다.
GET [your-fhir-server]/Patient?name:exact=Jon
이 요청은 이름이 정확히 같은 리소스를 Jon반환 Patient 합니다. 리소스에 이름이 같은 Jonathan joN환자가 있는 경우 지정된 값과 정확히 일치하지 않으므로 검색에서 리소스를 무시하고 건너뜁니다.
:포함
:contains 는 매개 변수에 string 사용되며 검색되는 필드 내의 문자열에서 지정된 값의 부분 일치 항목이 있는 리소스를 검색합니다. contains 은 대/소문자를 구분하지 않으며 문자 연결이 허용됩니다. 예시:
GET [your-fhir-server]/Patient?address:contains=Meadow
이 요청은 "Meadow" 문자열을 address 포함하는 값이 있는 필드가 있는 모든 Patient 리소스를 반환합니다. 즉, 검색 결과로 반환된 "Meadowers" 또는 "59 Meadow ST"와 같은 값을 포함하는 주소를 가질 수 있습니다.
연결된 검색
여러 참조 매개 변수를 포함하는 일련의 검색 작업을 수행하려면 마침표 .로 일련의 참조 매개 변수를 서버 요청에 하나씩 추가하여 "연결"할 수 있습니다. 예를 들어 특정 name리소스를 포함하는 리소스에 대한 참조를 사용하여 subject 모든 DiagnosticReport 리소스를 Patient 보려면 다음을 수행합니다.
GET [your-fhir-server]/DiagnosticReport?subject:Patient.name=Sarah
이 요청은 "Sarah"라는 환자 주체가 있는 모든 DiagnosticReport 리소스를 반환합니다. 필드 Patient 가 매개 변수의 참조 매개 변수에 대해 연결된 검색을 수행한 후의 기간 . 입니다subject.
정기적 인 검색 (체인 검색이 아님)의 또 다른 일반적인 사용은 특정 환자에 대한 모든 만남을 찾는 것입니다. Patient에는 제목이 있는 하나 이상의 Encounters가 있는 경우가 많습니다. 다음은 제공된 리소스에 대한 모든 Encounter 리소스를 Patient 검색합니다 id.
GET [your-fhir-server]/Encounter?subject=Patient/78a14cbe-8968-49fd-a231-d43e6619399f
연결된 검색을 사용하여 특정 Patient 정보와 일치하는 모든 Encounter 리소스(예: birthdate.)를 찾을 수 있습니다.
GET [your-fhir-server]/Encounter?subject:Patient.birthdate=1987-02-20
이렇게 하면 지정된 생년월일 값이 있는 모든 환자에서 리소스를 검색 Encounter 할 수 있습니다.
또한 하나의 요청에서 여러 조건을 검색할 수 있는 기호 &를 사용하여 연결 검색을 한 요청에서 두 번 이상 수행할 수 있습니다. 이러한 경우 연결된 검색은 모든 조건만 한 번에 충족하는 조건을 검색하는 대신 각 매개 변수를 "독립적으로" 검색합니다.
GET [your-fhir-server]/Patient?general-practitioner:Practitioner.name=Sarah&general-practitioner:Practitioner.address-state=WA
이렇게 하면 "Sarah"generalPractitioner가 있는 모든 Patient 리소스가 반환되고 generalPractitioner 주 WA와 주소가 있는 리소스가 반환됩니다. 즉, 환자가 주 NY에서 사라를 가지고 있고 주 WA의 빌이 모두 환자의 generalPractitioner것으로 참조되면 둘 다 반환됩니다.
검색이 모든 조건을 그룹으로 포함하는 작업이어야 AND 하는 시나리오의 경우 복합 검색의 예제를 참조하세요.
역방향 체인 검색
체인 검색을 사용하면 참조하는 리소스의 속성에 따라 리소스를 검색할 수 있습니다. 역방향 체인 검색을 사용하면 다른 방법으로 이 작업을 수행할 수 있습니다. 매개 변수를 사용하여 _has 해당 리소스를 참조하는 리소스의 속성을 기반으로 리소스를 검색할 수 있습니다. 예를 들어 리소스에는 Observation 환자 리소스를 참조하는 검색 매개 변수 patient 가 있습니다. 다음을 사용하여 특정 code환자 리소스에서 참조하는 Observation 모든 환자 리소스를 찾습니다.
GET [base]/Patient?_has:Observation:patient:code=527
이 요청은 코드527로 참조되는 Observation 환자 리소스를 반환합니다.
또한 역방향 체인 검색에는 재귀 구조가 있을 수 있습니다. 예를 들어 다음에서는 관찰에 Observation 특정 사용자의 janedoe감사 이벤트가 있는 모든 환자를 검색합니다.
GET [base]/Patient?_has:Observation:patient:_has:AuditEvent:entity:agent:Practitioner.name=janedoe
참고 항목
Azure Cosmos DB에서 지원되는 Azure API for FHIR 및 오픈 소스 FHIR 서버에서 연결된 검색 및 역방향 체인 검색은 MVP 구현입니다. Azure Cosmos DB에서 연결된 검색을 수행하기 위해 구현은 검색 식을 안내하고 하위 쿼리를 실행하여 일치하는 리소스를 확인합니다. 이 작업은 식의 각 수준에 대해 수행됩니다. 쿼리가 100개 이상의 결과를 반환하면 오류가 throw됩니다.
복합 검색
한 번에 여러 조건을 충족하는 리소스를 검색하려면 단일 매개 변수 값 시퀀스를 기호 $와 조인하는 복합 검색을 사용합니다. 결과는 조인된 검색 매개 변수로 지정된 모든 조건과 일치하는 리소스의 교집합이 됩니다. 이러한 검색 매개 변수를 복합 검색 매개 변수라고 하며 중첩된 구조에서 여러 매개 변수를 결합하는 새 매개 변수를 정의합니다. 예를 들어 다음 검색에서는 칼륨 값이 Observation 9.2보다 작거나 같은 모든 DiagnosticReport 리소스를 찾습니다.
GET [your-fhir-server]/DiagnosticReport?result.code-value-quantity=2823-3$lt9.2
이 요청은 코드 2823-3가 포함된 구성 요소를 지정합니다. 이 경우 칼륨이 됩니다. 기호 다음에 $ 는 "작거나 같음" 및 9.2 칼륨 값 범위에 사용하는 lt 구성 요소의 값 범위를 지정합니다.
다음 항목 집합 검색
단일 검색 쿼리당 반환할 수 있는 최대 항목 수는 1000개입니다. 검색 쿼리와 일치하는 항목이 1,000개 이상인 경우 다음 절차를 사용하여 1000보다 큰 항목을 볼 수 있습니다.
다음 Bundle 결과와 searchset같이 연속 토큰 url 값을 사용합니다.
"resourceType": "Bundle",
"id": "98731cb7-3a39-46f3-8a72-afe945741bd9",
"meta": {
"lastUpdated": "2021-04-22T09:58:16.7823171+00:00"
},
"type": "searchset",
"link": [
{
"relation": "next",
"url": "[your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd"
},
{
"relation": "self",
"url": "[your-fhir-server]/Patient?_sort=_lastUpdated"
}
],
그런 다음, 필드에서 제공된 URL에 대한 GET 요청을 수행합니다 relation: next.
GET [your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd
그러면 검색 결과에 대한 다음 항목 집합이 반환됩니다. 검색 searchset 결과 항목의 전체 집합이며 연속 토큰 url 은 처음 1000에 표시되지 않는 항목을 검색하기 위해 서버에서 제공하는 링크입니다.
POST를 사용하여 검색
이전에 언급한 모든 검색 예제는 사용된 GET 요청입니다. 을 사용하여 _search요청을 사용하여 POST 검색 작업을 수행할 수도 있습니다.
POST [your-fhir-server]/Patient/_search?_id=45
이 요청은 값이 45인 리소스를 id 반환 Patient 합니다. GET 요청과 마찬가지로 서버는 조건을 충족하는 리소스 집합을 결정하고 HTTP 응답에서 번들 리소스를 반환합니다.
쿼리 매개 변수가 양식 본문으로 제출되는 POST를 사용하여 검색하는 또 다른 예는 다음과 같습니다.
POST [your-fhir-server]/Patient/_search
content-type: application/x-www-form-urlencoded
name=John
다음 단계
이 문서에서는 다양한 검색 매개 변수, 한정자 및 FHIR 검색 도구를 사용하여 검색하는 방법을 알아보았습니다. FHIR 검색에 대한 자세한 내용은
참고 항목
FHIR®은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.