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 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 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 você pode querer pesquisar em relação a um elemento em um recurso que não é 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.
Nota
Sempre que criar, atualizar ou excluir um parâmetro de pesquisa, você 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 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"
}
Nota
O novo parâmetro de pesquisa aparecerá na instrução de capacidade do servidor FHIR depois de POSTAR o parâmetro de pesquisa para o banco de dados e reindexar seu banco de dados. A visualização da SearchParameter instrução in the capability é a única maneira de saber se um parâmetro de pesquisa é suportado no seu servidor FHIR. Se você puder encontrar o parâmetro de pesquisa, mas não puder vê-lo na instrução de capacidade, ainda precisará indexar o parâmetro de pesquisa. Você pode POSTAR vários parâmetros de pesquisa antes de acionar uma operação de reindexação.
Os 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, como 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ê pode usar
Resource, caso contrário, você pode 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 suportada.
expression: Descreve como calcular o valor para a 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 expressão ou da sintaxe xpath, e a API do Azure para FHIR ignora a sintaxe xpath.
Testar parâmetros de pesquisa
Embora não seja possível usar os parâmetros de pesquisa na produção até executar um trabalho de reindexação, você pode testar os 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 para o recurso. Você pode percorrer a lista retornada para encontrar o parâmetro de pesquisa que você criou. A execução deste comando não alterará nenhum comportamento no seu servidor FHIR.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
Por exemplo, para encontrar 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 seu 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
A execução define os índices para quaisquer 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 de índices parciais de uso como true, o que significa que ele retorna resultados onde 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, procure pacientes que tenham uma raça específica:
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Depois de ter certeza de que seu parâmetro de pesquisa está funcionando conforme o esperado, execute ou agende seu 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.
Nota
Se não souber o ID do parâmetro de pesquisa, pode procurá-lo. Usando GET {{FHIR_URL}}/SearchParameter retornará todos os parâmetros de pesquisa personalizados, e você pode percorrer a lista para encontrar o parâmetro de pesquisa que você precisa. Também pode limitar a pesquisa por nome. Com o exemplo a seguir, você pode pesquisar por nome usando USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRaceo .
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 é atualizado 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óximos passos
Neste artigo, você aprendeu como criar um parâmetro de pesquisa. Em seguida, você pode aprender como reindexar seu servidor FHIR.
Nota
FHIR® é uma marca registada da HL7 e é utilizada com a permissão da HL7.