Azure API for FHIR에 대한 사용자 지정 검색 매개 변수 정의

FHIR®(Fast Healthcare Interoperability Resources) 사양은 리소스와 관련된 모든 리소스 및 검색 매개 변수에 대한 검색 매개 변수 집합을 정의합니다. 그러나 FHIR 사양에 의해 표준 검색 매개 변수로 정의되지 않은 리소스의 요소에 대해 검색할 수 있는 시나리오가 있습니다. 이 문서에서는 Azure API for 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"
}

중요한 요소는 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 해야 합니다.

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 되고 버전이 증가합니다.

검색 매개 변수 삭제

검색 매개 변수를 삭제해야 하는 경우 다음을 사용합니다.

Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}

다음 단계

이 문서에서는 검색 매개 변수를 만드는 방법을 알아보았습니다. 다음으로 FHIR 서버를 다시 인덱싱하는 방법을 알아볼 수 있습니다.