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

發行項
10/04/2024

重要

Azure API for FHIR 將於 2026 年 9 月 30 日淘汰。 請依照移轉策略，在該日期前轉換至 Azure 健康資料服務 FHIR® 服務。由於 Azure API for FHIR 已淘汰，因此從 2025 年 4 月 1 日開始，將不允許新的部署。 Azure 健康資料服務 FHIR 服務是 Azure API for FHIR 的進化版本，可讓客戶透過與其他 Azure 服務整合來管理 FHIR、DICOM 和醫療技術服務。

在某些情況下，您可能在尚未編製索引的 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 separated.}"
    }
] 

}

注意

若要檢查重新編製索引作業的狀態或取消作業，您需要重新編製索引標識符。這是 "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,000 個資源的資料庫，我們注意到在 100,000 個要求單位（RU）上需要 4-5 天的時間，才能重新編製整個資料庫的索引。

下表概述可用的參數、預設值和建議範圍。您可以使用這些參數來加速程式（使用更多計算）或降低程式速度（使用較少的計算）。例如，您可以在低流量時間執行重新編製索引作業，並增加計算，使其更快完成。您也可以使用設定來確保計算使用量低，並在背景中執行數天。

參數	說明	Default	可用的範圍
QueryDelayIntervalInMilliseconds	重新編製索引作業期間開始每個資源批次之間的延遲。較小的數位會加速工作，而較高的數位會降低作業速度。	500 毫秒（.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 的許可下使用。

共用方式為