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 gerir serviços FHIR, DICOM e MedTech com integrações noutros serviços do Azure.
A especificação Fast Healthcare Interoperability Resources (FHIR) define os fundamentos da pesquisa de recursos FHIR®. Este artigo orienta você através de alguns aspectos-chave da pesquisa de recursos no FHIR. Para obter detalhes completos sobre como pesquisar recursos FHIR, consulte Pesquisar na especificação FHIR HL7. Ao longo deste artigo, damos exemplos de sintaxe de pesquisa. Cada pesquisa é feita no seu servidor FHIR, que normalmente tem um URL de https://<FHIRSERVERNAME>.azurewebsites.net. Nos exemplos, usamos o espaço reservado {{FHIR_URL}} para essa URL.
As pesquisas FHIR podem ser em relação a um tipo de recurso específico, um compartimento especificado ou todos os recursos. A maneira mais simples de executar uma pesquisa no FHIR é usar uma GET solicitação. Por exemplo, se você quiser puxar todos os pacientes no banco de dados, você pode 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 longa. Para pesquisar usando POSTo , os parâmetros de pesquisa podem ser enviados como um corpo de formulário. Isso permite séries mais longas e complexas 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ê pode encontrar os detalhes do erro no OperationOutcome para ajudá-lo a entender por que a pesquisa falhou.
Nas seções a seguir, abordamos os vários aspetos envolvidos na pesquisa. Depois de revisar esses detalhes, consulte nossa página de exemplos que tem exemplos de pesquisas que você pode fazer na API do Azure para FHIR.
Parâmetros de pesquisa
As pesquisas são baseadas em vários atributos do recurso. Estes atributos são denominados 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ê possa pesquisar com êxito em relação a ele.
Cada parâmetro de pesquisa tem um tipo de dados definido. A tabela a seguir descreve o 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 obter mais informações, consulte a edição de código aberto #2344. Isso será resolvido durante um lançamento em dezembro de 2021.
| Tipo de parâmetro de pesquisa | API do Azure para FHIR | Serviço FHIR nos Serviços de Dados de Saúde do Azure | Comentário |
|---|---|---|---|
| Número | Sim | Sim | |
| data | Sim | Sim | |
| string | Yes | Sim | |
| token | Sim | Sim | |
| referência | Sim | Sim | |
| compósito | Parcial | Parcial | A lista de tipos compostos suportados é descrita posteriormente neste artigo. |
| quantidade | Sim | Sim | |
| uri | Sim | Sim | |
| Especial | No | Não |
Parâmetros de pesquisa comuns
Existem parâmetros de pesquisa comuns que se aplicam a todos os recursos. Eles estão na lista a seguir, juntamente com seu 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 | Sim | |
| _lastUpdated | Sim | Sim | |
| _tag | Sim | Sim | |
| _type | Sim | Sim | |
| _security | Sim | Sim | |
| _profile | Sim | Sim | |
| _has | Parcial | Sim | O suporte para _has está em MVP na API do Azure para FHIR e na versão OSS apoiada pelo Azure Cosmos DB. Mais detalhes estão incluídos na seção de encadeamento a seguir. |
| _query | No | Não | |
| _filter | No | Não | |
| _list | No | Não | |
| _Texto | No | Não | |
| _content | No | Não |
Parâmetros específicos do recurso
Com a API do Azure para FHIR, damos suporte a quase todos os parâmetros de pesquisa específicos de recursos definidos pela especificação FHIR. Os únicos parâmetros de pesquisa que não suportamos estão disponíveis nos seguintes links.
Você também pode ver o suporte atual para parâmetros de pesquisa na Declaração de Capacidade FHIR com a seguinte solicitação.
GET {{FHIR_URL}}/metadata
Para ver os parâmetros de pesquisa na instrução de capacidade, navegue até CapabilityStatement.rest.resource.searchParam para ver os parâmetros de pesquisa para cada recurso e CapabilityStatement.rest.searchParam para encontrar os parâmetros de pesquisa para todos os recursos.
Nota
A API do Azure para FHIR não cria ou indexa automaticamente quaisquer parâmetros de pesquisa que não estejam 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 pesquisar em relação a pares de valores. Por exemplo, se você estava procurando por uma observação de altura onde a pessoa tinha 60 polegadas, você gostaria de ter certeza de que um único componente da observação continha o código de altura e o valor de 60. Você não gostaria de obter uma observação onde um peso de 60 e altura de 48 foi armazenado, mesmo que a observação teria entradas qualificadas para o valor de 60 e código de altura, apenas em diferentes seções de componentes.
Com a API do Azure para FHIR, damos suporte aos seguintes emparelhamentos de tipos de parâmetros de pesquisa.
- Referência, Token
- Token, Data
- Token, Número, Número
- Token, Quantidade
- Token, String
- Token, Token
Para obter mais informações, consulte os parâmetros de pesquisa composta HL7.
Nota
Os parâmetros de pesquisa compostos não suportam modificadores de acordo com a especificação FHIR.
Modificadores e prefixos
Os modificadores permitem modificar o parâmetro de pesquisa. A tabela a seguir é uma visão geral de todos os modificadores FHIR e seu 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 |
|---|---|---|---|
| :ausente | Sim | Sim | |
| :exato | Sim | Sim | |
| :contém | Sim | Sim | |
| :Texto | Sim | Sim | |
| :type (referência) | Sim | Sim | |
| :não | Sim | Sim | |
| :abaixo (uri) | Sim | Sim | |
| :acima (uri) | Sim | Sim | |
| :in (token) | No | Não | |
| :abaixo (token) | No | Não | |
| :acima (token) | No | Não | |
| :not-in (token) | No | 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 a encontrar correspondências. A API do Azure para FHIR dá suporte a todos os prefixos.
Parâmetros dos resultados da pesquisa
Para ajudar a gerenciar os recursos retornados, há parâmetros de resultados de pesquisa que você pode usar. Para obter detalhes sobre como usar cada um dos parâmetros de resultado da pesquisa, consulte o site HL7.
| Parâmetros dos resultados da pesquisa | API do Azure para FHIR | Serviço FHIR nos Serviços de Dados de Saúde do Azure | Comentário |
|---|---|---|---|
| _elements | Sim | Sim | |
| _count | Sim | Sim | _count está limitada a 1000 recursos. Se definido acima de 1000, apenas 1000 são retornados e um aviso será retornado no pacote. |
| _include | Sim | Sim | Os itens incluídos são limitados a 100. _include em PaaS e OSS no Azure Cosmos DB não incluem suporte a :iterate (#2137). |
| _revinclude | Sim | Sim | Os itens incluídos são limitados a 100. _revinclude em PaaS e OSS no Azure Cosmos DB não incluem suporte a :iterate (#2137). Há também um código de status incorreto para uma solicitação incorreta #1319 |
| _summary | Sim | Sim | |
| _total | Parcial | Parcial | _total=nenhum e _total=preciso |
| _sort | Parcial | Parcial | sort=_lastUpdated tem suporte na API do Azure para FHIR e no serviço FHIR. Para bancos de dados do Azure API for FHIR e OSS Azure Cosmos DB criados após 20 de abril de 2021, a classificação é suportada no nome, sobrenome, data de nascimento e data clínica. |
| _contained | No | Não | |
| _containedType | No | Não | |
| _score | No | No |
Nota
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 classificar em um único campo de cada vez.
Por padrão, a API do Azure para FHIR é definida como tratamento leniente. Isso significa que o servidor ignora quaisquer parâmetros desconhecidos ou não suportados. Se você quiser usar um tratamento rigoroso, você pode usar o cabeçalho Preferir e definir handling=strict.
Pesquisa encadeada ou encadeada reversa
Uma pesquisa encadeada permite pesquisar usando um parâmetro de pesquisa em um recurso referenciado por outro recurso. Por exemplo, se você quiser encontrar encontros em que o nome do paciente é Jane, use:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane.
Da mesma forma, pode efetuar uma pesquisa em cadeia invertida. Isto permite-lhe obter recursos onde especifique critérios sobre outros recursos que se referem a eles. Para obter mais exemplos de pesquisa encadeada e encadeada inversa, consulte a página de exemplos de pesquisa FHIR.
Nota
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 retornará apenas 1000 itens. Se houver mais de 1000 itens 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
Como mencionado anteriormente, os resultados de uma pesquisa são um pacote paginado. Por padrão, a pesquisa retorna 10 resultados por página, mas isso pode ser aumentado (ou diminuído) especificando _count. Dentro do pacote, haverá um autolink que contém o resultado atual da pesquisa. Se houver correspondências adicionais, o pacote conterá um próximo link. Você pode continuar a usar o próximo link para obter as páginas subsequentes de resultados. _count é limitado a 1.000 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 KB a 3 KB, 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 oferece suporte a primeiro, último ou links anteriores.
Próximos passos
Agora que você aprendeu sobre os conceitos básicos da pesquisa, consulte a página de exemplos de pesquisa para obter detalhes sobre como pesquisar usando diferentes parâmetros de pesquisa, modificadores e outros cenários de pesquisa FHIR.
Nota
FHIR® é uma marca registada da HL7 e é utilizada com a permissão da HL7.