Compartilhar via

Exemplos de pesquisa do FHIR da API do Azure para FHIR

  • Artigo

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.

Veja a seguir exemplos de uso de operações de pesquisa FHIR® (Fast Healthcare Interoperability Resources), incluindo parâmetros e modificadores de pesquisa, pesquisa em cadeia e cadeia reversa, pesquisa composta, exibição do próximo conjunto de entradas para resultados de pesquisa e pesquisa com uma POST solicitação. Para saber mais sobre pesquisa, confira Visão geral da Pesquisa do FHIR.

Parâmetros de resultado de pesquisa

_include

_include pesquisa entre recursos os que incluem o parâmetro especificado do recurso. Por exemplo, você pode pesquisar entre recursos MedicationRequest para encontrar somente os que incluem informações sobre as receitas para determinado paciente, que é o parâmetro reference patient. O exemplo a seguir extrai todos os MedicationRequests e todos os pacientes referenciados do MedicationRequests.

 GET [your-fhir-server]/MedicationRequest?_include=MedicationRequest:patient

Observação

_include e _revinclude estão limitados a 100 itens.

_revinclude

_revinclude permite que você pesquise na direção oposta de _include. Por exemplo, você pode procurar pacientes e, em seguida, reverter a inclusão de todos os encontros que fazem referência aos pacientes:

GET [your-fhir-server]/Patient?_revinclude=Encounter:subject

_elements

_elements restringe o resultado da pesquisa a um subconjunto de campos para reduzir o tamanho da resposta com a omissão de dados desnecessários. O parâmetro aceita uma lista separada por vírgulas de elementos base.

GET [your-fhir-server]/Patient?_elements=identifier,active

A partir dessa solicitação, você obtém um pacote de pacientes em que cada recurso inclui apenas os identificadores e o status ativo do paciente. Os recursos nessa resposta contêm um meta.tag valor de SUBSETTED para indicar que são um conjunto incompleto de resultados.

Modificadores de pesquisa

:not

:not permite que você encontre recursos em que um atributo não é verdadeiro. Por exemplo, você pode pesquisar pacientes em que o sexo não é feminino.

GET [your-fhir-server]/Patient?gender:not=female

Como valor retornado, você obteria todas as entradas de pacientes em que o gênero não é feminino, incluindo valores vazios (entradas especificadas sem gênero). Isso é diferente de procurar pacientes em que o sexo é masculino, já que isso não incluiria as entradas sem um gênero específico.

:missing

:missing retorna todos os recursos que não têm um valor para o elemento especificado quando o valor é true e retorna todos os recursos que contêm o elemento especificado quando o valor é false. Para elementos de tipo de dados simples, corresponde a todos os recursos em que o elemento está presente com extensões, :missing=true mas tem um valor vazio. O exemplo a seguir mostra como localizar todos os Patient recursos que não têm informações na data de nascimento.

GET [your-fhir-server]/Patient?birthdate:missing=true

:exact

:exact é usado para parâmetros string e retorna resultados que correspondem ao parâmetro de forma precisa, por exemplo, maiúsculas e concatenação de caracteres.

GET [your-fhir-server]/Patient?name:exact=Jon

Essa solicitação retorna recursos Patient que têm o nome exatamente igual a Jon. Se o recurso tivesse Pacientes com nomes como Jonathan ou joN, a pesquisa ignoraria o recurso, pois ele não corresponde exatamente ao valor especificado.

:contains

:contains é usado em parâmetros string e pesquisa recursos com correspondências parciais do valor especificado em qualquer lugar na cadeia de caracteres no campo pesquisado. contains não diferencia maiúsculas de minúsculas e permite a concatenação de caracteres. Por exemplo:

GET [your-fhir-server]/Patient?address:contains=Meadow

Essa solicitação retornaria todos os Patient recursos com address campos que têm valores que contêm a cadeia de caracteres "Meadow". Isso significa que você pode ter endereços que incluem valores como "Floresta" ou "Rua das Flores, 123" retornados como resultados da pesquisa.

Para fazer uma série de operações de pesquisa que abordam vários parâmetros de referência, você poderá “encadear” uma série de parâmetros de referência acrescentando-os à solicitação do servidor um de cada vez com um . de ponto. Por exemplo, se quiser exibir todos os recursos DiagnosticReport com uma referência subject a um recurso Patient que inclui determinado name:

 GET [your-fhir-server]/DiagnosticReport?subject:Patient.name=Sarah

Essa solicitação retornaria todos os recursos DiagnosticReport com uma paciente chamada “Sara”. O . de ponto após o campo Patient faz a pesquisa encadeada no parâmetro de referência do parâmetro subject.

Outro uso comum de uma pesquisa regular (não uma pesquisa encadeada) é encontrar todos os encontros de um paciente específico. Patients geralmente têm um ou mais Encounters com um assunto. A seguir, pesquisamos todos os Encounter recursos para um Patient com o .id

GET [your-fhir-server]/Encounter?subject=Patient/78a14cbe-8968-49fd-a231-d43e6619399f

Usando a pesquisa encadeada, você pode encontrar todos os Encounter recursos que correspondem a uma determinada Patient informação, como o birthdate.

GET [your-fhir-server]/Encounter?subject:Patient.birthdate=1987-02-20

Isso permitiria pesquisar Encounter recursos em todos os pacientes que têm o valor de data de nascimento especificado.

Além disso, a pesquisa encadeada pode ser feita mais de uma vez em uma solicitação com o símbolo &, que permite que você pesquise várias condições em uma solicitação. Nesses casos, a pesquisa encadeada pesquisa cada parâmetro "independentemente", em vez de procurar condições que atendam apenas a todas as condições ao mesmo tempo:

GET [your-fhir-server]/Patient?general-practitioner:Practitioner.name=Sarah&general-practitioner:Practitioner.address-state=WA

Isso retornaria todos os recursos Patient que tenham “Sara” como generalPractitioner e tenham um generalPractitioner com endereço no estado de SP. Em outras palavras, se um paciente teve Sarah do estado de NY e Bill do estado WA, ambos referenciados como do paciente, ambos são devolvidos generalPractitioner.

Para cenários em que a pesquisa precisa ser uma AND operação que abrange todas as condições como um grupo, consulte o exemplo em Pesquisa composta.

A pesquisa em cadeia permite que você pesquise recursos com base nas propriedades dos recursos aos quais eles se referem. Usar a pesquisa de cadeia reversa permite que você faça o contrário. Você pode pesquisar recursos com base nas propriedades dos recursos que fazem referência a eles, usando o parâmetro _has. Por exemplo, um Observation recurso tem um parâmetro patient de pesquisa que se refere a um recurso Paciente. Use o seguinte para localizar todos os recursos do Paciente referenciados por Observation com um .code

GET [base]/Patient?_has:Observation:patient:code=527

Essa solicitação retorna recursos do paciente referenciados com Observation o código 527.

Além disso, a pesquisa em cadeia reversa pode ter uma estrutura recursiva. Por exemplo, o seguinte pesquisa todos os pacientes que têm Observation onde a observação tem um evento de auditoria de um usuário janedoeespecífico.

GET [base]/Patient?_has:Observation:patient:_has:AuditEvent:entity:agent:Practitioner.name=janedoe

Observação

Na API do Azure para FHIR e no FHIR Server de código aberto apoiado pelo Azure Cosmos DB, a pesquisa encadeada e a pesquisa encadeada reversa são uma implementação de MVP. Para realizar uma pesquisa encadeada no Azure Cosmos DB, a implementação percorre a expressão de pesquisa e emite subconsultas para resolver os recursos correspondentes. Isso é feito em cada nível da expressão. Se alguma consulta retornar mais de 100 resultados, um erro será gerado.

Para pesquisar recursos que atendam a várias condições ao mesmo tempo, use uma pesquisa composta que une uma sequência de valores de parâmetro único com um símbolo $. O resultado seria a interseção dos recursos que correspondem a todas as condições especificadas pelos parâmetros de pesquisa unidos. Esses parâmetros de pesquisa são chamados de parâmetros de pesquisa composta e definem um novo parâmetro que combina os vários parâmetros em uma estrutura aninhada. Por exemplo, a pesquisa a seguir localiza todos os DiagnosticReport recursos que contêm Observation com um valor de potássio menor ou igual a 9,2.

GET [your-fhir-server]/DiagnosticReport?result.code-value-quantity=2823-3$lt9.2

Essa solicitação especifica o componente que contém um código de 2823-3, que, nesse caso, seria potássio. A seguir ao símbolo $, ele especifica o intervalo dos valores de componente usando lt para “menor ou igual a” e 9.2 para o intervalo de valores de potássio.

Pesquisar o próximo conjunto de entradas

O número máximo de entradas que podem ser retornadas por uma única consulta de pesquisa é 1000. Se houver mais de 1.000 entradas que correspondam à consulta de pesquisa, você poderá usar o procedimento a seguir para ver entradas maiores que 1000.
Use o valor do token url de continuação em searchset, como no resultado a seguir Bundle .

    "resourceType": "Bundle",
    "id": "98731cb7-3a39-46f3-8a72-afe945741bd9",
    "meta": {
        "lastUpdated": "2021-04-22T09:58:16.7823171+00:00"
    },
    "type": "searchset",
    "link": [
        {
            "relation": "next",
            "url": "[your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd"
        },
        {
            "relation": "self",
            "url": "[your-fhir-server]/Patient?_sort=_lastUpdated"
        }
    ],

Em seguida, faça uma solicitação GET para o URL fornecido no campo relation: next.

GET [your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd

Isso retorna o próximo conjunto de entradas para o resultado da pesquisa. O searchset é o conjunto completo de entradas de resultados de pesquisa e o token url de continuação é o link fornecido pelo servidor para você recuperar entradas que não aparecem nas primeiras 1000.

Pesquisar usando POST

Todos os exemplos de pesquisa mencionados anteriormente usaram GET solicitações. Você também pode fazer operações de pesquisa usando POST solicitações usando _search.

POST [your-fhir-server]/Patient/_search?_id=45

Essa solicitação retorna Patient recursos com o id valor de 45. Assim como acontece com as solicitações GET, o servidor determina qual conjunto de recursos atende à condição e retorna um recurso de pacote na resposta HTTP.

Outro exemplo de pesquisa usando POST em que os parâmetros de consulta são enviados como um corpo de formulário é o seguinte.

POST [your-fhir-server]/Patient/_search
content-type: application/x-www-form-urlencoded

name=John

Próximas etapas

Neste artigo, você aprendeu a pesquisar usando diferentes parâmetros de pesquisa, modificadores e ferramentas de pesquisa do FHIR. Para saber mais sobre Pesquisa do FHIR, confira

Visão geral da Pesquisa do FHIR

Observação

FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.