Definindo parâmetros de pesquisa personalizados para a 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 um conjunto de parâmetros de pesquisa para todos os recursos e parâmetros de pesquisa específicos de um recurso. No entanto, há cenários em que talvez você queira pesquisar em um elemento em um recurso que não está definido como um parâmetro de pesquisa padrão pela especificação FHIR. Este artigo descreve como você pode definir seus próprios parâmetros de pesquisa a serem usados na API do Azure para FHIR.
Observação
Cada vez que você criar, atualizar ou excluir um parâmetro de pesquisa, precisará executar um trabalho de reindexação para permitir que o parâmetro de pesquisa seja usado na produção. Este artigo descreverá como você pode testar os parâmetros de pesquisa antes de reindexar todo o servidor FHIR.
Criar novo parâmetro de pesquisa
Para criar um novo parâmetro de pesquisa, você POST usa o SearchParameter recurso para o banco de dados. O exemplo de código a seguir mostra como adicionar o US Core Race SearchParameter ao Patient recurso.
POST {{FHIR_URL}}/SearchParameter
{
"resourceType" : "SearchParameter",
"id" : "us-core-race",
"url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
"version" : "3.1.1",
"name" : "USCoreRace",
"status" : "active",
"date" : "2019-05-21",
"publisher" : "US Realm Steering Committee",
"contact" : [
{
"telecom" : [
{
"system" : "other",
"value" : "http://www.healthit.gov/"
}
]
}
],
"description" : "Returns patients with a race extension matching the specified code.",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "US",
"display" : "United States of America"
}
]
}
],
"code" : "race",
"base" : [
"Patient"
],
"type" : "token",
"expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}
Observação
O novo parâmetro de pesquisa aparecerá na instrução de funcionalidade do servidor FHIR depois que você POSTAR o parâmetro de pesquisa no banco de dados e reindexar seu banco de dados. Visualizar a SearchParameter instrução na capability é a única maneira de saber se há suporte para um parâmetro de pesquisa no servidor FHIR. Se você puder encontrar o parâmetro de pesquisa, mas não puder vê-lo na instrução de capacidade, ainda será necessário indexar o parâmetro de pesquisa. Você pode POSTAR vários parâmetros de pesquisa antes de disparar uma operação de reindexação.
Elementos importantes de um SearchParameter incluem o seguinte.
url: Uma chave exclusiva para descrever o parâmetro de pesquisa. Muitas organizações, como a HL7, usam um formato de URL padrão para os parâmetros de pesquisa que definem, conforme mostrado anteriormente no parâmetro de pesquisa de corrida US Core.
code: o valor armazenado no código é o que você usa ao pesquisar. Para o exemplo anterior, você pesquisaria com
GET {FHIR_URL}/Patient?race=<code>para obter todos os pacientes de uma raça específica. O código deve ser exclusivo para o recurso ao qual o parâmetro de pesquisa se aplica.base: descreve a qual recurso o parâmetro de pesquisa se aplica. Se o parâmetro de pesquisa se aplicar a todos os recursos, você poderá usar
Resource; caso contrário, você poderá listar todos os recursos relevantes.type: descreve o tipo de dados para o parâmetro de pesquisa. O tipo é limitado pelo suporte para a API do Azure para FHIR. Isso significa que você não pode definir um parâmetro de pesquisa do tipo Special ou definir um parâmetro de pesquisa composto, a menos que seja uma combinação com suporte.
expressão: descreve como calcular o valor da pesquisa. Ao descrever um parâmetro de pesquisa, você deve incluir a expressão, mesmo que ela não seja exigida pela especificação. Isso ocorre porque você precisa da sintaxe expression ou xpath, e a API do Azure para FHIR ignora a sintaxe xpath.
Parâmetros de pesquisa de teste
Embora você não possa usar os parâmetros de pesquisa na produção até executar um trabalho de reindexação, você pode testar seus parâmetros de pesquisa antes de reindexar todo o banco de dados.
Primeiro, você pode testar seu novo parâmetro de pesquisa para ver quais valores são retornados. Ao executar o comando a seguir em uma instância de recurso específica (inserindo sua ID), você obtém uma lista de pares de valores com o nome do parâmetro de pesquisa e o valor armazenado para o paciente específico. Isso inclui todos os parâmetros de pesquisa do recurso. Você pode rolar pela lista retornada para encontrar o parâmetro de pesquisa criado. A execução desse comando não alterará nenhum comportamento no servidor FHIR.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
Por exemplo, para localizar todos os parâmetros de pesquisa de um paciente, use o seguinte.
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
O resultado é semelhante ao seguinte.
{
"resourceType": "Parameters",
"id": "8be24e78-b333-49da-a861-523491c3437a",
"meta": {
"versionId": "1"
},
"parameter": [
{
"name": "deceased",
"valueString": "http://hl7.org/fhir/special-values|false"
},
{
"name": "language",
"valueString": "urn:ietf:bcp:47|en-US"
},
{
"name": "race",
"valueString": "2028-9"
},
...
Depois de ver que o parâmetro de pesquisa está sendo exibido conforme o esperado, você pode reindexar um único recurso para testar a pesquisa com o elemento. Primeiro, você reindexa um único recurso:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
Executar isso define os índices para todos os parâmetros de pesquisa para o recurso específico que você definiu para esse tipo de recurso. Isso faz uma atualização para o servidor FHIR. Agora você pode pesquisar e definir o cabeçalho usar índices parciais como true, o que significa que ele retorna resultados em que qualquer um dos recursos que têm o parâmetro de pesquisa indexado, mesmo que nem todos os recursos desse tipo o tenham indexado.
Continuando com nosso exemplo, você pode indexar um paciente para habilitar a US Core Race SearchParameter da seguinte maneira.
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
Em seguida, pesquise pacientes que tenham uma raça específica:
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Quando estiver satisfeito com o fato de que o parâmetro de pesquisa está funcionando conforme o esperado, execute ou agende o trabalho de reindexação para que os parâmetros de pesquisa possam ser usados no servidor FHIR para casos de uso de produção.
Atualizar um parâmetro de pesquisa
Para atualizar um parâmetro de pesquisa, use PUT para criar uma nova versão do parâmetro de pesquisa. Você deve incluir o SearchParameter ID no id elemento do corpo da PUT solicitação e na PUT chamada.
Observação
Se você não souber o ID do parâmetro de pesquisa, poderá pesquisá-lo. O uso GET {{FHIR_URL}}/SearchParameter retornará todos os parâmetros de pesquisa personalizados e você poderá rolar pela lista para encontrar o parâmetro de pesquisa necessário. Você também pode limitar a pesquisa por nome. Com o exemplo a seguir, você pode pesquisar o nome usando USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRace.
PUT {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
{
"resourceType" : "SearchParameter",
"id" : "SearchParameter ID",
"url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
"version" : "3.1.1",
"name" : "USCoreRace",
"status" : "active",
"date" : "2019-05-21",
"publisher" : "US Realm Steering Committee",
"contact" : [
{
"telecom" : [
{
"system" : "other",
"value" : "http://www.healthit.gov/"
}
]
}
],
"description" : "New Description!",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "US",
"display" : "United States of America"
}
]
}
],
"code" : "race",
"base" : [
"Patient"
],
"type" : "token",
"expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}
O resultado é uma atualização SearchParameter e a versão é incrementada.
Aviso
Tenha cuidado ao atualizar SearchParameters que já foram indexados em seu banco de dados. Alterar o comportamento de um SearchParameter existente pode ter impactos no comportamento esperado. Recomendamos executar um trabalho de reindexação imediatamente.
Excluir um parâmetro de pesquisa
Se você precisar excluir um parâmetro de pesquisa, use o seguinte.
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Aviso
Tenha cuidado ao excluir SearchParameters que já foram indexados em seu banco de dados. Alterar o comportamento de um SearchParameter existente pode ter impactos no comportamento esperado. Recomendamos executar um trabalho de reindexação imediatamente.
Próximas etapas
Neste artigo, você aprendeu como criar um parâmetro de pesquisa. Em seguida, você pode aprender como reindexar seu servidor FHIR.
Observação
FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.