本页面介绍了如何在 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 查看器页面。
在 FHIR 存储区 (FHIR Store) 下拉列表中,选择一个数据集,然后在该数据集中选择 FHIR 存储区。
如需过滤资源类型列表,请搜索您要显示的资源类型:
点击资源类型字段。
在显示的属性下拉列表中,选择资源类型。
输入一种资源类型。
如需搜索其他资源类型,请从显示的运算符下拉列表中选择 OR,然后输入其他资源类型。
在资源类型列表中,选择您要搜索的资源类型。
在显示的资源表的搜索框中,输入您要搜索的值。
FHIR 查看器会在表中显示搜索结果。选择一种资源后,FHIR 查看器会显示该资源的内容。
查看某资源的内容时,您可以搜索该资源内的数据。
如需搜索资源内的数据,请按照以下步骤操作:
选择一种资源。
在 FHIR 查看器窗格中,点击元素标签页。
在搜索框中,输入您要搜索的值。
下载 FHIR 资源中的二进制数据
如需下载与 FHIR 查看器中的资源关联的可用二进制数据,请按照以下步骤操作:
选择资源。
在 FHIR 查看器窗格中,点击元素标签页。
如有必要,请展开元素以访问所需的资源元素。
点击下载文件以下载可用数据。
创建并运行高级搜索查询
您可以使用高级搜索查询根据 FHIR 搜索规范搜索特定的 FHIR 资源。
如需创建高级搜索查询,请完成以下步骤:
在 FHIR 查看器页面上,点击搜索标签页。
如需创建搜索查询,请点击打开查询构建器。
随即会显示查询选择面板。
从选择 FHIR 资源类型列表中,选择要搜索的 FHIR 资源类型。
点击继续。
从参数列表中,选择您要用于搜索资源的参数。
从修饰符列表中,选择要应用于查询的修饰符。该列表仅包含与所选参数的数据类型兼容的修饰符。
这是一个可选选项。如果未选择任何修饰符,则执行相等性检查。
在值字段中,输入查询参数的值。
如需添加多个参数值,请点击 OR。这使您可以在搜索查询中包含多个资源参数值。
构建搜索查询时,查询会显示在查询预览窗格中。如需查看搜索查询的完整网址,请点击显示完整路径。
如需添加多个参数,请点击 AND。
点击继续。
如需包含由搜索查询中返回的资源引用的资源,请从包含的参数下拉列表中选择资源参数。
如需包含引用搜索查询中返回的资源的资源,请从反向包含的参数下拉列表中选择资源参数。
点击完成以保存搜索查询。
保存的搜索查询会显示在 FHIR 搜索操作字段中。
如需使用查询搜索资源,请点击运行搜索。
搜索结果会显示在搜索结果列表中。如需查看有关搜索返回的资源的详细信息,请点击此列表中的资源。
如需将查询保存为查询模板,请点击保存模板,然后选择保存模板或将模板另存为。系统会提示您输入查询的名称和说明。查询参数会保存在模板中,但所有已定义的值都会被移除。
搜索查询示例
以下示例展示了一个搜索查询,该查询会搜索来自 2021 年 8 月特定医疗服务提供方 Practitioner/12345 的 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
- 前缀:
查询会在查询选择面板中如下配置,您可以在查询预览窗格中预览此查询。查询会显示在 FHIR 搜索操作字段中。
修改搜索查询
如需修改搜索查询,请执行以下操作之一:
- 如需在查询构建器中修改查询,请点击打开查询构建器。
- 如需手动修改查询,请修改文本框中的参数值。
运行查询模板
如需从已保存的模板运行查询,请完成以下步骤:
点击已保存的模板。
随即会显示查询选择面板的搜索模板标签页,其中显示了所有已保存的查询模板。
选择要运行的查询模板,然后点击完成。
该模板的搜索查询会显示在 FHIR 搜索操作字段中且未定义任何值。
如需定义搜索查询的值,请修改此字段中的参数值。
点击运行搜索以使用查询搜索资源。
使用 search
方法
要使用 REST API 搜索 FHIR 资源,请使用 projects.locations.datasets.fhirStores.fhir.search
方法。您可以使用 GET
或 POST
请求调用此方法。
使用 search
方法和 GET
以下示例展示了如何使用 projects.locations.datasets.fhirStores.fhir.search
方法和 GET
在给定 FHIR 存储区中搜索资源。
curl
要搜索 FHIR 存储区中的资源,请发出 GET
请求并指定以下信息:
- 数据集的名称
- FHIR 存储区的名称
- 要搜索的资源类型
- 查询字符串包含要搜索的信息,如构建搜索查询部分中所述
- 访问令牌
以下示例显示了一个使用 curl
搜索所有姓“Smith”患者的 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/fhirStores/FHIR_STORE_ID/fhir/Patient?family:exact=Smith"
如果请求成功,服务器将以 JSON 格式的 FHIR Bundle
形式返回响应。Bundle.type
是 searchset
,搜索结果是 Bundle.entry
数组中的条目。在此示例中,请求返回单个患者资源,包括该资源内的数据:
{ "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 搜索所有姓“Smith”患者的 GET
请求。
$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
数组中的条目。在此示例中,请求返回单个患者资源,包括该资源内的数据:
{ "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
使用 search
方法和 POST
以下示例展示了如何使用 projects.locations.datasets.fhirStores.fhir.search
方法和 POST
在给定 FHIR 存储区中搜索资源。
curl
要搜索 FHIR 存储区中的资源,请发出 POST
请求并指定以下信息:
- 数据集的名称
- FHIR 存储区的名称
- 要搜索的资源类型
- 查询字符串包含要搜索的信息,如构建搜索查询部分中所述
- 访问令牌
以下示例显示了一个使用 curl
搜索所有姓“Smith”患者的 POST
请求。
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
数组中的条目。在此示例中,请求返回单个患者资源,包括该资源内的数据:
{ "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 搜索所有姓“Smith”患者的 POST
请求。
$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
数组中的条目。在此示例中,请求返回单个患者资源,包括该资源内的数据:
{ "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)
没有语法可执行两个 name=value
对的 OR
。
每种 FHIR 资源类型都会在每个版本的 FHIR 中定义自己的搜索参数。可用参数记录在每个资源的 FHIR 规范中。如需查看示例,请参阅 FHIR R4 患者。您可以通过功能语句以编程方式检索参数。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
索引延迟
FHIR 资源以异步方式编入索引,因此创建或更改资源的时间与搜索结果中反映相应更改的时间之间可能会略有延迟。唯一的例外是资源标识符数据,该数据作为特殊索引同步编入索引。因此,使用资源标识符进行搜索时不会受到索引延迟的影响。如需使用特殊的同步索引,标识符的搜索字词应采用 identifier=[system]|[value]
或 identifier=[value]
格式,并且可以使用以下任一搜索结果参数:
_count
_include
_revinclude
_summary
_elements
如果您的查询包含任何其他搜索参数,系统将改用标准异步索引。请注意,针对特殊索引搜索针对解析少量匹配项进行了优化。如果标识符搜索条件与大量资源(即超过 2,000 个)匹配,则搜索不会得到优化。对于与大量资源匹配的搜索查询,您可以在查询中添加一个额外的 _sort
参数,以避免使用特殊同步索引。如果要保留默认排序顺序,请使用 _sort=-_lastUpdated
。
搜索所有资源类型
某些搜索参数(通过 _id
等前导下划线显示)适用于所有资源类型。这些全资源参数在资源类型的 FHIR 规范中列出。
使用这些搜索参数时,您可以通过从请求路径中省略资源类型,跨多个资源类型执行搜索。例如,使用 GET .../fhir?_id=1234
而不是 GET .../fhir/Patient?_id=1234
搜索所有 FHIR 资源,而不是仅搜索患者资源。您可以对此类请求使用特殊参数 _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]
使用与 number 相同的前缀修饰符。
字符串
默认为不区分大小写、重音符号或其他变音符号的前缀搜索。
令牌
搜索“code”的完全匹配字符串您可以将搜索范围限定为“system”的 URI,并使用以下格式指示从中获取代码的值集:
[parameter]=[system]|[code]
例如,仅当被限定为具有指定 URI 的编码系统的值时,以下搜索与 10738-3 的代码匹配:
code=http://hl7.org/fhir/ValueSet/observation-codes|10738-3
数量
使用与 number 相同的前缀修饰符搜索数值。您可以使用特定系统和代码来限定搜索,以下列格式指示值的单位:
[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 存储在任何无法识别的参数上返回错误。