定義 Azure API for FHIR 的自訂搜尋參數

發行項
06/01/2023

快速醫療保健互通性資源 (FHIR®) 規格會針對 (資源) 特定的所有資源和搜尋參數定義一組搜尋參數。不過，在某些情況下，您可能會想要搜尋資源中未由 FHIR 規格定義為標準搜尋參數的專案。本文說明如何定義自己的搜尋參數，以用於 Azure API for FHIR。

注意

每次建立、更新或刪除搜尋參數時，都必須執行重新編制索引作業，才能在生產環境中使用搜尋參數。下面我們將概述如何在重新編制整個 FHIR 伺服器的索引之前測試搜尋參數。

建立新的搜尋參數

若要建立新的搜尋參數，請將 POSTSearchParameter 資源提供給資料庫。下列程式碼範例示範如何將 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"
}

注意

當您將搜尋參數 POST 至資料庫並 重新編制資料庫索引之後，新的搜尋參數會出現在 FHIR 伺服器的功能語句中。 SearchParameter在功能語句中檢視是判斷 FHIR 伺服器是否支援搜尋參數的唯一方式。如果您可以搜尋搜尋參數來尋找搜尋參數，但無法在功能語句中看到它，您仍然需要編制搜尋參數的索引。您可以在觸發重新索引作業之前 POST 多個搜尋參數。

的重要元素 SearchParameter ：

url：描述搜尋參數的唯一索引鍵。許多組織，例如 HL7，會針對他們定義的搜尋參數使用標準 URL 格式，如上述美國核心競爭搜尋參數所示。
code：儲存在程式代碼中的值是您搜尋時將使用的值。針對上述範例，您會搜尋 GET {FHIR_URL}/Patient?race=<code> 以取得特定競賽的所有病患。 (套用搜尋參數的資源) ，程式碼必須是唯一的。
base：描述搜尋參數套用 () 的資源。如果搜尋參數適用于所有資源，您可以使用 Resource ;否則，您可以列出所有相關資源。
type：描述搜尋參數的資料類型。類型受限於 Azure API for FHIR 的支援。這表示您無法定義特殊類型的搜尋參數，或定義複合搜尋參數，除非它是支援的組合。
運算式：描述如何計算搜尋的值。描述搜尋參數時，即使規格不需要運算式，您也必須包含運算式。這是因為您需要運算式或 xpath 語法，而 Azure API for FHIR 會忽略 xpath 語法。

測試搜尋參數

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

首先，您可以測試新的搜尋參數，以查看將傳回哪些值。藉由對特定資源實例執行下列命令， (輸入其識別碼) ，您將會傳回具有搜尋參數名稱的值組清單，以及針對特定病患儲存的值。這將會包含資源的所有搜尋參數，您可以捲動以尋找您所建立的搜尋參數。執行此命令不會變更 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，這表示它會傳回任何資源已編制搜尋參數索引的結果，即使該類型的所有資源都沒有編制索引。

繼續上述範例，您可以為一位病患編制索引，以啟用美國核心競賽 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 來建立新版的搜尋參數。您必須將 SearchParameter IDid 包含在要求主體的 PUT 元素和呼叫中 PUT 。

注意

如果您不知道搜尋參數的識別碼，您可以搜尋它。使用 GET {{FHIR_URL}}/SearchParameter 會傳回所有自訂搜尋參數，而且您可以捲動搜尋參數來尋找您需要的搜尋參數。您也可以依名稱限制搜尋。使用下列範例，您可以使用來搜尋名稱 USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRace 。

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 ，版本將會遞增。

警告

更新已在資料庫中編制索引的 SearchParameters 時，請小心。變更現有 SearchParameter 的行為可能會影響預期的行為。建議您立即執行重新編制索引作業。

刪除搜尋參數

如果您需要刪除搜尋參數，請使用下列專案：

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

警告

刪除已在資料庫中編制索引的 SearchParameters 時，請小心。 Changing an existing SearchParameter’s behavior could have impacts on the expected behavior. We recommend running a reindex job immediately.

下一步

在本文中，您已瞭解如何建立搜尋參數。接下來，您可以瞭解如何重新編制 FHIR 伺服器的索引。

如何執行重新索引作業

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

定義 Azure API for FHIR 的自訂搜尋參數

建立新的搜尋參數

測試搜尋參數

更新搜尋參數

刪除搜尋參數

下一步

其他資源