定義自訂搜尋參數

發行項
10/16/2024

FHIR® 規格會定義一組套用至所有資源的搜尋參數。此外，FHIR 會定義特定資源特有的許多搜尋參數。不過，您可能也想要搜尋 FHIR 規格未定義為標準搜尋參數之資源中的元素。本文說明如何定義自己的自定義搜尋參數，以在 Azure Health Data Services 的 FHIR 服務中使用。

注意

每次建立、更新或刪除搜尋參數時，都必須執行重新編製索引作業，以啟用即時生產環境的搜尋參數。我們將概述如何在重新編製下列整個 FHIR 服務資料庫的索引之前，先測試搜尋參數。

建立新的搜尋參數

若要建立新的搜尋參數，您需要 POST SearchParameter FHIR 服務資料庫的資源。

POST {{FHIR_URL}}/SearchParameter

下列範例示範如何建立新的自定義搜尋參數。

在實作指南中為每個定義建立新的搜尋參數

下列程式代碼範例示範如何將US Core Race 搜尋參數新增至 Patient FHIR 服務資料庫中的資源類型。

{
  "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"
}

為參考類型的資源屬性建立新的搜尋參數

下列程式代碼範例示範如何建立自定義搜尋參數，以根據其分配位置來搜尋MedicationDispense資源。這是為參考類型新增自定義搜尋參數的範例。

{
 "resourceType": "SearchParameter",
  "id": "a3c28d46-fd06-49ca-aea7-5f9314ef0497",
  "url": "{{An absolute URI that is used to identify this search parameter}}",
  "version": "1.0",
  "name": "MedicationDispenseLocationSearchParameter",
  "status": "active",
  "description": "Search parameter for MedicationDispense by location",
  "code": "location",
  "base": ["MedicationDispense"],
  "target": ["Location"],
  "type": "reference",
  "expression": "MedicationDispense.location"
}

注意

當您將搜尋參數重新編製資料庫索引之後POST，新的搜尋參數會出現在 FHIR 服務的功能語句中。 SearchParameter在功能語句中檢視是判斷 FHIR 服務是否支援搜尋參數的唯一方法。如果您在 capability 語句中找不到 SearchParameter ，您仍然需要重新編製資料庫索引以啟動搜尋參數。 POST您可以在觸發重新索引作業之前，先有多個搜尋參數。

資源的重要元素 SearchParameter 包括：

url：描述搜尋參數的唯一索引鍵。 HL7 等組織會針對他們定義的搜尋參數使用標準 URL 格式，如美國核心競賽搜尋參數所示。
code：儲存在 程式代碼 專案中的值是 API 呼叫中包含搜尋參數時，用於搜尋參數的名稱。針對上述使用「US Core Race」延伸模組的範例，您會使用 GET {{FHIR_URL}}/Patient?race=<code> 從指定的編碼系統設定的值中搜尋 where <code> 。這個呼叫會擷取特定種族的所有患者。
base：描述搜尋參數適用的資源類型。如果搜尋參數套用至所有資源，您可以使用 Resource;否則，您可以列出所有相關的資源類型。
target：描述搜尋參數符合哪些資源類型。
type：描述搜尋參數的數據類型。類型受限於 FHIR 服務中數據類型的支援。這表示您無法定義特殊類型的搜尋參數，或定義複合搜尋參數，除非它是支持的組合。
expression：描述如何計算搜尋的值。在描述搜尋參數時，即使規格不需要表達式，您也必須包含表達式。這是因為您需要表達式或 xpath 語法，而 FHIR 服務會忽略 xpath 語法。

測試新的搜尋參數

雖然在您執行重新編製索引作業之前，無法在生產環境中使用新的搜尋參數，但在重新編製整個資料庫索引之前，有一些方法可以測試自定義搜尋參數。

首先，您可以測試新的搜尋參數，以查看傳回的值。藉由針對特定資源實例執行下列命令（藉由提供資源識別符），您可以取得值組清單，其中包含搜尋參數名稱和儲存在對應元素中的值。此清單包含資源的所有搜尋參數。您可以捲動以尋找您所建立的搜尋參數。執行此命令不會變更 FHIR 服務中的任何行為。

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOURCE_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

執行此 POST 呼叫會設定針對要求中指定的資源實例所定義之任何搜尋參數的索引。此呼叫會變更 FHIR 服務資料庫。現在您可以將標頭搜尋並設定 x-ms-use-partial-indices 為 true，這會導致 FHIR 服務傳回任何已編製搜尋參數索引之資源的結果，即使該類型的所有資源實例都沒有編製索引也一樣。

繼續我們的範例，您可以編制一個病患的索引以啟用 SearchParameter：

POST {{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

然後執行測試搜尋：

針對患者進行種族：

GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true

位置（參考類型）

{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

在您測試新的搜尋參數並確認其如預期般運作之後，請執行或排程重新編製索引作業，讓新的搜尋參數可用於即時生產環境。

如需如何重新編製 FHIR 服務資料庫索引的資訊，請參閱執行重新編製索引作業。

更新搜尋參數

若要更新搜尋參數，請使用 PUT 來建立新版的搜尋參數。您必須在要求PUT主體PUT和要求字串的欄位中包含搜尋參數識別碼id。

注意

如果您不知道搜尋參數的標識碼，您可以使用來搜尋。GET {{FHIR_URL}}/SearchParameter 這會傳回所有自定義和標準搜尋參數。您可以捲動清單，以尋找所需的搜尋參數。您也可以依名稱限制搜尋。如下列範例要求所示，自定義 SearchParameter 資源實例的名稱為 USCoreRace。您可以使用來依名稱GET {{FHIR_URL}}/SearchParameter?name=USCoreRace搜尋此SearchParameter資源。

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 服務資料庫的索引。如需更多資訊，請參閱

如何執行重新編製索引作業

注意

FHIR® 是 HL7 的註冊商標，在 HL7 的許可下使用。

共用方式為