En esta página, se muestra cómo usar el método projects.locations.datasets.fhirStores.fhir.search
para buscar recursos en una tienda de FHIR determinada. Puedes llamar al método de diferentes maneras mediante las solicitudes GET
o POST
. La especificación de búsqueda de FHIR incluye un amplio conjunto de funciones de consulta. En esta página, se resumen muchas de las funciones de uso común, pero no se enumeran de forma exhaustiva las partes de la especificación de búsqueda compatibles con la API de Cloud Healthcare.
Usa el método search
con GET
En los siguientes ejemplos, se muestra cómo buscar recursos en una tienda de FHIR determinada mediante el método projects.locations.datasets.fhirStores.fhir.search
con GET
.
curl
Para buscar recursos en una tienda de FHIR, realiza una solicitud GET
y especifica la siguiente información:
- El nombre del conjunto de datos
- El nombre de la tienda de FHIR
- El tipo de recurso que deseas buscar
- Una string de consulta que contiene la información que buscas, como se describe en la sección Cómo construir una búsqueda
- Un token de acceso
En el siguiente ejemplo, se muestra una solicitud GET
mediante curl
para buscar todos los pacientes con el apellido "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"
Si la solicitud es exitosa, el servidor mostrará la respuesta como un Bundle
de FHIR en formato JSON. Bundle.type
es searchset
y los resultados de la búsqueda son entradas en el arreglo Bundle.entry
. En este ejemplo, la solicitud muestra un solo recurso Patient que incluye los datos dentro de ese recurso:
{ "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
Para buscar recursos en una tienda de FHIR, realiza una solicitud GET
y especifica la siguiente información:
- El nombre del conjunto de datos
- El nombre de la tienda de FHIR
- El tipo de recurso que deseas buscar
- Una string de consulta que contiene la información que buscas, como se describe en la sección Cómo construir una búsqueda
- Un token de acceso
En el siguiente ejemplo, se muestra una solicitud GET
mediante Windows PowerShell para buscar todos los pacientes con el apellido "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
Si la solicitud es exitosa, el servidor mostrará la respuesta como un Bundle
de FHIR en formato JSON. Bundle.type
es searchset
y los resultados de la búsqueda son entradas en el arreglo Bundle.entry
. En este ejemplo, la solicitud muestra un solo recurso Patient que incluye los datos dentro de ese recurso:
{ "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
Usa el método search
con POST
En los siguientes ejemplos, se muestra cómo buscar recursos en una tienda de FHIR determinada mediante el método projects.locations.datasets.fhirStores.fhir.search
con POST
.
curl
Para buscar recursos en una tienda de FHIR, realiza una solicitud POST
y especifica la siguiente información:
- El nombre del conjunto de datos
- El nombre de la tienda de FHIR
- El tipo de recurso que deseas buscar
- Una string de consulta que contiene la información que buscas, como se describe en la sección Cómo construir una búsqueda
- Un token de acceso
En el siguiente ejemplo, se muestra una solicitud POST
mediante curl
para buscar todos los pacientes con el apellido "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"
Si la solicitud es exitosa, el servidor mostrará la respuesta como un Bundle
de FHIR en formato JSON. Bundle.type
es searchset
y los resultados de la búsqueda son entradas en el arreglo Bundle.entry
. En este ejemplo, la solicitud muestra un solo recurso Patient que incluye los datos dentro de ese recurso:
{ "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
Para buscar recursos en una tienda de FHIR, realiza una solicitud POST
y especifica la siguiente información:
- El nombre del conjunto de datos
- El nombre de la tienda de FHIR
- El tipo de recurso que deseas buscar
- Una string de consulta que contiene la información que buscas, como se describe en la sección Cómo construir una búsqueda
- Un token de acceso
En el siguiente ejemplo, se muestra una solicitud POST
mediante Windows PowerShell para buscar todos los pacientes con el apellido "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
Si la solicitud es exitosa, el servidor mostrará la respuesta como un Bundle
de FHIR en formato JSON. Bundle.type
es searchset
y los resultados de la búsqueda son entradas en el arreglo Bundle.entry
. En este ejemplo, la solicitud muestra un solo recurso Patient que incluye los datos dentro de ese recurso:
{ "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
Cómo crear una búsqueda
La cadena de consulta es una serie de pares name=value
codificados con el formato de una URL. Una búsqueda combina todos los pares con un AND
lógico. Cada valor puede ser una lista de valores separados por comas, que se tratan como un OR
lógico de esos valores. Por ejemplo:
Patient?key1=value1&key2=value2,value3
Esta es una búsqueda en los recursos de Patient
en función de los siguientes criterios:
(key1 = value1) AND (key2 = value2 OR key2 = value3)
No hay una sintaxis para realizar un OR de dos pares nombre=valor.
Cada tipo de recurso de FHIR define sus propios parámetros de búsqueda en cada versión de FHIR. Los parámetros disponibles se documentan en la especificación de FHIR de cada recurso, por ejemplo, FHIR R4 Patient, y se pueden recuperar de manera programática a través de la declaración de capacidad. La API de Cloud Healthcare admite la mayoría de los parámetros de búsqueda. Las exclusiones se pueden encontrar a través de la declaración de capacidad o de la declaración de conformidad de FHIR.
Paginación y ordenamiento
El parámetro _count
controla la cantidad máxima de recursos que se muestran a partir del método de búsqueda, por ejemplo, _count=10
mostrará como máximo 10 recursos que coincidan con la consulta. El valor predeterminado es 100 y el valor máximo permitido es 1,000.
Si con la búsqueda, se encontraron más recursos que los que caben en una página, la respuesta incluirá una URL de paginación en el campo Bundle.link
. Es posible que se muestren varios valores en este campo. El valor en el que Bundle.link.relation = next
indica que se puede usar la Bundle.link.url
correspondiente para recuperar la siguiente página. El valor de Bundle.total
indica la cantidad total de recursos coincidentes. Este valor será exacto si los resultados caben todos en una página, pero será una estimación aproximada si la cantidad de resultados ocupa mucho más que una página. Solo se puede obtener un total exacto para una búsqueda que coincide con una gran cantidad de resultados si se siguen los vínculos de paginación hasta que se agoten los resultados.
Los resultados se pueden ordenar mediante el parámetro _sort
, que acepta una lista separada por comas de nombres de parámetros de búsqueda en orden de prioridad y que puede tener un prefijo -
de forma opcional para indicar un orden descendente. Por ejemplo:
_sort=status,-date,category
Esta se ordenará por estado de forma ascendente y dividirá los vínculos por fecha de forma descendente y cualquier vínculo restante por categoría de forma ascendente.
Demora en la indexación
Los recursos de FHIR se indexan de forma asíncrona, por lo que puede haber una pequeña demora entre el momento en que se crea o se cambia un recurso y el momento en que el cambio se refleja en los resultados de la búsqueda.
Busca en todos los tipos de recursos
Ciertos parámetros de búsqueda, que se distinguen porque comienzan con un guión bajo como _id
, se aplican a todos los tipos de recursos. Estos parámetros para todos los recursos se enumeran en la especificación de FHIR destinada al tipo Resource
.
Cuando usas estos parámetros de búsqueda, puedes realizar una búsqueda en varios tipos de recursos si omites el tipo de recurso en la ruta de la solicitud. Por ejemplo, si usas GET .../fhir?_id=1234
en lugar de GET .../fhir/Patient?_id=1234
, se busca en todos los recursos en lugar de solo en Patient. El parámetro especial _type
se puede usar con este tipo de solicitud para limitar los resultados a una lista de tipos de recursos separados por comas como, por ejemplo, el siguiente:
GET .../fhir?_tag=active&_type=Observation,Condition
Este solo mostrará los resultados coincidentes para los recursos Observation
y Condition
.
Tipos de datos
Cada parámetro de búsqueda definido por FHIR tiene un tipo de datos, que incluye tipos primitivos, como string, número y fecha, y también tipos complejos, como token, referencia y cantidad. Cada tipo de datos tiene su propia sintaxis para especificar valores y admite modificadores que alteran la forma en que se realiza la búsqueda.
Los siguientes son algunos ejemplos simples de cómo se usan los tipos de datos:
- Número busca en valores de números enteros o de punto flotante. El valor puede tener como prefijo un modificador como
ne, lt, le, gt, ge
a fin de cambiar el comparador, por ejemplo,[parameter]=100
para casos de igualdad o[parameter]=ge100
para casos en los que es mayor o igual que 100. - Fecha busca en cualquier tipo de fecha, hora o período. El formato del parámetro de fecha es
yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]
, y aquí se aplican los mismos modificadores del prefijo que se usan para el número. - String se configura de forma predeterminada como una búsqueda de prefijo que no es sensible al uso de mayúsculas y minúsculas, a los acentos o a otros signos diacríticos.
- Token busca una coincidencia de string exacta de un "código", que abarcan de forma opcional el URI de un "sistema" que indica el conjunto de valores del cual se toma el código mediante el formato
[parameter]=[system]|[code]
. Por ejemplo,code=http://hl7.org/fhir/ValueSet/observation-codes|10738-3
coincidiría con un código de 10738-3, pero solo cuando se califica como un valor de un sistema de codificación que contiene el URI especificado. - Cantidad busca un valor numérico mediante los mismos modificadores de prefijo que el número, que pueden estar calificados de forma opcional con un sistema y código específicos que indiquen las unidades del valor en el formato
[parameter]=[prefix][number]|[system]|[code]
. Por ejemplo,value-quantity=lt9.1|http://unitsofmeasure.org|mg
busca valores de cantidad inferiores a 9.1 que tengan el código y el sistema de unidades especificados. - Referencia busca referencias entre recursos, que se pueden especificar mediante
[parameter]=[id]
o[parameter]=[type]/[id]
para referencias a recursos dentro de la tienda de FHIR o mediante[parameter]=[url]
para referencias por URL que podrían estar fuera la tienda de FHIR.
Puedes encontrar más detalles sobre los tipos de datos adicionales, las sintaxis de valores y los modificadores en las funciones de búsqueda avanzada de FHIR.
Busca en la organización de parámetros
De forma predeterminada, el método de búsqueda aplica la organización "indulgente", que ignora los parámetros que no reconoce y realiza la búsqueda mediante cualquier parámetro restante en la solicitud, lo que podría mostrar más recursos de los esperados.
En la respuesta, se incluirá un valor en Bundle.link
con un valor de Bundle.link.relation = self
y una Bundle.link.url
de una URL que contenga solo los parámetros que se aplicaron correctamente a la búsqueda. Este valor se puede inspeccionar para determinar si se ignoró algún parámetro.
De manera alternativa, si se configura el encabezado HTTP Prefer: handling=strict
en una solicitud de búsqueda, se hará que la tienda de FHIR muestre un error en cualquier parámetro no reconocido.