Nesta página, mostramos como usar o método projects.locations.datasets.fhirStores.fhir.search
para pesquisar recursos em um determinado armazenamento FHIR. É possível chamar o método de maneiras diferentes usando as solicitações GET
ou POST
. A especificação de pesquisa FHIR inclui um amplo conjunto de funcionalidades de consulta. Esta página resume muitos dos recursos mais usados, mas não é uma lista completa dos componentes da especificação de pesquisa compatíveis com a API Cloud Healthcare.
Como usar o método search
com GET
Os exemplos a seguir mostram como pesquisar recursos em um determinado armazenamento FHIR usando o método projects.locations.datasets.fhirStores.fhir.search
com GET
.
curl
Para pesquisar recursos em um armazenamento FHIR, faça uma solicitação GET
e especifique as seguintes informações:
- O nome do conjunto de dados
- O nome do armazenamento FHIR
- O tipo de recurso a ser pesquisado
- Uma string de consulta contendo as informações que você está pesquisando, conforme descrito na seção Como criar uma consulta de pesquisa
- Um token de acesso
O exemplo a seguir mostra uma solicitação GET
usando curl
para pesquisar todos os pacientes com o sobrenome "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"
Se a solicitação for bem-sucedida, o servidor retornará a resposta como um Bundle
do FHIR no formato JSON. O Bundle.type
é searchset
, e os resultados da pesquisa são entradas na matriz Bundle.entry
. Neste exemplo, a solicitação retorna um único recurso Paciente, incluindo os dados dentro do 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 pesquisar recursos em um armazenamento FHIR, faça uma solicitação GET
e especifique as seguintes informações:
- O nome do conjunto de dados
- O nome do armazenamento FHIR
- O tipo de recurso a ser pesquisado
- Uma string de consulta contendo as informações que você está pesquisando, conforme descrito na seção Como criar uma consulta de pesquisa
- Um token de acesso
O exemplo a seguir mostra uma solicitação GET
usando o Windows PowerShell para pesquisar todos os pacientes com o sobrenome "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
Se a solicitação for bem-sucedida, o servidor retornará a resposta como um Bundle
do FHIR no formato JSON. O Bundle.type
é searchset
, e os resultados da pesquisa são entradas na matriz Bundle.entry
. Neste exemplo, a solicitação retorna um único recurso Paciente, incluindo os dados dentro do 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
Como usar o método search
com POST
Os exemplos a seguir mostram como pesquisar recursos em um determinado armazenamento FHIR usando o método projects.locations.datasets.fhirStores.fhir.search
com POST
.
curl
Para pesquisar recursos em um armazenamento FHIR, faça uma solicitação POST
e especifique as seguintes informações:
- O nome do conjunto de dados
- O nome do armazenamento FHIR
- O tipo de recurso a ser pesquisado
- Uma string de consulta contendo as informações que você está pesquisando, conforme descrito na seção Como criar uma consulta de pesquisa
- Um token de acesso
O exemplo a seguir mostra uma solicitação POST
usando curl
para pesquisar todos os pacientes com o sobrenome "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"
Se a solicitação for bem-sucedida, o servidor retornará a resposta como um Bundle
do FHIR no formato JSON. O Bundle.type
é searchset
, e os resultados da pesquisa são entradas na matriz Bundle.entry
. Neste exemplo, a solicitação retorna um único recurso Paciente, incluindo os dados dentro do 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 pesquisar recursos em um armazenamento FHIR, faça uma solicitação POST
e especifique as seguintes informações:
- O nome do conjunto de dados
- O nome do armazenamento FHIR
- O tipo de recurso a ser pesquisado
- Uma string de consulta contendo as informações que você está pesquisando, conforme descrito na seção Como criar uma consulta de pesquisa
- Um token de acesso
O exemplo a seguir mostra uma solicitação POST
usando o Windows PowerShell para pesquisar todos os pacientes com o sobrenome "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
Se a solicitação for bem-sucedida, o servidor retornará a resposta como um Bundle
do FHIR no formato JSON. O Bundle.type
é searchset
, e os resultados da pesquisa são entradas na matriz Bundle.entry
. Neste exemplo, a solicitação retorna um único recurso Paciente, incluindo os dados dentro do 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
Como criar uma consulta de pesquisa
A string de consulta é uma série de pares name=value
codificados no formato de URL. Uma pesquisa combina todos os pares com um AND
lógico. Cada valor pode ser uma lista de valores separados por vírgulas, que são tratados como um OR
lógico desses valores. Exemplo:
Patient?key1=value1&key2=value2,value3
é uma pesquisa por recursos Patient
pelos critérios:
(key1 = value1) AND (key2 = value2 OR key2 = value3)
Não há sintaxe para executar um OR de dois pares nome=valor.
Cada tipo de recurso do FHIR define os próprios parâmetros de pesquisa em cada versão do FHIR. Os parâmetros disponíveis são documentados na especificação FHIR para cada recurso, por exemplo, Paciente R4 FHIR, e podem ser recuperados programaticamente por meio da instrução de capacidade. A API Cloud Healthcare é compatível com a maioria dos parâmetros de pesquisa. As exclusões podem ser encontradas por meio da instrução de capacidade ou da instrução de conformidade com FHIR.
Paginação e classificação
O número máximo de recursos retornados do método de pesquisa é controlado pelo parâmetro _count
. Por exemplo, _count=10
retornará no máximo dez recursos correspondentes à consulta. O padrão é 100 e o valor máximo permitido é 1.000.
Se a pesquisa encontrou mais recursos do que cabem em uma página, a resposta incluirá um URL de paginação no campo Bundle.link
. Pode haver vários valores retornados nesse campo. O valor com Bundle.link.relation = next
indica que o Bundle.link.url
correspondente pode ser usado para recuperar a próxima página. O valor de Bundle.total
indica o número total de recursos correspondentes. Esse valor será exato se os resultados se encaixarem totalmente em uma página, mas uma estimativa aproximada, pois o número de resultados se torna muito maior do que uma página. Um total exato de uma pesquisa que corresponde a um grande número de resultados só pode ser obtido seguindo os links de paginação repetidamente até que os resultados se esgotem.
Os resultados podem ser classificados usando o parâmetro _sort
, que aceita uma lista separada por vírgulas de nomes de parâmetros de pesquisa em ordem de prioridade, opcionalmente com um prefixo -
para indicar a ordem decrescente. Exemplo:
_sort=status,-date,category
classificará por status crescente, desempatando por data decrescente e desempatando o restante por categoria crescente.
Atraso na indexação
Os recursos do FHIR são indexados de forma assíncrona. Portanto, pode haver um pequeno atraso entre o momento em que um recurso é criado ou alterado e quando a alteração é refletida nos resultados da pesquisa.
Como pesquisar em todos os tipos de recursos
Alguns parâmetros de pesquisa, diferenciados por um sublinhado à esquerda, como _id
, aplicam-se a todos os tipos de recursos. Esses parâmetros de todos os recursos estão listados na especificação FHIR para o tipo Resource
.
Ao usar esses parâmetros de pesquisa, você pode realizar uma pesquisa em vários tipos de recursos omitindo o tipo de recurso do caminho da solicitação. Por exemplo, GET .../fhir?_id=1234
em vez de GET .../fhir/Patient?_id=1234
pesquisa em todos os recursos, não apenas em pacientes. O parâmetro especial _type
pode ser usado com esse tipo de solicitação para limitar os resultados a uma lista separada por vírgulas de tipos de recursos, por exemplo:
GET .../fhir?_tag=active&_type=Observation,Condition
retornará apenas resultados correspondentes aos recursos Observation
e Condition
.
Tipos de dados
Cada parâmetro de pesquisa definido pelo FHIR tem um tipo de dados, que inclui tipos primitivos, como string, número e data, e também tipos complexos, como token, referência e quantidade. Cada tipo de dados tem sua própria sintaxe para especificar valores e suporta modificadores que alteram como a pesquisa é realizada.
Veja alguns exemplos simples de como os tipos de dados são usados:
- Número pesquisa valores inteiros ou de ponto flutuante. O valor pode ser prefixado com um modificador como
ne, lt, le, gt, ge
para alterar o comparador, por exemplo,[parameter]=100
para igualdade,[parameter]=ge100
para maior ou igual a 100. - Data pesquisa qualquer tipo de data, hora ou período. O formato do parâmetro de data é
yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]
, e os mesmos modificadores de prefixo usados para número também se aplicam aqui. - String assume como padrão uma pesquisa de prefixo que não diferencia maiúsculas de minúsculas e acentos ou outros sinais diacríticos.
- Token pesquisa uma correspondência exata de string de um "código", opcionalmente com escopo no URI de um "sistema" indicando o conjunto de valores do qual o código é extraído usando o formato
[parameter]=[system]|[code]
. Por exemplo,code=http://hl7.org/fhir/ValueSet/observation-codes|10738-3
corresponde a um código 10738-3, mas somente quando qualificado como um valor de um sistema de codificação com o URI especificado. - Quantidade pesquisa um valor numérico usando os mesmos modificadores de prefixo que o número, opcionalmente qualificado com um sistema e código específicos que indicam as unidades do valor no formato
[parameter]=[prefix][number]|[system]|[code]
. Por exemplo,value-quantity=lt9.1|http://unitsofmeasure.org|mg
pesquisa valores de quantidade menores que 9.1 com o sistema de unidades e o código especificados. - Referência pesquisa referências entre recursos, que podem ser especificados por
[parameter]=[id]
ou[parameter]=[type]/[id]
para referências a recursos dentro do armazenamento FHIR ou[parameter]=[url]
para referências por URL que podem estar fora do armazenamento FHIR.
Mais detalhes sobre outros tipos de dados, sintaxes de valor e modificadores podem ser encontrados em Recursos de pesquisa avançada do FHIR.
Manipulação dos parâmetros de pesquisa
Por padrão, o método de pesquisa aplica uma manipulação "flexível", que ignora os parâmetros que não reconhece e realiza a pesquisa usando os parâmetros restantes na solicitação, o que pode retornar mais recursos do que o esperado.
A resposta incluirá um valor em Bundle.link
com um valor de Bundle.link.relation = self
e um Bundle.link.url
de um URL contendo apenas os parâmetros que foram aplicados à pesquisa. Esse valor pode ser inspecionado para determinar se algum parâmetro foi ignorado.
Como alternativa, definir o cabeçalho HTTP Prefer: handling=strict
em uma solicitação de pesquisa fará com que o armazenamento FHIR retorne um erro em caso de qualquer parâmetro não reconhecido.