可選取的搜尋參數 (預覽)

發行項
10/16/2024

重要

可選取的搜尋參數功能可供預覽。預覽 API 和 SDK 在沒有服務等級協定（SLA）的情況下提供。建議您不要將其用於生產工作負載。部分功能可能不受支援，或是在功能上有所限制。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

搜尋資源是 FHIR® 服務的基礎。 FHIR 服務中的每個資源都會以一組元素的形式攜帶資訊。搜尋參數可用來查詢這些項目中的資訊。部署 FHIR 服務時，預設會啟用內建的搜尋參數。 FHIR 服務會在擷取數據期間擷取和編製 FHIR 資源的特定屬性，以執行有效率的搜尋。

可選取的搜尋參數可讓您啟用或停用內建的搜尋參數。這項功能可協助您將更多資源儲存在已配置的儲存空間中，並藉由只啟用所需的搜尋參數來改善效能。

若要對搜尋參數執行狀態更新，請遵循下列步驟：

取得搜尋參數的狀態。
更新搜尋參數的狀態。
執行重新編製索引作業。

在本文中，我們會使用 {{FHIR_URL}} 占位符在 API 呼叫範例中示範 FHIR 搜尋語法，以代表 FHIR 伺服器 URL。

取得搜尋參數的狀態

提供 API 端點（'$status'）來檢視搜尋參數的狀態。回應有四種狀態：

狀態	描述
支援	FHIR 服務支援搜尋參數，而且您提交要求以啟用搜尋參數。執行重新編制索引作業，以從支援的要啟用執行。
已啟用	搜尋參數已啟用進行搜尋。此狀態是支持狀態之後的下一個步驟。
PendingDisable	執行重新索引作業之後，停用搜尋參數會擱置中。
已停用	搜尋參數已停用。

若要取得所有搜尋參數的狀態，請使用下列要求，以傳回所有搜尋參數及其狀態的清單。捲動清單以尋找您需要的搜尋參數。

GET {{FHIR_URL}}/SearchParameter/$status

若要識別個別或搜尋參數子集的狀態，請使用下列篩選條件。

名稱. 若要依名稱識別搜尋參數狀態，請使用此要求。

   GET {{FHIR_URL}}/SearchParameter/$status?code=<name of search parameter/ sub string>

URL。若要依標準標識碼識別搜尋參數狀態，請使用此要求。

GET {{FHIR_URL}}/SearchParameter/$status?url=<SearchParameter url>

資源類型。在 FHIR 中，搜尋參數會在個別資源層級啟用，以允許篩選和擷取特定資源子集。若要識別對應至資源的所有搜尋參數狀態，請使用此要求。

GET {{FHIR_URL}}/SearchParameter/$status?resourcetype=<ResourceType name>

為了回應對$status端點的 GET 要求，參數資源類型會以搜尋參數的狀態傳回。以下是範例回應。

{
  "resourceType" : "Parameters",
  "parameter" : [
    "name" : "searchParameterStatus",
    "part" : {
        {
        "name" : "url",
        "valueString" : "http://hl7.org/fhir/SearchParameter/Account-identifier"
        },
        {
        "name" : "status",
        "valueString" : "supported"
        }
    }
  ]
}

更新搜尋參數的狀態

取得搜尋參數的狀態之後，請將搜尋參數的狀態更新為 Supported 或 Disabled。

注意

若要更新搜尋參數的狀態，您需要 搜尋參數管理員 Azure RBAC 角色。

您可以針對單一搜尋參數或大量更新搜尋參數狀態。

更新單一搜尋參數狀態

若要更新單一搜尋參數的狀態，請使用下列 API 要求。

PUT {{FHIR_URL}}/SearchParameter/$status
{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "searchParameterStatus",
            "part": [
                {
                    "name": "url",
                    "valueUrl": "http://hl7.org/fhir/SearchParameter/Resource-test-id"
                },
                {
                    "name": "status",
                    "valueString": "Supported"
                }
            ]
        }
    ]
}

根據您的使用案例，您可以保留搜尋參數的「支援」或「已停用」狀態值。當您在要求中傳送狀態 Disabled 時，回應會傳回， PendingDisable 因為重新編製索引作業必須執行才能完全移除關聯。

如果您在回應中收到 400 HTTP 狀態代碼，這表示已識別的搜尋參數沒有唯一的相符專案。檢查搜尋參數標識碼。

大量更新搜尋參數狀態

若要大量更新搜尋參數的狀態，'PUT' 要求應該在要求本文中具有 'Parameters' 資源清單。清單必須包含需要更新的個別搜尋參數。

PUT {{FHIR_URL}}/SearchParameter/$status
{
  "resourceType" : "Parameters",
  "parameter" : [
    {
     "name" : "searchParameterStatus",
     "part" :{
        "name" : "url",
        "valueString" : "http://hl7.org/fhir/SearchParameter/Endpoint-name"
     },
     "part":{ 
        "name" : "status",
        "valueString" : "supported"
     }
    },
         "name" : "searchParameterStatus",
     "part" :{
        "name" : "url",
        "valueString" : "http://hl7.org/fhir/SearchParameter/HealthcareService-name"
     },
     "part":{ 
        "name" : "status",
        "valueString" : "supported"
     }
    },
    ...
  ]
}

執行重新編製索引作業

將搜尋參數狀態更新為 Supported 或 Disabled之後，下一個步驟是執行重新索引作業。

在搜尋參數編製索引之前， Enabled 不會啟動搜尋參數的和 Disabled 狀態。重新編制作業執行索引，會將狀態從 Supported 更新為 Enabled 或 PendingDisable 。Disabled

您可以針對整個 FHIR 服務資料庫或特定搜尋參數執行重新索引作業。重新編製索引作業可能會耗用效能。如需詳細資訊，請參閱執行重新索引作業。

注意

功能語句檔是 FHIR 伺服器的一組行為。 Enabled 搜尋參數會列在 FHIR 服務的功能語句中。 /metadata 端點可以使用功能語句。

常見問題集

如果查詢包含狀態為『Supported』的搜尋參數，則行為為何？

必須重新編製「支援」狀態的搜尋參數。在那之前，不會啟動搜尋參數。如果在非使用中搜尋參數上執行查詢，FHIR 服務會轉譯回應，而不考慮該搜尋參數。在回應中，將會有警告訊息，指出搜尋參數未編製索引且未用於查詢。若要在這類情況下呈現錯誤，請使用值 'strict' 的 'Prefer： handling' 標頭。藉由設定此標頭，警告會回報為錯誤。

下一步

定義自訂搜尋參數

注意

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

共用方式為