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 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 dos Serviços de Dados de Saúde do Azure para serviço FHIR é a versão evoluída da API do Azure para FHIR que permite aos clientes gerenciar os serviços FHIR, DICOM e serviço de tecnologia médica com integrações a 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 orienta você por alguns aspectos-chave 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, damos exemplos de sintaxe de pesquisa. Cada pesquisa é feita em relação ao servidor FHIR, que normalmente tem um URL de https://<FHIRSERVERNAME>.azurewebsites.net. Nos exemplos, usamos o espaço reservado {{FHIR_URL}} para esta 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 extrair todos os pacientes no banco de dados, poderá usar a solicitação a seguir.
GET {{FHIR_URL}}/Patient
Você também pode pesquisar usando POST, o que é útil se a string de consulta for 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 do pacote FHIR com o tipo searchset. Se a pesquisa falhar, você poderá 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 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
As pesquisas são baseadas 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. A tabela a seguir descreve o suporte para os vários tipos de dados.
Aviso
Atualmente, há um problema ao usar _sort a API do Azure para FHIR com pesquisa encadeada. Para obter mais informações, consulte o problema de software livre #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 |
|---|---|---|---|
| número | Sim | Sim | |
| date | Sim | Sim | |
| string | Sim | Sim | |
| token | Sim | Sim | |
| reference | Sim | Sim | |
| composto | Parcial | Parcial | A lista de tipos compostos com suporte é descrita posteriormente neste artigo. |
| quantity | Sim | Sim | |
| uri | Sim | Sim | |
| especial | Não | No |
Parâmetros de pesquisa comum
Há 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á no MVP na API do Azure para FHIR e na versão do OSS com suporte do Azure Cosmos DB. Mais detalhes estão incluídos na seção de encadeamento a seguir. |
| _query | Não | No | |
| _filter | Não | No | |
| _list | Não | No | |
| _text | Não | No | |
| _content | Não | No |
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 que não suportamos estão disponíveis nos links a seguir.
Você também pode ver o suporte atual para parâmetros de pesquisa na Declaração de Capacidade FHIR com a solicitação a seguir.
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 de cada recurso e CapabilityStatement.rest.searchParam os parâmetros de pesquisa de 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 você definir 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 pares 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 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 |
|---|---|---|---|
| :missing | Sim | Sim | |
| :exact | Sim | Sim | |
| :contains | Sim | Sim | |
| :text | Sim | Sim | |
| :type (reference) | Sim | Sim | |
| :not | Sim | Sim | |
| :below (uri) | Sim | Sim | |
| :above (uri) | Sim | Sim | |
| :in (token) | Não | No | |
| :below (token) | Não | No | |
| :above (token) | Não | No | |
| :not-in (token) | Não | No |
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. 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 | Sim | |
| _contar | Sim | Sim | _count é limitado a 1000 recursos. Se definido como maior que 1000, apenas 1000 serão retornados e um aviso será retornado no pacote. |
| _include | Sim | Sim | 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 | Sim | 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 | Sim | |
| _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 | No | |
| _containedType | Não | No | |
| _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 ignora 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.
Busca encadeada e 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
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 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 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 e 3 KB, usando header 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, 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.
Observação
FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.