本頁面由 Cloud Translation API 翻譯而成。

建立自訂 FHIR 搜尋作業

本頁說明如何設定 FHIR 存放區，支援 FHIR 標準搜尋參數未涵蓋的欄位和擴充功能自訂搜尋參數。

自訂搜尋參數在許多情況下都很有用，包括：

您需要搜尋 FHIR 資源中的欄位，但該欄位沒有支援的搜尋參數。
您需要在 FHIR 資料模型中新增的擴充功能中搜尋。

總覽

根據預設，搜尋 FHIR 資源支援 FHIR 規格中定義的標準搜尋參數，但 FHIR 功能陳述式或 FHIR 一致性陳述式中記錄的部分參數除外。

您可以建立一或多個自訂搜尋參數，並透過 search 方法設定 FHIR 儲存庫，在查詢中支援這些參數。自訂搜尋參數適用於下列情況：

在標準搜尋參數未涵蓋的欄位中搜尋。
在 FHIR 資料模型的擴充功能中搜尋。

許多 FHIR 實作指南會定義搜尋參數，您可以在搜尋時使用這些參數。

自訂搜尋參數支援相同的搜尋行為，包括進階 FHIR 搜尋功能，例如：

修飾符
_include 和 _revinclude
串聯搜尋
_sort

如要為 FHIR 儲存區啟用自訂搜尋功能，請先建立一或多個定義搜尋行為的 SearchParameter 資源。SearchParameter 是標準 FHIR 資源類型，可使用與其他資源類型相同的方法建立、更新或刪除。請參閱「在商店中建立搜尋參數資源」。

FHIR 存放區中的 SearchParameter 資源必須使用 configureSearch 方法設定，才會生效。這個方法會啟用自訂搜尋參數清單。每次呼叫時，都會取代先前的參數清單。系統會針對 configureSearch 觸發長時間執行的作業，根據新的搜尋設定，重新為商店中的所有相關資源建立索引。方法呼叫後的所有新資源和更新資源，都會根據新設定建立索引。系統會移除設定中已不存在的自訂搜尋參數索引資料。如要進一步瞭解如何使用 configureSearch，請參閱「為 FHIR 儲存庫啟用自訂搜尋參數」。

商店的 CapabilityStatement (透過 fhir.capabilities 方法擷取) 會列出標準和自訂搜尋參數。資源的搜尋參數位於 rest.resource.searchParam 欄位。

建立自訂 FHIR 搜尋作業

在 FHIR 儲存庫中建立 SearchParameter 資源

下列範例說明如何使用 projects.locations.datasets.fhirStores.fhir.create 方法建立自訂搜尋參數資源。您也可以使用 projects.locations.datasets.fhirStores.import 方法。

如要瞭解搜尋參數的相關欄位，請參閱「SearchParameter 資源欄位」。

curl

以下範例顯示如何使用 curl 發出 POST 要求。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
        \"resourceType\": \"SearchParameter\",
        \"url\": \"CANONICAL_URL\",
        \"base\": [\"RESOURCE_TYPE\"],
        \"code\": \"SEARCH_PARAMETER_CODE\",
        \"name\": \"SEARCH_PARAMETER_NAME\",
        \"type\": \"SEARCH_PARAMETER_TYPE\",
        \"expression\": \"SEARCH_PARAMETER_EXPRESSION\",
        \"status\": \"active\",
        \"description\": \"SEARCH_PARAMETER_DESCRIPTION\"
    }" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "resourceType": "SearchParameter",
  "url": "CANONICAL_URL",
  "base": ["RESOURCE_TYPE"],
  "code": "SEARCH_PARAMETER_CODE",
  "name": "SEARCH_PARAMETER_NAME",
  "type": "SEARCH_PARAMETER_TYPE",
  "expression": "SEARCH_PARAMETER_EXPRESSION",
  "status": "active",
  "description": "SEARCH_PARAMETER_DESCRIPTION",
  "meta": {
    "lastUpdated": "LAST_UPDATED",
    "versionId": "VERSION_ID"
  },
}

PowerShell

下列範例顯示如何使用 Windows PowerShell 提出 POST 要求。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

$SearchParameter = '{
    "resourceType": "SearchParameter",
    "url": "CANONICAL_URL",
    "base": ["RESOURCE_TYPE"],
    "code": "SEARCH_PARAMETER_CODE",
    "name": "SEARCH_PARAMETER_NAME",
    "type": "SEARCH_PARAMETER_TYPE",
    "expression": "SEARCH_PARAMETER_EXPRESSION",
    "status": "active",
    "description": "SEARCH_PARAMETER_DESCRIPTION"
}'

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body $SearchParameter `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter" | ConvertTo-Json

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "resourceType": "SearchParameter",
  "url": "CANONICAL_URL",
  "base": ["RESOURCE_TYPE"],
  "code": "SEARCH_PARAMETER_CODE",
  "name": "SEARCH_PARAMETER_NAME",
  "type": "SEARCH_PARAMETER_TYPE",
  "expression": "SEARCH_PARAMETER_EXPRESSION",
  "status": "active",
  "description": "SEARCH_PARAMETER_DESCRIPTION",
  "meta": {
    "lastUpdated": "LAST_UPDATED",
    "versionId": "VERSION_ID"
  },
}

為 FHIR 儲存庫啟用自訂搜尋參數

如要為 FHIR 存放區啟用一或多個自訂搜尋參數，請向 [store base URL]:configureSearch 方法發出 POST 要求，並為要啟用的每個搜尋參數指定標準網址。

標準網址的格式如下：

uri：選取商店中適用於該 URI 的最大 version。
uri|version 選取特定版本。

舉例來說，如果商店包含 1.0.0 和 1.0.1 版本的搜尋參數 (具有 http://example.com/search URI)，標準網址 http://example.com/search|1.0.0 會選取 1.0.0 版本。標準網址 http://example.com/search 會選取1.0.1版本。

提供給這個方法的網址清單會取代先前的任何設定，並移除先前生效的自訂搜尋參數。系統會根據呼叫 configureSearch 時存在的 SearchParameter 資源內容，快取設定。如果更新或刪除 SearchParameter 資源，除非再次呼叫 configureSearch，否則設定不會更新。

如果 [store base URL]:configureSearch 方法呼叫成功，傳回值就是長時間執行的作業名稱，可根據新設定重新為商店中的資源建立索引。您可以使用 operations.get 方法查看長時間執行的作業狀態，並使用 operations.cancel 方法取消作業。狀態會顯示計數器，指出已成功重新建立索引的資源數量。

在長時間執行的作業期間，商店的搜尋功能仍可正常運作，但這項作業新增或變更的自訂搜尋參數會傳回部分結果。取消作業是安全的，但自訂搜尋參數只會部分建立索引。請務必先完成整個重新建立索引作業，再使用新加入或變更的參數進行搜尋。

如有錯誤，系統會顯示在 Cloud Logging 中。

configureSearch 方法也可以搭配 "validate_only": true 選項使用，藉此驗證指定的搜尋參數，而不需修改商店設定或重新建立任何資料的索引。

下列範例說明如何使用 projects.locations.datasets.fhirStores.configureSearch 方法，為 FHIR 儲存庫啟用一或多個自訂搜尋參數。

curl

以下範例顯示如何使用 curl 發出 POST 要求。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
        \"canonicalUrls\": [\"CANONICAL_URL1\",\"CANONICAL_URL2\"],
    }" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

回應會包含作業名稱。如要追蹤作業狀態，可以使用 Operation get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

如果長時間執行的作業仍在執行，伺服器會以 JSON 格式傳回回應，其中包含待重新建立索引的 FHIR 資源數量：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.fhir.FhirStoreService.ConfigureSearch",
    "createTime": "CREATE_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "pending": "PENDING_COUNT"
    }
  }
}

LRO 完成後，伺服器會以 JSON 格式傳回作業狀態的回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.configureSearch",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty",
  }
}

如果 LRO 成功，回應會包含成功重新建立索引的 FHIR 資源數量，以及 google.protobuf.Empty 回應類型。

PowerShell

下列範例顯示如何使用 Windows PowerShell 提出 POST 要求。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

$configureSearch = '{
  "canonical_urls": [
    "CANONICAL_URL1",
    "CANONICAL_URL2"
  ]
}'

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body $configureSearch `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

回應會包含作業名稱。如要追蹤作業狀態，可以使用 Operation get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

如果長時間執行的作業仍在執行，伺服器會以 JSON 格式傳回回應，其中包含待重新建立索引的 FHIR 資源數量：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.fhir.FhirStoreService.ConfigureSearch",
    "createTime": "CREATE_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "pending": "PENDING_COUNT"
    }
  }
}

LRO 完成後，伺服器會以 JSON 格式傳回作業狀態的回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.configureSearch",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty",
  }
}

如果 LRO 成功，回應會包含成功重新建立索引的 FHIR 資源數量，以及 google.protobuf.Empty 回應類型。

使用自訂搜尋功能搜尋資源

您可以像其他搜尋一樣，使用自訂 SearchParameter 進行搜尋。請使用搜尋參數資源中的 code 值做為搜尋查詢的 key。詳情請參閱「搜尋 FHIR 資源」。

SearchParameter 資源欄位

以下章節說明與自訂搜尋相關的 SearchParameter 資源欄位。這些欄位適用於 FHIR 的 STU3 和 R4 版本。

`uri` 和 `version`

必要欄位 uri 和選用欄位 version 會定義 SearchParameter 資源的標準網址。uri 和 version 的組合在 FHIR 存放區中不得重複。

標準網址是 configureSearch 呼叫中使用的網址。

`name`、`description` 和 `status`

name、description 和 status 欄位為必填，但不會產生任何功能效果。

`base`

「base」欄位會列出這項搜尋適用的 FHIR 資源類型。

如果有多個類型，expression 欄位就必須為每個類型加上子句。在兩種型別上定義一個參數，與為每種型別定義一個參數，兩者之間沒有差異。為多種資源類型定義一個參數，可讓定義更精簡。

`code`

「code」欄位定義要在 FHIR 搜尋查詢中使用的鍵。舉例來說，如果 code 定義為 payment-type，而 base 定義為 Claim，則使用這個參數的搜尋查詢會是 Claim?payment-type=ABC。

code 欄位的值不得與相同資源類型中的任何其他標準或自訂搜尋參數相同。您無法使用自訂搜尋參數重新定義或修改標準搜尋參數。configureSearch 方法會拒絕重複的搜尋參數。

code 欄位的值必須符合下列規定：

開頭須為英文字母
長度不得超過 64 個字元
必須只包含下列內容：
- 英數字元
- 連字號 -
- 底線字元 _

code 欄位的 FHIR 標準慣例是使用含破折號的小寫字母。

`type`

「type」欄位定義搜尋參數類型。搜尋參數類型會決定搜尋條件的語意，如 FHIR 搜尋規格中所定義。type 的這個值必須與 expression 欄位指定的欄位資料類型相容。如果不是，configureSearch會拒絕自訂搜尋參數。

type 欄位必須定義為下列其中一項：

number
date
string
token
reference
quantity
uri

系統不支援 composite 和 special 類型。

`expression`

「expression」欄位會定義搜尋參數查詢的欄位或擴充功能。這個欄位使用 FHIRPath 的部分語法和函式。

欄位語法

expression 欄位定義為以資源類型開頭的路徑，後面接一或多個以 . 分隔的欄位，例如 Patient.contact.name.given。如要瞭解 FHIR 資料的欄位結構，請參閱 FHIR 資源和 FHIR 資料型別。

多個子句

expression 欄位可包含多個以 | 分隔的子句。在這種情況下，只要有任何子句與資源相符，搜尋參數就會相符。舉例來說，如果搜尋參數的運算式為 Patient.name.given | Patient.name.family，則會比對這兩個欄位。在 base 中指定多個資源類型時，請使用多個子句。舉例來說，Patient.name.given | Practitioner.name.given 適用於 Patient 和 Practitioner 的搜尋參數。

`.as([data type])`

如果欄位有多個可能的資料類型，請使用 .as([data type]) 函式。舉例來說，Observation.value 欄位可包含許多不同類型，例如 Quantity 和 String，這些類型適用於不同的搜尋類型。你可以使用 Observation.value.as(Quantity) 或 Observation.value.as(String) 選取這些搜尋類型。

選取擴充功能

您可以使用 .extension([canonical url]) 函式選取擴充功能。由於擴充功能包含可含有任何資料類型的 value 欄位，完整路徑會定義為 .extension([canonical url]).value.as([data type])。複雜的擴充功能可以使用多個 .extension() 元件，例如 Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-citizenship').extension('code').value.as(CodeableConcept)。

您也可以使用 .extension.where(url='[canonical url]') 函式選取擴充功能。這是唯一允許使用 where() 函式的環境。

不支援其他 FHIRPath 函式。

`target`

如果 type 欄位定義為 reference，則 target 欄位必須包含一或多個 FHIR 資源類型，定義哪些資源類型可做為這項參照搜尋的目標。

舉例來說，如果 Patient.generalPractitioner 欄位允許參照 Practitioner、PractitionerRole 和 Organization，搜尋參數可以特別比對 Practitioner、PractitionerRole 或 Organization 的參照。如要比對所有目標類型的參照，請在 target 欄位中納入所有類型。

`modifier`、`comparator`、`multipleOr`、`multipleAnd` 和 `chain`

系統會忽略 modifier、comparator、multipleOr、multipleAnd 和 chain 欄位。自訂搜尋參數提供的選項和功能，與 FHIR 儲存庫在相同類型標準搜尋參數上支援的選項和功能相同。

使用實作指南中的搜尋參數

如果您要導入從 FHIR 導入指南取得的搜尋參數，請使用下列任一方法，將導入指南 JSON 檔案中的 SearchParameter 資源匯入 FHIR 儲存庫：

在某些情況下，您必須轉換已發布的 Cloud Healthcare API 搜尋參數，才能支援該參數。如果搜尋參數未轉換，configureSearch 方法會拒絕這些參數。實作指南中的搜尋參數有下列限制：

如果搜尋參數與基本 FHIR 規格中的參數相同，configureSearch 方法會拒絕重複的搜尋參數。呼叫 configureSearch 時，請省略這類重複項目。詳情請參閱 code。
如果搜尋參數只包含 xpath 運算式，請將該運算式轉換為對等的 FHIRPath 運算式，並在 expression 欄位中使用。詳情請參閱 expression。
系統不支援 composite 和 special 搜尋參數類型。
系統不支援替代的型別轉換語法 ([field] as [data type])。轉換為支援的對等項目 [field].as([data type])。詳情請參閱 .as([data type])。
系統不支援用於限制參照資源類型的 [reference field].where(resolve() is [resource type]) 慣例。移除 where() 子句，改為將參照的資源類型儲存在 SearchParameter.target 欄位中。詳情請參閱 target。
部分導入指南會使用擴充功能的運算式，省略 Cloud Healthcare API FHIR 儲存庫所需的某些路徑元件。舉例來說，Patient.extension('url') 必須修改為 Patient.extension('url').value.as([data type])，Patient.extension('url').extension.value 則必須修改為 Patient.extension('url').extension('url2').value.as([data type])。

範例

使用自訂搜尋功能搜尋擴充功能欄位

以下步驟以在 Patient 資源的 mothersMaidenName 擴充功能中搜尋文字為例。

建立範例 Patient 資源：

curl

以下範例說明如何使用 curl 提出 POST 要求，藉此建立 Patient 資源。這個 Patient 資源的 mothersMaidenName 擴充功能已設為 Marca。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      \"name\": [
          {
              \"use\": \"official\",
              \"family\": \"Smith\",
              \"given\": [
                  \"Darcy\"
              ]
          }
      ],
      \"gender\": \"female\",
      \"birthDate\": \"1970-01-01\",
      \"resourceType\": \"Patient\",
      \"extension\": [
          {
              \"url\": \"http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName\",
              \"valueString\": \"Marca\"
          }
      ]
    }" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient"

如果要求成功，伺服器會以 JSON 格式傳回類似以下範例的回應：

{
  "birthDate": "1970-01-01",
  "gender": "female",
  "id": "PATIENT_ID",
  "meta": {
    "lastUpdated": "2020-01-01T00:00:00+00:00",
    "versionId": "VERSION_ID"
  },
  "name": [
    {
      "family": "Smith",
      "given": [
        "Darcy"
      ],
      "use": "official"
    }
  ],
  "resourceType": "Patient"
  "extension": [
    {
        "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName",
        "valueString": "Marca"
    }
  ]
}

PowerShell

下列範例說明如何使用 Windows PowerShell 提出 POST 要求，藉此建立 Patient 資源。這項 Patient 資源的 mothersMaidenName 擴充功能設為 Marca。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

$Patient = '{
    "name": [
        {
            "use": "official",
            "family": "Smith",
            "given": [
                "Darcy"
            ]
        }
    ],
    "gender": "female",
    "birthDate": "1970-01-01",
    "resourceType": "Patient",
    "extension": [
        {
            "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName",
            "valueString": "Marca"
        }
    ]
}'

Invoke-RestMethod `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/fhir+json; charset=utf-8" `
  -Body $Patient `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient" | ConvertTo-Json

如果要求成功，伺服器會以 JSON 格式傳回類似以下範例的回應：

{
  "birthDate": "1970-01-01",
  "gender": "female",
  "id": "PATIENT_ID",
  "meta": {
    "lastUpdated": "2020-01-01T00:00:00+00:00",
    "versionId": "VERSION_ID"
  },
  "name": [
    {
      "family": "Smith",
      "given": [
        "Darcy"
      ],
      "use": "official"
    }
  ],
  "resourceType": "Patient"
  "extension": [
    {
        "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName",
        "valueString": "Marca"
    }
  ]
}

建立自訂搜尋參數資源：

curl

下列範例說明如何使用 curl 提出 POST 要求，為 mothersMaidenName 擴充功能建立自訂搜尋參數資源。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
        \"resourceType\": \"SearchParameter\",
        \"url\": \"http://example.com/SearchParameter/patient-mothersMaidenName\",
        \"base\": [\"Patient\"],
        \"code\": \"mothers-maiden-name\",
        \"name\": \"mothers-maiden-name\",
        \"type\": \"string\",
        \"expression\": \"Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName').value.as(String)\",
        \"status\": \"active\",
        \"description\": \"search on mother's maiden name\"
  }" \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{ 

   "resourceType": "SearchParameter", 

   "url": "http://example.com/SearchParameter/patient-mothersMaidenName", 

   "base": ["Patient"], 

   "code": "mothers-maiden-name", 

   "name": "mothers-maiden-name", 

   "type": "string", 

   "expression": "Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName').value.as(String)", 

   "status": "active", 

   "description": "search on mother's maiden name", 

   "meta": { 

    "lastUpdated": "2020-01-01T00:00:00+00:00", 

    "versionId": "VERSION_ID" 

   }, 

}

PowerShell

以下說明如何使用 Windows PowerShell 發出 `POST` 要求，為 `mothersMaidenName` 擴充功能建立自訂搜尋參數資源。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

$SearchParameter = '{
    "resourceType": "SearchParameter",
    "url": "http://example.com/SearchParameter/patient-mothersMaidenName",
    "base": ["Patient"],
    "code": "mothers-maiden-name",
    "name": "mothers-maiden-name",
    "type": "string",
    "expression": "Patient.extension(''http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName'').value.as(String)",
    "status": "active",
    "description": "search on mother''s maiden name"
}'

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body $SearchParameter `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{ 

   "resourceType": "SearchParameter", 

   "url": "http://example.com/SearchParameter/patient-mothersMaidenName", 

   "base": ["Patient"], 

   "code": "mothers-maiden-name", 

   "name": "mothers-maiden-name", 

   "type": "string", 

   "expression": "Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName').value.as(String)", 

   "status": "active", 

   "description": "search on mother's maiden name", 

   "meta": { 

      "lastUpdated": "2020-01-01T00:00:00+00:00", 

      "versionId": "VERSION_ID" 

   }, 

}

如要在 expression 欄位中指定其他資料類型，請使用 .as([data type]) 函式。舉例來說，如要指定布林值的搜尋運算式，請使用 .value.as(Boolean)。詳情請參閱 .as([data type])。

啟用搜尋參數：

curl

如要啟用自訂搜尋參數，請發出 POST 要求，並為要啟用的每個搜尋參數指定標準網址。

以下範例顯示如何使用 curl 發出 POST 要求。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
        \"canonicalUrls\": [\"http://example.com/SearchParameter/patient-mothersMaidenName\"],
    }" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

PowerShell

如要啟用自訂搜尋參數，請發出 POST 要求，並為要啟用的每個搜尋參數指定標準網址。

下列範例顯示如何使用 Windows PowerShell 提出 POST 要求。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

$configureSearch = '{
  "canonicalUrls": "http://example.com/SearchParameter/patient-mothersMaidenName"
}' `

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body $configureSearch `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

使用自訂搜尋參數進行搜尋：

curl

以下範例說明如何使用 curl 提出 GET 要求，在 mothersMaidenName 擴充功能中搜尋「Marca」字串的病患資源。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?mothers-maiden-name:exact=Marca"

如果要求成功，伺服器會以 JSON 格式傳回 FHIR Bundle。Bundle.type 是 searchset，搜尋結果則是 Bundle.entry 陣列中的項目。在本範例中，要求會傳回單一 Patient 資源，包括該資源內的資料：

{
  "entry": [
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID",
      "resource": {
        "birthDate": "1970-01-01",
        "gender": "female",
        "id": "PATIENT_ID",
        "meta": {
          "lastUpdated": "LAST_UPDATED",
          "versionId": "VERSION_ID"
        },
        "name": [
          {
            "family": "Smith",
            "given": [
              "Darcy"
            ],
            "use": "official"
          }
        ],
        "resourceType": "Patient"
        "extension": [
          {
              "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName",
              "valueString": "Marca"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}

PowerShell

下列範例說明如何使用 Windows PowerShell 發出 `GET` 要求，在 `mothersMaidenName` 擴充功能中搜尋字串 `Marca` 的病患資源。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-RestMethod `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?mothers-maiden-name:exact=Marca" | ConvertTo-Json

{
  "entry": [
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID",
      "resource": {
        "birthDate": "1970-01-01",
        "gender": "female",
        "id": "PATIENT_ID",
        "meta": {
          "lastUpdated": "LAST_UPDATED",
          "versionId": "VERSION_ID"
        },
        "name": [
          {
            "family": "Smith",
            "given": [
              "Darcy"
            ],
            "use": "official"
          }
        ],
        "resourceType": "Patient"
        "extension": [
          {
              "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName",
              "valueString": "Marca"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}

使用自訂搜尋功能，在 2 層擴充功能欄位中搜尋

下列步驟說明如何在 Patient 資源的 us-core-ethnicity 擴充功能中搜尋程式碼。

建立範例 Patient 資源：

curl

以下範例說明如何使用 curl 提出 POST 要求，藉此建立 Patient 資源。這個 Patient 資源已設定 us-core-ethnicity 擴充功能。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      \"name\": [
          {
              \"use\": \"official\",
              \"family\": \"Smith\",
              \"given\": [
                  \"Darcy\"
              ]
          }
      ],
      \"gender\": \"female\",
      \"birthDate\": \"1970-01-01\",
      \"resourceType\": \"Patient\",
      \"extension\": [
          {
            \"url\": \"http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity\",
            \"extension\": [
              {
                \"url\" : \"ombCategory\",
                \"valueCoding\" : {
                  \"system\" : \"urn:oid:2.16.840.1.113883.6.238\",
                  \"code\" : \"2028-9\",
                  \"display\" : \"Asian\"
                }
              }
            ]
          }
      ]
    }" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient"

如果要求成功，伺服器會以 JSON 格式傳回類似以下範例的回應：

{
  "birthDate": "1970-01-01",
  "gender": "female",
  "id": "PATIENT_ID",
  "meta": {
    "lastUpdated": "2020-01-01T00:00:00+00:00",
    "versionId": "VERSION_ID"
  },
  "name": [
    {
      "family": "Smith",
      "given": [
        "Darcy"
      ],
      "use": "official"
    }
  ],
  "resourceType": "Patient"
  "extension": [
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
      "extension": [
        {
          "url" : "ombCategory",
          "valueCoding" : {
            "system" : "urn:oid:2.16.840.1.113883.6.238",
            "code" : "2028-9",
            "display" : "Asian"
          }
        }
      ]
    }
  ]
}

PowerShell

下列範例說明如何使用 Windows PowerShell 提出 POST 要求，藉此建立 Patient 資源。這個 Patient 資源已設定 us-core-ethnicity 擴充功能。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

$Patient = '{
    "name": [
        {
            "use": "official",
            "family": "Smith",
            "given": [
                "Darcy"
            ]
        }
    ],
    "gender": "female",
    "birthDate": "1970-01-01",
    "resourceType": "Patient",
    "extension": [
      {
        "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
        "extension": [
          {
            "url" : "ombCategory",
            "valueCoding" : {
              "system" : "urn:oid:2.16.840.1.113883.6.238",
              "code" : "2028-9",
              "display" : "Asian"
            }
          }
        ]
      }
    ]
}'

Invoke-RestMethod `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/fhir+json; charset=utf-8" `
  -Body $Patient `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient" | ConvertTo-Json

如果要求成功，伺服器會以 JSON 格式傳回類似以下範例的回應：

{
  "birthDate": "1970-01-01",
  "gender": "female",
  "id": "PATIENT_ID",
  "meta": {
    "lastUpdated": "2020-01-01T00:00:00+00:00",
    "versionId": "VERSION_ID"
  },
  "name": [
    {
      "family": "Smith",
      "given": [
        "Darcy"
      ],
      "use": "official"
    }
  ],
  "resourceType": "Patient"
  "extension": [
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
      "extension": [
        {
          "url" : "ombCategory",
          "valueCoding" : {
            "system" : "urn:oid:2.16.840.1.113883.6.238",
            "code" : "2028-9",
            "display" : "Asian"
          }
        }
      ]
    }
  ]
}

建立自訂搜尋參數資源：

curl

下列範例說明如何使用 curl 提出 POST 要求，為 us-core-ethnicity 擴充功能建立自訂搜尋參數資源。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
        \"resourceType\": \"SearchParameter\",
        \"url\": \"http://example.com/SearchParameter/patient-us-core-ethnicity\",
        \"base\": [\"Patient\"],
        \"code\": \"ethnicity\",
        \"name\": \"ethnicity\",
        \"type\": \"token\",
        \"expression\": \"Patient.extension('http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity').extension('ombCategory').value.as(Coding)\",
        \"status\": \"active\",
        \"description\": \"search on the ombCategory of a patient.\"
  }" \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "resourceType": "SearchParameter",
  "url": "http://example.com/SearchParameter/patient-us-core-ethnicity",
  "base": ["Patient"],
  "code": "ethnicity",
  "name": "ethnicity",
  "type": "token",
  "expression": "Patient.extension('http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity').extension('ombCategory').value.as(Coding)",
  "status": "active",
  "description": "search on the ombCategory of a patient.",
  "meta": {
    "lastUpdated": "2020-01-01T00:00:00+00:00",
    "versionId": "VERSION_ID"
  },
}

PowerShell

下列範例說明如何使用 Windows PowerShell 發出 `POST` 要求，為 `mothersMaidenName` 擴充功能建立自訂搜尋參數資源。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

$SearchParameter = '{
    "resourceType": "SearchParameter",
    "url": "http://example.com/SearchParameter/patient-us-core-ethnicity",
    "base": ["Patient"],
    "code": "ethnicity",
    "name": "ethnicity",
    "type": "token",
    "expression": "Patient.extension(''http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity'').extension(''ombCategory'').value.as(Coding)",
    "status": "active",
    "description": "search on the ombCategory of a patient."
}'

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body $SearchParameter `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "resourceType": "SearchParameter",
  "url": "http://example.com/SearchParameter/patient-us-core-ethnicity",
  "base": ["Patient"],
  "code": "ethnicity",
  "name": "ethnicity",
  "type": "token",
  "expression": "Patient.extension('http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity').extension('ombCategory').value.as(Coding)",
  "status": "active",
  "description": "search on the ombCategory of a patient.",
  "meta": {
    "lastUpdated": "2020-01-01T00:00:00+00:00",
    "versionId": "VERSION_ID"
  },
}

啟用搜尋參數：

curl

如要啟用自訂搜尋參數，請發出 POST 要求，並為要啟用的每個搜尋參數指定標準網址。

以下範例顯示如何使用 curl 發出 POST 要求。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
        \"canonicalUrls\": [\"http://example.com/SearchParameter/patient-us-core-ethnicity\"],
    }" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

PowerShell

如要啟用自訂搜尋參數，請發出 POST 要求，並為要啟用的每個搜尋參數指定標準網址。

下列範例顯示如何使用 Windows PowerShell 提出 POST 要求。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

$configureSearch = '{
  "canonicalUrls": "http://example.com/SearchParameter/patient-us-core-ethnicity"
}' `

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body $configureSearch `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"

如果要求成功，伺服器會以 JSON 格式傳回回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

使用自訂搜尋參數進行搜尋：

curl

下列範例說明如何使用 curl 發出 GET 要求，在 us-core-ethnicity 擴充功能中搜尋 urn:oid:2.16.840.1.113883.6.238|2028-9 代碼的病患資源。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?ethnicity=urn:oid:2.16.840.1.113883.6.238|2028-9"

{
  "entry": [
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID",
      "resource": {
        "birthDate": "1970-01-01",
        "gender": "female",
        "id": "PATIENT_ID",
        "meta": {
          "lastUpdated": "LAST_UPDATED",
          "versionId": "VERSION_ID"
        },
        "name": [
          {
            "family": "Smith",
            "given": [
              "Darcy"
            ],
            "use": "official"
          }
        ],
        "resourceType": "Patient"
        "extension": [
          {
            "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
            "extension": [
              {
                "url" : "ombCategory",
                "valueCoding" : {
                  "system" : "urn:oid:2.16.840.1.113883.6.238",
                  "code" : "2028-9",
                  "display" : "Asian"
                }
              }
            ]
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?ethnicity=urn:oid:2.16.840.1.113883.6.238|2028-9"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}

PowerShell

下列範例說明如何使用 Windows PowerShell 發出 `GET` 要求，在 `us-core-ethnicity` 擴充功能中搜尋代碼 `urn:oid:2.16.840.1.113883.6.238|2028-9` 的 Patient 資源。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-RestMethod `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?ethnicity=urn:oid:2.16.840.1.113883.6.238|2028-9 | ConvertTo-Json

{
  "entry": [
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID",
      "resource": {
        "birthDate": "1970-01-01",
        "gender": "female",
        "id": "PATIENT_ID",
        "meta": {
          "lastUpdated": "LAST_UPDATED",
          "versionId": "VERSION_ID"
        },
        "name": [
          {
            "family": "Smith",
            "given": [
              "Darcy"
            ],
            "use": "official"
          }
        ],
        "resourceType": "Patient"
        "extension": [
          {
            "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
            "extension": [
              {
                "url" : "ombCategory",
                "valueCoding" : {
                  "system" : "urn:oid:2.16.840.1.113883.6.238",
                  "code" : "2028-9",
                  "display" : "Asian"
                }
              }
            ]
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?ethnicity=urn:oid:2.16.840.1.113883.6.238|2028-9"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}

建立自訂 FHIR 搜尋作業 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

建立自訂 FHIR 搜尋作業

在 FHIR 儲存庫中建立 SearchParameter 資源

curl

PowerShell

為 FHIR 儲存庫啟用自訂搜尋參數

curl

PowerShell

使用自訂搜尋功能搜尋資源

SearchParameter 資源欄位

uri 和 version

name、description 和 status

base

code

type

expression

欄位語法

多個子句

.as([data type])

選取擴充功能

target

modifier、comparator、multipleOr、multipleAnd 和 chain

使用實作指南中的搜尋參數

範例

使用自訂搜尋功能搜尋擴充功能欄位

curl

PowerShell

curl

PowerShell

curl

PowerShell

curl

PowerShell

使用自訂搜尋功能，在 2 層擴充功能欄位中搜尋

curl

PowerShell

curl

PowerShell

curl

PowerShell

curl

PowerShell

建立自訂 FHIR 搜尋作業

`uri` 和 `version`

`name`、`description` 和 `status`

`base`

`code`

`type`

`expression`

`.as([data type])`

`target`

`modifier`、`comparator`、`multipleOr`、`multipleAnd` 和 `chain`