Visão geral da pesquisa na API do Azure para FHIR
Importante
A API do Azure para FHIR será desativada em 30 de setembro de 2026. Siga as estratégias de migração para fazer a transição para o serviço FHIR dos Serviços de Dados de Saúde do Azure até essa data. Devido à desativação da API do Azure para FHIR, novas implantações não serão permitidas a partir de 1º de abril de 2025. O serviço FHIR dos Serviços de Dados de Saúde do Azure é a versão evoluída da API do Azure para FHIR que permite aos clientes gerenciar serviços FHIR, DICOM e MedTech com integrações em outros serviços do Azure.
A especificação FHIR® (Fast Healthcare Interoperability Resources) define os conceitos básicos de pesquisa de recursos do FHIR. Este artigo guiará você por alguns aspectos importantes da pesquisa de recursos no FHIR. Para obter detalhes completos sobre como pesquisar recursos de FHIR, tente Pesquisar na Especificação FHIR da HL7. Ao longo deste artigo, forneceremos exemplos de sintaxe de pesquisa. Cada pesquisa ocorrerá em relação ao servidor FHIR, que normalmente tem uma URL de https://<FHIRSERVERNAME>.azurewebsites.net. Nos exemplos, usaremos o espaço reservado {{FHIR_URL}} para essa URL.
As pesquisas de FHIR podem ser feitas em um tipo de recurso específico, em um compartimento especificado ou em todos os recursos. A maneira mais simples de executar uma pesquisa no FHIR é usar uma solicitação GET. Por exemplo, se você quiser efetuar pull de todos os pacientes no banco de dados, poderá usar a seguinte solicitação:
GET {{FHIR_URL}}/Patient
Você também pode pesquisar usando POST, o que é útil se a cadeia de caracteres de consulta for muito longa. Para pesquisar usando POST, os parâmetros de pesquisa podem ser enviados como um corpo de formulário. Isso permite uma série mais longa e complexa de parâmetros de consulta que podem ser difíceis de ver e entender em uma cadeia de caracteres de consulta.
Se a solicitação de pesquisa for bem-sucedida, você receberá uma resposta de pacote FHIR com o tipo searchset. Se a pesquisa falhar, você encontrará os detalhes do erro para em OperationOutcome para poder entender por que a pesquisa falhou.
Nas seções a seguir, abordaremos os vários aspectos envolvidos na pesquisa. Depois de examinar esses detalhes, confira nossa página de exemplos, com exemplos de pesquisas possíveis na API do Azure para FHIR.
Parâmetros de pesquisa
Ao fazer uma pesquisa, você pesquisará com base em vários atributos do recurso. Esses atributos são chamados de parâmetros de pesquisa. Cada recurso tem um conjunto de parâmetros de pesquisa definidos. O parâmetro de pesquisa deve ser definido e indexado no banco de dados para que você pesquise com êxito.
Cada parâmetro de pesquisa tem tipos de dados definidos. Veja abaixo uma descrição do suporte para os vários tipos de dados:
Aviso
Atualmente, há um problema ao usar _sort na API do Azure para FHIR com pesquisa encadeada. Para saber mais, confira a questão de código aberto nº 2344. Isso será resolvido durante um lançamento em dezembro de 2021.
| Pesquisar tipo de parâmetro | API do Azure para FHIR | Serviço FHIR nos Serviços de Dados de Saúde do Azure | Comentário |
|---|---|---|---|
| number | Sim | Yes | |
| date | Sim | Sim | |
| string | Sim | Yes | |
| token | Sim | Yes | |
| reference | Sim | Yes | |
| composto | Parcial | Parcial | A lista de tipos compostos com suporte é fornecida posteriormente neste artigo. |
| quantity | Sim | Yes | |
| uri | Sim | Yes | |
| especial | Não | Não |
Parâmetros de pesquisa comum
Há parâmetros de pesquisa comuns que se aplicam a todos os recursos. Eles estão listados abaixo, juntamente com o suporte na API do Azure para FHIR:
| Parâmetro de pesquisa comum | API do Azure para FHIR | Serviço FHIR nos Serviços de Dados de Saúde do Azure | Comentário |
|---|---|---|---|
| _id | Sim | Yes | |
| _lastUpdated | Sim | Yes | |
| _tag | Sim | Yes | |
| _type | Sim | Yes | |
| _security | Sim | Yes | |
| _profile | Sim | Yes | |
| _has | Partial | Sim | O suporte para _has está em MVP na API do Azure para FHIR e na versão de software de código aberto com suporte do Azure Cosmos DB. Veja mais detalhes na seção de encadeamento abaixo. |
| _query | Não | Não | |
| _filter | Não | Não | |
| _list | Não | Não | |
| _text | Não | Não | |
| _content | Não | Não |
Parâmetros específicos ao recurso
Com a API do Azure para FHIR, damos suporte a quase todos os parâmetros de pesquisa específicos ao recurso definidos pela especificação FHIR. Os únicos parâmetros de pesquisa para os quais não damos suporte estão disponíveis nos links abaixo:
Você também pode ver o suporte atual para parâmetros de pesquisa na Instrução de Funcionalidade FHIR com a seguinte solicitação:
GET {{FHIR_URL}}/metadata
Para ver os parâmetros de pesquisa na instrução de funcionalidade, navegue até CapabilityStatement.rest.resource.searchParam ver os parâmetros de pesquisa para cada recurso e até CapabilityStatement.rest.searchParam para localizar os parâmetros de pesquisa para todos os recursos.
Observação
A API do Azure para FHIR não cria ou indexa automaticamente os parâmetros de pesquisa que não são definidos pela especificação FHIR. No entanto, fornecemos suporte para que você defina seus próprios parâmetros de pesquisa.
Parâmetros de pesquisa compostos
A pesquisa composta permite a pesquisa em pares de valor. Por exemplo, se você estivesse procurando uma observação de altura em que a pessoa tinha 60 polegadas, iria querer ter certeza de que um único componente da observação continha o código de altura e o valor de 60. Você não iria querer uma observação em que um peso de 60 e altura de 48 tivessem sido armazenados, apesar de a observação ter entradas qualificadas para o valor de 60 e o código de altura, apenas em seções de componentes diferentes.
Com a API do Azure para FHIR, damos suporte aos seguintes emparelhamentos de tipo de parâmetro de pesquisa:
- Referência, Token
- Token, Data
- Token, Número, Número
- Token, Quantidade
- Token, Cadeia de caracteres
- Token, Token
Para saber mais, confira os Parâmetros de pesquisa compostos da HL7.
Observação
Os parâmetros de pesquisa compostos não dão suporte a modificadores, de acordo com a especificação FHIR.
Modificadores & prefixos
Os modificadores permitem modificar o parâmetro de pesquisa. Veja abaixo uma visão geral de todos os modificadores FHIR e o suporte na API do Azure para FHIR.
| Modificadores | API do Azure para FHIR | Serviço FHIR nos Serviços de Dados de Saúde do Azure | Comentário |
|---|---|---|---|
| :missing | Sim | Yes | |
| :exact | Sim | Yes | |
| :contains | Sim | Yes | |
| :text | Sim | Yes | |
| :type (reference) | Sim | Yes | |
| :not | Sim | Yes | |
| :below (uri) | Sim | Yes | |
| :above (uri) | Sim | Yes | |
| :in (token) | Não | Não | |
| :below (token) | Não | Não | |
| :above (token) | Não | Não | |
| :not-in (token) | Não | Não |
Para parâmetros de pesquisa que têm uma ordem específica (números, datas e quantidades), você pode usar um prefixo no parâmetro para ajudar na localização de correspondências. A API do Azure para FHIR dá suporte a todos os prefixos.
Parâmetros de resultado de pesquisa
Para ajudar a gerenciar os recursos retornados, há parâmetros de resultado de pesquisa que você pode usar em sua pesquisa. Para obter detalhes sobre como usar cada um dos parâmetros de resultado da pesquisa, confira o site da HL7.
| Parâmetros de resultado de pesquisa | API do Azure para FHIR | Serviço FHIR nos Serviços de Dados de Saúde do Azure | Comentário |
|---|---|---|---|
| _elements | Sim | Yes | |
| _contar | Sim | Yes | _count é limitado a 1000 recursos. Se for definido acima de 1000, apenas 1000 retornarão e um aviso será incluído no pacote. |
| _include | Sim | Yes | Os itens incluídos são limitados a 100. _include no PaaS e no OSS no Azure Cosmos DB não incluem o suporte a :iterate (nº 2137). |
| _revinclude | Sim | Yes | Os itens incluídos são limitados a 100. _revinclude no PaaS e no OSS no Azure Cosmos DB não incluem o suporte a :iterate (nº 2137). Há também um código de status incorreto para uma solicitação incorreta nº 1319 |
| _summary | Sim | Yes | |
| _total | Parcial | Parcial | _total=none e _total=accurate |
| _sort | Parcial | Parcial | Há suporte para sort=_lastUpdated na API do Azure para FHIR e no serviço FHIR. Para bancos de dados da API do Azure para FHIR e Azure Cosmos DB de software de código aberto criados após 20 de abril de 2021, há suporte para classificação em nome, sobrenome, data de nascimento e clínica. |
| _contained | Não | Não | |
| _containedType | Não | Não | |
| _score | Não | Número |
Observação
Por padrão _sort classifica o registro em ordem crescente. Você pode usar o prefixo '-' para classificar em ordem decrescente. Além disso, o serviço FHIR e a API do Azure para FHIR só permitem que você classifique em um único campo por vez.
Por padrão, a API do Azure para FHIR é definida como manipulação branda. Isso significa que o servidor ignorará quaisquer parâmetros desconhecidos ou sem suporte. Se você quiser usar a manipulação estrita, poderá usar o cabeçalho Prefer e definir handling=strict.
Encadeado & pesquisa encadeada reversa
Uma pesquisa encadeada permite que você pesquise com um parâmetro de pesquisa em um recurso referenciado por outro recurso. Por exemplo, se você quiser achar encontros em que o nome da paciente é Jane, use:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
Da mesma forma, você pode fazer uma pesquisa encadeada reversa. Ela permite que você obtenha recursos em que você especifica critérios em outros recursos que se referem a eles. Para obter mais exemplos de pesquisa encadeada e encadeada reversa, confira a página de exemplos de pesquisa do FHIR.
Observação
Na API do Azure para FHIR e no código aberto apoiado pelo Azure Cosmos DB, há uma limitação em que cada subconsulta necessária para as pesquisas encadeadas e encadeadas inversas retornará apenas 1000 itens. Se mais de 1000 itens forem encontrados, você receberá a seguinte mensagem de erro: "Subconsultas em uma expressão encadeada não podem retornar mais de 1000 resultados, use um critério mais seletivo". Para obter uma consulta bem-sucedida, você precisará ser mais específico no que está procurando.
Paginação
Conforme mencionado acima, os resultados de uma pesquisa serão um pacote paginado. Por padrão, a pesquisa retornará 10 resultados por página, mas é possível aumentar (ou diminuir) esse valor especificando _count. Dentro do pacote, haverá um autolink com o resultado atual da pesquisa. Se houver correspondências adicionais, o pacote conterá um próximo link. Você pode continuar usando o próximo link para obter as páginas subsequentes dos resultados. _count é limitado a 1000 itens ou menos.
O próximo link no pacote tem um limite de tamanho de token de continuação de 3 KB. Você tem flexibilidade para ajustar o tamanho do token de continuação entre 1 a 3KB, usando o cabeçalho "x-ms-documentdb-responsecontinuationtokenlimitinkb".
Atualmente, a API do Azure para FHIR dá suporte apenas ao próximo link em pacotes e não dá suporte aos links primeiro, último ou anterior.
Próximas etapas
Agora que você aprendeu sobre os conceitos básicos da pesquisa, confira a página de exemplos de pesquisa para obter detalhes sobre como pesquisar usando parâmetros de pesquisa diferentes, modificadores e outros cenários de pesquisa FHIR.
FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.