本頁面提供基本操作說明,介紹如何在 FHIR 儲存庫中搜尋 FHIR 資源。搜尋 FHIR 資源是查詢 FHIR 資料並從中取得洞察資料的主要方式。
您可以使用下列方式,在 Cloud Healthcare API 中搜尋 FHIR 資源:
- 在 Google Cloud 控制台中使用 FHIR 檢視器。
- 使用
projects.locations.datasets.fhirStores.fhir.search
方法。這個方法提供下列 FHIR 資源搜尋方式:GET
要求POST
要求
本頁面彙整了許多常用的搜尋功能,但並未列出 Cloud Healthcare API 支援的FHIR 搜尋規格所有部分。
使用 FHIR 檢視器
FHIR 檢視器是控制台中的頁面,可供您搜尋及 Google Cloud 查看 FHIR 資源的內容。
如要在 FHIR 儲存庫中搜尋資源,請完成下列步驟:
前往 Google Cloud 控制台的「FHIR viewer」頁面。
在「FHIR Store」(FHIR 儲存庫) 下拉式清單中選取資料集,然後選取資料集中的 FHIR 儲存庫。
如要篩選資源類型清單,請搜尋要顯示的資源類型:
按一下「資源類型」欄位。
在隨即出現的「Properties」(屬性) 下拉式清單中選取「Resource Type」(資源類型)。
輸入資源類型。
如要搜尋其他資源類型,請從隨即顯示的「Operators」(運算子) 下拉式清單中選取「OR」(或),然後輸入其他資源類型。
在資源類型清單中,選取要搜尋的資源類型。
在顯示的資源表格搜尋框中,輸入要搜尋的值。
FHIR 檢視器會以表格形式顯示搜尋結果。選取資源後,FHIR 檢視器就會顯示資源內容。
查看資源內容時,您可以搜尋資源內的資料。
如要在資源中搜尋資料,請按照下列步驟操作:
請選取資源。
在「FHIR viewer」窗格中,按一下「Elements」分頁標籤。
在搜尋框中輸入要搜尋的值。
下載 FHIR 資源中的二進位資料
如要下載 FHIR 檢視器中與資源相關聯的可用二進位資料,請按照下列步驟操作:
請選取資源。
在「FHIR viewer」窗格中,按一下「Elements」分頁標籤。
如有需要,請展開元素,存取所需資源元素。
按一下「下載檔案」即可下載可用資料。
建立及執行進階搜尋查詢
您可以使用進階搜尋查詢,依據 FHIR 搜尋規格搜尋特定 FHIR 資源。
如要建立進階搜尋查詢,請完成下列步驟:
在「FHIR viewer」(FHIR 檢視器) 頁面上,按一下「Search」(搜尋) 分頁標籤。
如要建立搜尋查詢,請按一下「開啟查詢建構工具」。
系統會顯示「查詢選取」面板。
在「選取 FHIR 資源類型」清單中,選擇要搜尋的 FHIR 資源類型。
按一下「繼續」。
從「參數」清單中,選取要用來搜尋資源的參數。
在「修飾符」清單中,選取要套用至查詢的修飾符。清單只會列出與所選參數資料類型相容的修飾符。
這是選填項目。如未選取修飾符,系統會執行等號檢查。
在「值」欄位中,輸入查詢參數的值。
如要新增多個參數值,請按一下「OR」。這樣一來,您就能在搜尋查詢中加入資源參數的多個值。
建構搜尋查詢時,「查詢預覽」窗格會顯示查詢內容。如要查看搜尋查詢的完整網址,請按一下「顯示完整路徑」。
如要新增多個參數,請按一下「和」。
按一下「繼續」。
如要納入搜尋查詢傳回的資源所參照的資源,請從「Included parameters」(納入的參數) 下拉式清單中選擇資源參數。
如要納入參照搜尋查詢傳回資源的資源,請從「Reverse included parameters」(反向納入的參數) 下拉式清單中選擇資源參數。
按一下「完成」即可儲存搜尋查詢。
儲存的搜尋查詢會顯示在「FHIR search operation」(FHIR 搜尋作業) 欄位中。
如要使用查詢條件搜尋資源,請按一下「執行搜尋」。
搜尋結果會顯示在「搜尋結果」清單中。如要查看搜尋結果中某項資源的詳細資料,請點選清單中的資源。
如要將查詢儲存為查詢範本,請按一下「儲存範本」,然後選擇「儲存範本」或「另存範本」。系統會提示您輸入查詢的名稱和說明。 查詢參數會儲存在範本中,但系統會移除所有已定義的值。
搜尋查詢範例
以下範例顯示搜尋查詢,可從特定醫療服務提供者 Practitioner/12345 搜尋 2021 年 8 月的 Claim 資源:
- 參數:
care-team
- 價值:
Practitioner/12345
- 價值:
- 運算子:AND
- 參數:
created
- 前置字元:
lt (lesser than)
- 價值:
8/1/21, 12:00 AM
- 前置字元:
- 運算子:AND
- 參數:
created
- 前置字元:
gt (greater than)
- 價值:
8/31/21, 11:59 PM
- 前置字元:
這項設定位於「Query Selection」(查詢選取) 面板,查詢則會顯示在「Query Preview」(查詢預覽) 窗格中。查詢會顯示在「FHIR search operation」(FHIR 搜尋作業) 欄位中。
編輯搜尋查詢
如要編輯搜尋查詢,請執行下列其中一項操作:
- 如要在查詢建構工具中編輯查詢,請按一下「開啟查詢建構工具」。
- 如要手動編輯查詢,請修改文字方塊中的參數值。
執行查詢範本
如要從已儲存的範本執行查詢,請完成下列步驟:
按一下「已儲存的範本」。
「查詢選取」面板會顯示「搜尋範本」分頁,其中列出所有已儲存的查詢範本。
選取要執行的查詢範本,然後按一下「完成」。
範本的搜尋查詢會顯示在 FHIR 搜尋作業 欄位中,且不含任何值。
如要定義搜尋查詢的值,請編輯欄位中的參數值。
按一下「執行搜尋」,即可使用查詢條件搜尋資源。
共用 FHIR 資源
您可以分享 FHIR 資源目前或歷史版本的連結。
控制台
前往 Google Cloud 控制台的「FHIR viewer」頁面。
在「FHIR store」(FHIR 儲存庫) 選單中選取資料集,然後選取資料集中的 FHIR 儲存庫。
如要篩選 FHIR 資源類型清單,請搜尋要顯示的資源類型。
按一下「資源類型」欄位。
在隨即出現的「Properties」(屬性) 下拉式清單中選取「Resource Type」(資源類型)。
輸入 FHIR 資源類型。
在 FHIR 資源類型清單中,選取資源類型。
在隨即顯示的 FHIR 資源表格中,選取或搜尋資源。
在「FHIR viewer」(FHIR 檢視器)窗格中,按一下
「Share」(分享)。系統會自動將 FHIR 資源的共用連結複製到剪貼簿。
使用 search
方法
如要使用 REST API 搜尋 FHIR 資源,請使用 projects.locations.datasets.fhirStores.fhir.search
方法。您可以使用 GET
或 POST
要求呼叫方法。
搭配 GET
使用 search
方法
下列範例說明如何使用 projects.locations.datasets.fhirStores.fhir.search
方法和 GET
,在指定 FHIR 存放區中搜尋資源。
curl
如要在 FHIR 儲存庫中搜尋資源,請發出 GET
要求,並指定下列資訊:
- 資料集名稱
- FHIR 儲存庫名稱
- 要搜尋的資源類型
- 查詢字串,內含您要搜尋的資訊,如「建構搜尋查詢」一節所述
- 存取權杖
以下範例顯示如何使用 curl
提出 GET
要求,搜尋所有姓氏為「Smith」的病患。
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/fhirStores/FHIR_STORE_ID/fhir/Patient?family:exact=Smith"
如果要求成功,伺服器會以 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" }, "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
如要在 FHIR 儲存庫中搜尋資源,請發出 GET
要求,並指定下列資訊:
- 資料集名稱
- FHIR 儲存庫名稱
- 要搜尋的資源類型
- 查詢字串,內含您要搜尋的資訊,如「建構搜尋查詢」一節所述
- 存取權杖
以下範例顯示如何使用 Windows PowerShell 提出 GET
要求,搜尋所有姓氏為「Smith」的病患。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Get ` -Headers $headers ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE?family:exact=Smith" | ConvertTo-Json
如果要求成功,伺服器會以 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" }, "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" }
Java
Node.js
Python
搭配 POST
使用 search
方法
下列範例說明如何使用 projects.locations.datasets.fhirStores.fhir.search
方法和 POST
,在指定 FHIR 存放區中搜尋資源。
curl
如要在 FHIR 儲存庫中搜尋資源,請發出 POST
要求,並指定下列資訊:
- 資料集名稱
- FHIR 儲存庫名稱
- 要搜尋的資源類型
- 查詢字串,內含您要搜尋的資訊,如「建構搜尋查詢」一節所述
- 存取權杖
以下範例顯示如何使用 curl
提出 POST
要求,搜尋所有姓氏為「Smith」的病患。
curl -X POST \ --data "" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/fhir+json; charset=utf-8" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/_search?family:exact=Smith"
如果要求成功,伺服器會以 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" }, "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
如要在 FHIR 儲存庫中搜尋資源,請發出 POST
要求,並指定下列資訊:
- 資料集名稱
- FHIR 儲存庫名稱
- 要搜尋的資源類型
- 查詢字串,內含您要搜尋的資訊,如「建構搜尋查詢」一節所述
- 存取權杖
以下範例顯示如何使用 Windows PowerShell 提出 POST
要求,搜尋所有姓氏為「Smith」的病患。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json; charset=utf-8" ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/_search?family:exact=Smith" | ConvertTo-Json
如果要求成功,伺服器會以 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" }, "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" }
Java
Node.js
Python
建構搜尋查詢
查詢字串是一系列以網址形式編碼的 name=value
配對。搜尋會以邏輯 AND
組合所有配對。每個值都可以是逗號分隔的值清單,這些值會視為這些值的邏輯 OR
。舉例來說,Patient?key1=value1&key2=value2,value3
是依下列條件搜尋病患資源:
(key1 = value1) AND (key2 = value2 OR key2 = value3)
無法對兩組 OR
執行 name=value
運算。name=value
每個 FHIR 資源類型都會在各個 FHIR 版本中定義自己的搜尋參數。如要瞭解可用參數,請參閱各項資源的 FHIR 規格。如需範例,請參閱 FHIR R4 Patient。 您可以透過功能陳述式,以程式輔助方式擷取參數。 Cloud Healthcare API 支援大多數的搜尋參數;如要瞭解例外狀況,請參閱功能聲明或 FHIR 符合聲明。
分頁和排序
FHIR 搜尋結果每頁傳回的資源數量取決於下列因素:
_count
參數。這項參數可控管搜尋方法傳回的資源數量上限。舉例來說,_count=10
最多會傳回 10 個符合查詢條件的資源。預設值為 100,上限為 1,000。- 回應資料的大小。如果回應大小超出上限,搜尋結果頁面傳回的資源數量可能會少於
_count
參數指定的值。
如果搜尋傳回的資源數量超過一頁可容納的資源數量,回應會在 Bundle.link
欄位中加入分頁網址。這個欄位可能會傳回多個值;Bundle.link.relation = next
值表示您可以使用對應的 Bundle.link.url
擷取下一頁。
Bundle.total
的值表示相符資源的總數。如果結果完全符合一頁,這個值就是確切的數字,但如果結果數量超過一頁,這個值就會變成粗略的估計值。如要取得符合多個結果的搜尋確切總數,請重複點選分頁連結,直到所有結果都顯示完畢為止。
如要進一步瞭解分頁和搜尋總計,請參閱「使用 FHIR 搜尋導入分頁和搜尋總計」。
您可以使用 _sort
參數排序結果,這個參數會接受以逗號分隔的搜尋參數名稱清單,並依優先順序排序。您可以使用 -
前置字元表示遞減順序。舉例來說,下列查詢會依狀態升序排序,並依日期降序排序,如果仍有相同項目,則依類別升序排序:
_sort=status,-date,category
_sort
僅支援 number
、data
、string
、token
和 quantity
類型的搜尋參數。如要使用其他類型的搜尋參數 (例如 reference
) 排序,請使用 FHIR 自訂搜尋,在 reference
欄位中建立 string
搜尋參數。
建立索引延遲
FHIR 資源會以非同步方式建立索引,因此資源建立或變更後,可能需要過一段時間,變更才會反映在搜尋結果中。唯一的例外是資源 ID 資料,這類資料會以特殊索引的形式同步建立索引。因此,使用資源 ID 搜尋時,不會受到索引延遲的影響。如要使用特殊同步索引,識別碼的搜尋字詞應採用 identifier=[system]|[value]
或 identifier=[value]
模式,且可使用下列任一搜尋結果參數:
_count
_include
_revinclude
_summary
_elements
如果查詢包含任何其他搜尋參數,系統會改用標準非同步索引。請注意,針對特殊索引進行搜尋時,系統會盡量找出少量相符項目。如果您的 ID 搜尋條件與大量 (超過 2,000 個) 資源相符,搜尋作業就不會經過最佳化。如果搜尋查詢會比對大量資源,您可以在查詢中加入額外的 _sort
參數,避免使用特殊的同步索引。如要保留預設排序順序,請使用 _sort=-_lastUpdated
。
搜尋所有資源類型
某些搜尋參數 (開頭有底線,例如 _id
) 適用於所有資源類型。這些所有資源參數列在「資源類型」的 FHIR 規格中。
使用這些搜尋參數時,您可以從要求路徑中省略資源類型,對多個資源類型執行搜尋。舉例來說,使用 GET .../fhir?_id=1234
而不是 GET .../fhir/Patient?_id=1234
,會搜尋所有 FHIR 資源,而不只是 Patient 資源。您可以在這類要求中使用特殊參數 _type
,將結果限制為以半形逗號分隔的資源類型清單。舉例來說,下列查詢只會傳回 Observation
和 Condition
資源的相符結果:
GET .../fhir?_tag=active&_type=Observation,Condition
資料類型
FHIR 定義的每個搜尋參數都有資料型別,包括下列原始型別:
- 字串
- 數字
- 日期
資料型別也包括下列複雜型別:
- 權杖
- 參考資料
- 數量
每種資料類型都有專屬的語法,可指定值。每種資料類型都支援修飾符,可改變搜尋的執行方式。
以下各節說明如何使用資料型別。如要進一步瞭解其他資料類型、值語法和修飾符,請參閱進階 FHIR 搜尋功能。
數字
搜尋整數或浮點值。如要變更比較子,請在值前面加上下列其中一個修飾符:
ne
lt
le
gt
ge
例如,使用 [parameter]=100
表示相等,或使用 [parameter]=ge100
表示大於或等於 100。
日期
搜尋任何類型的日期、時間或時間範圍。日期參數格式如下:
yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]
適用於數字的前置字元修飾符也適用於此。
字串
預設為前置字串搜尋,不區分大小寫、重音或其他變音符號。
權杖
搜尋與「code」完全相符的字串。您可以將搜尋範圍限定為「系統」的 URI,指出程式碼設定的值是取自下列格式:
[parameter]=[system]|[code]
舉例來說,下列搜尋會比對 10738-3 的代碼,但僅限於符合特定 URI 編碼系統的值時:
code=http://hl7.org/fhir/ValueSet/observation-codes|10738-3
數量
使用與數字相同的前置字元修飾符,搜尋數值。你可以使用特定系統和代碼來限定搜尋範圍,指出值的單位,格式如下:
[parameter]=[prefix][number]|[system]|[code]
舉例來說,下列查詢會搜尋數量值小於 9.1,且具有指定單位系統和代碼的值:
value-quantity=lt9.1|http://unitsofmeasure.org|mg
參考資料
搜尋資源之間的參照。您可以透過下列查詢,參照 FHIR 儲存庫中的資源:
[parameter]=[id]
[parameter]=[type]/[id]
您可以使用 [parameter]=[url]
,依網址指定參照,這些參照可能位於 FHIR 存放區外部。
處理搜尋參數
根據預設,搜尋方法會套用「寬鬆」處理設定,忽略搜尋無法辨識的參數。搜尋方法會使用要求中的所有剩餘參數執行搜尋,因此可能會傳回超出預期的資源。
回應會包含下列項目:
Bundle.link
中的值,且值為Bundle.link.relation = self
- 網址的
Bundle.link.url
,其中只包含已成功套用至搜尋的參數。您可以檢查這個值,判斷是否有任何參數遭到忽略。
您可以在搜尋要求中將要求 HTTP 標頭設為 Prefer: handling=strict
。設定標頭後,FHIR 存放區就會針對任何無法辨識的參數傳回錯誤。