在 Azure API for FHIR 中執行重新編制索引作業

發行項
06/08/2023

在某些情況下，您可能會在尚未編制索引的 Azure API for FHIR 中搜尋或排序參數。當您定義自己的搜尋參數時，此案例會相關。在搜尋參數編制索引之前，無法在搜尋中使用。本文涵蓋如何執行重新索引作業，以索引尚未在 FHIR 服務資料庫中編制索引的搜尋參數。

警告

開始之前，請務必先閱讀此整篇文章。重新編制索引作業可能會非常耗用效能。本文包含如何節流和控制重新編制索引作業的選項。

如何執行重新索引作業

重新編制索引作業可以針對整個 FHIR 服務資料庫和特定的自訂搜尋參數執行。

在整個 FHIR 服務資料庫上執行重新編制索引作業

若要執行重新編制索引作業，請使用下列 POST 呼叫搭配要求本文中的 JSON 格式化 Parameters 資源：

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
    }
  ]
}

針對特定自訂搜尋參數執行重新編制索引作業

若要針對特定自訂搜尋參數執行重新編制索引作業，請使用下列 POST 呼叫搭配要求本文中的 JSON 格式化 Parameters 資源：

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" 。在上述範例中，重新索引作業的識別碼會是 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：完成重新編制作業百分比的索引。 resourcesSuccessfullyReindexed/totalResourcesToReindex 等於 x 100。
status：如果重新索引作業已排入佇列、執行中、完成、失敗或取消，則為狀態。
resources：列出受重新編制索引作業影響的所有資源類型。
'resourceReindexProgressByResource (CountReindexed of Count) '：針對每個資源類型提供總計數的重新編制索引計數。如果特定資源類型的重新編制索引已排入佇列，則只會提供 Count。
'searchParams'：列出受重新編制索引作業影響之搜尋參數的 URL。

刪除重新編制索引作業

如果您需要取消重新編制索引作業，請使用刪除呼叫並指定重新編制索引作業識別碼：

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

效能考量

重新編制索引作業可能會相當耗用效能。我們已實作一些節流控制，以協助您管理重新編制索引作業在資料庫上執行的方式。

注意

在大型資料集上，重新編制索引作業執行天數並不常見。對於具有 30，000，000000 萬個資源的資料庫，我們注意到在 100K RU 之間需要 4-5 天的時間來重新編制整個資料庫的索引。

下表列出可用的參數、預設值和建議範圍。您可以使用這些參數來加速進程， (使用更多計算) ，或讓進程變慢， (使用較少的計算) 。例如，您可以在低流量時間執行重新索引作業，並增加計算以更快完成。相反地，您可以使用設定來確保計算使用量很低，並在背景中執行數天。

參數	說明	預設值	可用範圍
QueryDelayIntervalInMilliseconds	重新編制索引作業期間開始每個資源批次之間的延遲。較小的數位會加速作業，而較高的數位會降低作業速度。	500 MS (.5 秒)	50-500000
MaximumResourcesPerQuery	要重新編制索引的資源批次中包含的資源數目上限。	100	1-5000
MaximumConcurrency	一次完成的批次數目。	1	1 - 10
targetDataStoreUsagePercentage	可讓您指定要用於重新編制索引作業的資料存放區百分比。例如，您可以指定 50% ，以確保最多重新編制索引作業會在 Azure Cosmos DB 上使用 50% 的可用 RU。	不存在，這表示最多可以使用 100%。	0-100

如果您想要使用上述任何參數，您可以在啟動重新編制索引作業時將它們傳遞至 Parameters 資源。

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

下一步

在本文中，您已瞭解如何開始重新編制索引作業。若要瞭解如何定義需要重新編制索引作業的新搜尋參數，請參閱

定義自訂搜尋參數

FHIR® 是 HL7 的注冊商標，並搭配 HL7 的許可權使用。