Azure API for FHIR에서 다시 인덱스 작업 실행

아티클
10/04/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의 진화된 버전입니다.

아직 인덱싱되지 않은 Azure API for FHIR®에 검색 또는 정렬 매개 변수가 있을 수 있는 시나리오가 있습니다. 이 시나리오는 사용자 고유의 검색 매개 변수를 정의할 때 관련이 있습니다. 검색 매개 변수가 인덱싱될 때까지 검색에 사용할 수 없습니다. 이 문서에서는 다시 인덱스 작업을 실행하여 FHIR 서비스 데이터베이스에서 검색 매개 변수를 인덱싱하는 방법을 설명합니다.

Warning

시작하기 전에 이 전체 문서를 읽는 것이 중요합니다. 다시 인덱스 작업은 성능이 매우 많이 사용될 수 있습니다. 이 문서에는 다시 인덱스 작업을 제한하고 제어하는 방법에 대한 옵션이 포함되어 있습니다.

재색인 작업 실행 방법

전체 FHIR 서비스 데이터베이스 및 특정 사용자 지정 검색 매개 변수에 대해 다시 인덱스 작업을 실행할 수 있습니다.

전체 FHIR 서비스 데이터베이스에서 다시 인덱스 작업 실행

다시 인덱스 작업을 실행하려면 요청 본문에서 JSON 형식 Parameters 의 리소스와 함께 다음 POST 호출을 사용합니다.

POST {{FHIR URL}}/$reindex 

{ 

“resourceType”: “Parameters”,  

“parameter”: [] 

}

"parameter": [] 다시 인덱스 작업에 할당된 리소스를 조정할 필요가 없는 경우(표시된 대로) 필드를 비워 둡니다.

요청이 성공하면 다음 예제와 같이 응답의 리소스 외 Parameters 에 201 만든 상태 코드가 표시됩니다.

HTTP/1.1 201 Created 
Content-Location: https://{{FHIR URL}}/_operations/reindex/560c7c61-2c70-4c54-b86d-c53a9d29495e 

{
  "resourceType": "Parameters",
  "id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
  "meta": {
    "versionId": "\"4c0049cd-0000-0100-0000-607dc5a90000\""
  },
  "parameter": [
    {
      "name": "id",
      "valueString": "560c7c61-2c70-4c54-b86d-c53a9d29495e"
    },
    {
       "name": "lastModified",
       "valueDateTime": "2023-06-08T04:52:44.0974408+00:00"
    },
    {
       "name": "queuedTime",
       "valueDateTime": "2023-06-08T04:52:44.0974406+00:00"
    },
    {
       "name": "totalResourcesToReindex",
       "valueDecimal": 0.0
    },
    {
       "name": "resourcesSuccessfullyReindexed",
       "valueDecimal": 0.0
    },
    {
       "name": "progress",
       "valueDecimal": 0.0
    },
    {
       "name": "status",
       "valueString": "Queued"
    },
    {
       "name": "maximumConcurrency",
       "valueDecimal": 3.0
    },
    {
        "name": "queryDelayIntervalInMilliseconds",
        "valueDecimal": 500.0
    },
    {
        "name": "maximumNumberOfResourcesPerQuery",
        "valueDecimal": 100.0
    }
  ]
}

특정 사용자 지정 검색 매개 변수에 대해 다시 인덱스 작업 실행

특정 사용자 지정 검색 매개 변수에 대해 다시 인덱스 작업을 실행하려면 요청 본문에서 JSON 형식 Parameters 리소스와 함께 다음 POST 호출을 사용합니다.

POST {{FHIR_URL}}/$reindex 
content-type: application/fhir+json
{ 

"resourceType": "Parameters",  

"parameter": [
    {
      "name": "targetSearchParameterTypes",
      "valueString": "{url of custom search parameter. In case of multiple custom search parameters, url list can be comma seperated.}"
    }
] 

}

참고 항목

다시 인덱스 작업의 상태를 확인하거나 작업을 취소하려면 다시 인덱스 ID가 필요합니다. 응답에서 반환된 값에 "parameter" 전달된 값입니다"id". 앞의 예제에서 다시 인덱스 작업의 ID는 다음과 같습니다 560c7c61-2c70-4c54-b86d-c53a9d29495e.

다시 인덱스 작업의 상태를 확인하는 방법

다시 인덱스 작업을 시작하면 다음 호출을 사용하여 작업의 상태를 확인할 수 있습니다.

GET {{FHIR URL}}/_operations/reindex/{{reindexJobId}

다음은 응답 예제입니다.

{
    "resourceType": "Parameters",
    "id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
    "meta": {
        "versionId": "138087"
    },
    "parameter": [
        {
            "name": "id",
            "valueString": "560c7c61-2c70-4c54-b86d-c53a9d29495e"
        },
        {
            "name": "startTime",
            "valueDateTime": "2023-06-08T04:54:53.2943069+00:00"
        },
        {
            "name": "endTime",
            "valueDateTime": "2023-06-08T04:54:54.4052272+00:00"
        },
        {
            "name": "lastModified",
            "valueDateTime": "2023-06-08T04:54:54.4053002+00:00"
        },
        {
            "name": "queuedTime",
            "valueDateTime": "2023-06-08T04:52:44.0974406+00:00"
        },
        {
            "name": "totalResourcesToReindex",
            "valueDecimal": 2.0
        },
        {
            "name": "resourcesSuccessfullyReindexed",
            "valueDecimal": 2.0
        },
        {
            "name": "progress",
            "valueDecimal": 100.0
        },
        {
            "name": "status",
            "valueString": "Completed"
        },
        {
            "name": "maximumConcurrency",
            "valueDecimal": 3.0
        },
        {
            "name": "resources",
            "valueString": "{{LIST_OF_IMPACTED_RESOURCES}}"
        },
        {
            "name": "resourceReindexProgressByResource (CountReindexed of Count)",
            "valueString": "{{RESOURCE_TYPE:REINDEXED_COUNT OF TOTAL_COUNT}}"
        },
        {
            "name": "searchParams",
            "valueString": "{{LIST_OF_SEARCHPARAM_URLS}}h"
        },
        {
            "name": "queryDelayIntervalInMilliseconds",
            "valueDecimal": 500.0
        },
        {
            "name": "maximumNumberOfResourcesPerQuery",
            "valueDecimal": 100.0
        }
    ]
}

응답에 다음 정보가 표시됩니다.

totalResourcesToReindex: 이 작업에서 다시 인덱싱되는 총 리소스 수를 포함합니다.
resourcesSuccessfullyReindexed: 이 작업에서 이미 다시 인덱싱된 총 리소스 수입니다.
progress: 작업 비율을 다시 인덱싱합니다. x 100으로 resourcesSuccessfullyReindexed/totalResourcesToReindex 계산됩니다.
status: 다시 인덱스 작업이 큐에 대기, 실행 중, 완료, 실패 또는 취소되었는지 여부를 나타냅니다.
resources: 다시 인덱스 작업의 영향을 받는 모든 리소스 유형을 나열합니다.
resourceReindexProgressByResource (CountReindexed of Count): 리소스 종류별로 총 개수의 다시 인덱싱된 수를 제공합니다. 특정 리소스 종류에 대한 다시 인덱싱이 큐에 대기 중인 경우 Count만 제공됩니다.
searchParams: 다시 인덱스 작업의 영향을 받는 검색 매개 변수의 URL을 나열합니다.

다시 인덱스 작업 삭제

다시 인덱스 작업을 취소해야 하는 경우 삭제 호출을 사용하고 다시 인덱스 작업 ID를 지정합니다.

Delete {{FHIR URL}}/_operations/reindex/{{reindexJobId}

성능 고려 사항

다시 인덱스 작업은 성능이 매우 많이 사용될 수 있습니다. 데이터베이스에서 다시 인덱스 작업이 실행되는 방식을 관리하는 데 도움이 되는 몇 가지 제한 컨트롤을 구현했습니다.

참고 항목

다시 인덱스 작업이 며칠 동안 실행되는 것은 대용량 데이터 세트에서 드문 일이 아닙니다. 리소스가 30,000,000개인 데이터베이스의 경우 전체 데이터베이스를 다시 인덱싱하는 데 100,000RU(요청 단위)에서 4-5일이 걸린 것으로 나타났습니다.

다음은 사용 가능한 매개 변수, 기본값 및 권장 범위를 요약한 표입니다. 이러한 매개 변수를 사용하여 프로세스 속도를 향상시키거나(더 많은 컴퓨팅 사용) 프로세스 속도를 늦출 수 있습니다(더 적은 컴퓨팅 사용). 예를 들어 트래픽이 적은 시간에 다시 인덱스 작업을 실행하고 컴퓨팅을 늘려 더 빨리 완료할 수 있습니다. 설정을 사용하여 컴퓨팅 사용량이 적고 백그라운드에서 며칠 동안 실행되도록 할 수도 있습니다.

매개 변수	설명	기본값	사용 가능한 범위
QueryDelayIntervalInMilliseconds	다시 인덱싱 작업 중에 시작되는 리소스의 각 일괄 처리 간의 지연입니다. 숫자가 작을수록 작업 속도가 빨라지고 숫자가 높을수록 속도가 느려집니다.	500MS(.5초)	50-500000
MaximumResourcesPerQuery	다시 인덱싱할 리소스 일괄 처리에 포함된 최대 리소스 수입니다.	100	1-5000
MaximumConcurrency	한 번에 수행되는 일괄 처리 수입니다.	1	1-10
targetDataStoreUsagePercentage	다시 인덱스 작업에 사용할 데이터 저장소의 백분율을 지정할 수 있습니다. 예를 들어 50%를 지정할 수 있으며, 이를 통해 최대 다시 인덱스 작업에서 Azure Cosmos DB에서 사용 가능한 RU의 50%를 사용할 수 있습니다.	존재하지 않습니다. 즉, 최대 100%를 사용할 수 있습니다.	0-100

위의 매개 변수를 사용하려는 경우 다시 인덱스 작업을 시작할 때 매개 변수 리소스에 전달할 수 있습니다.

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "maximumConcurrency",
      "valueInteger": "3"
    },
    {
      "name": "targetDataStoreUsagePercentage",
      "valueInteger": "20"
    },
    {
      "name": "queryDelayIntervalInMilliseconds",
      "valueInteger": "1000"
    },
    {
      "name": "maximumNumberOfResourcesPerQuery",
      "valueInteger": "1"
    }
  ]
}

다음 단계

이 문서에서는 다시 인덱스 작업을 시작하는 방법을 알아보았습니다. 다시 인덱스 작업이 필요한 새 검색 매개 변수를 정의하는 방법을 알아보려면 다음을 참조하세요.

사용자 지정 검색 매개 변수 정의

참고 항목

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

다음을 통해 공유

Azure API for FHIR에서 다시 인덱스 작업 실행

재색인 작업 실행 방법

전체 FHIR 서비스 데이터베이스에서 다시 인덱스 작업 실행

특정 사용자 지정 검색 매개 변수에 대해 다시 인덱스 작업 실행

다시 인덱스 작업의 상태를 확인하는 방법

다시 인덱스 작업 삭제

성능 고려 사항

다음 단계

피드백

추가 리소스