定義 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 和醫療技術服務。

Fast Healthcare 互操作性資源（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 時，請小心。變更現有的 SearchParameter 行為可能會影響預期的行為。建議您立即執行重新編製索引作業。

下一步

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

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

注意

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

共用方式為

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

建立新的搜尋參數

測試搜尋參數

更新搜尋參數

刪除搜尋參數

下一步

意見反應

其他資源