Definir parâmetros de pesquisa personalizados para a API do Azure para FHIR
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(s) recurso(s). No entanto, existem cenários em que poderá querer procurar um elemento num recurso que não é definido pela especificação FHIR como um parâmetro de pesquisa padrão. Este artigo descreve como pode definir os seus próprios parâmetros de pesquisa a utilizar na API do Azure para FHIR.
Nota
Sempre que criar, atualizar ou eliminar um parâmetro de pesquisa, terá de executar uma tarefa de reindexação para permitir que o parâmetro de pesquisa seja utilizado na produção. Abaixo, iremos descrever como 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, utilize POST o SearchParameter recurso para a base de dados. O exemplo de código abaixo mostra como adicionar o SearchParameter race dos E.U.A . Core 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 será apresentado na instrução de capacidade do servidor FHIR depois de PUBLICAR o parâmetro de pesquisa na base de dados e voltar aexexar a base de dados. Ver na SearchParameter instrução de capacidade é a única forma de saber se um parâmetro de pesquisa é suportado no seu servidor FHIR. Se conseguir encontrar o parâmetro de pesquisa ao procurar o parâmetro de pesquisa, mas não o conseguir ver na instrução de capacidade, ainda terá de indexar o parâmetro de pesquisa. Pode PUBLICAR vários parâmetros de pesquisa antes de acionar uma operação de reindexação.
Elementos importantes de um SearchParameter:
URL: uma chave exclusiva para descrever o parâmetro de pesquisa. Muitas organizações, como o HL7, utilizam um formato de URL padrão para os parâmetros de pesquisa que definem, conforme mostrado acima no parâmetro de pesquisa race dos EUA Core.
código: o valor armazenado no código é o que irá utilizar ao procurar. Para o exemplo acima, procuraria com
GET {FHIR_URL}/Patient?race=<code>para obter todos os pacientes de uma raça específica. O código tem de ser exclusivo para os recursos a que o parâmetro de pesquisa se aplica.base: descreve a que recursos o parâmetro de pesquisa se aplica. Se o parâmetro de pesquisa se aplicar a todos os recursos, pode utilizar
Resource; caso contrário, 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. Isto significa que não pode definir um parâmetro de pesquisa do tipo Especial ou definir um parâmetro de pesquisa composto , a menos que seja uma combinação suportada.
expressão: descreve como calcular o valor da pesquisa. Ao descrever um parâmetro de pesquisa, tem de incluir a expressão, mesmo que não seja exigida pela especificação. Isto acontece porque 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 possa utilizar os parâmetros de pesquisa em produção até executar uma tarefa de reindexação, existem algumas formas de testar os parâmetros de pesquisa antes de reindexar toda a base de dados.
Primeiro, pode testar o novo parâmetro de pesquisa para ver que valores serão devolvidos. Ao executar o comando abaixo numa instância de recurso específica (ao introduzir o respetivo ID), obterá novamente uma lista de pares de valores com o nome do parâmetro de pesquisa e o valor armazenado para o paciente específico. Isto incluirá todos os parâmetros de pesquisa do recurso e pode percorrer até encontrar o parâmetro de pesquisa que criou. Executar este comando não alterará nenhum comportamento no seu servidor FHIR.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
Por exemplo, para localizar todos os parâmetros de pesquisa de um paciente:
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
O resultado terá o seguinte aspeto:
{
"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"
},
...
Assim que vir que o parâmetro de pesquisa está a ser apresentado conforme esperado, pode reindexar um único recurso para testar a pesquisa com o elemento . Primeiro, irá reindexar um único recurso:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
Ao executar este procedimento, define os índices para quaisquer parâmetros de pesquisa para o recurso específico que definiu para esse tipo de recurso. Isto faz uma atualização para o servidor FHIR. Agora, pode procurar e definir o cabeçalho utilizar índices parciais como verdadeiro, o que significa que devolverá resultados em que qualquer um dos recursos tem o parâmetro de pesquisa indexado, mesmo que nem todos os recursos desse tipo o tenham indexado.
Continuando com o nosso exemplo acima, pode indexar um paciente para ativar a Us Core Race SearchParameter:
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
E, 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 testar e estar satisfeito com o facto de o parâmetro de pesquisa estar a funcionar conforme esperado, execute ou agende a tarefa de reindexação para que os parâmetros de pesquisa possam ser utilizados no servidor FHIR para casos de utilização de produção.
Atualizar um parâmetro de pesquisa
Para atualizar um parâmetro de pesquisa, utilize PUT para criar uma nova versão do parâmetro de pesquisa. Tem de incluir o SearchParameter ID no id elemento do corpo do PUT pedido e na PUT chamada.
Nota
Se não souber o ID do parâmetro de pesquisa, pode procurá-lo. A utilização GET {{FHIR_URL}}/SearchParameter irá devolver todos os parâmetros de pesquisa personalizados e pode percorrer o parâmetro de pesquisa para encontrar o parâmetro de pesquisa de que precisa. Também pode limitar a pesquisa por nome. Com o exemplo abaixo, pode procurar o nome com 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 será atualizado SearchParameter e a versão será incrementada.
Aviso
Tenha cuidado ao atualizar os SearchParameters que já foram indexados na sua base de dados. Alterar o comportamento de um SearchParameter existente pode ter impactos no comportamento esperado. Recomendamos que execute uma tarefa de reindexação imediatamente.
Eliminar um parâmetro de pesquisa
Se precisar de eliminar um parâmetro de pesquisa, utilize o seguinte:
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Aviso
Tenha cuidado ao eliminar SearchParameters que já foram indexados na sua base de dados. Alterar o comportamento de um SearchParameter existente pode ter impactos no comportamento esperado. Recomendamos que execute uma tarefa de reindexação imediatamente.
Passos seguintes
Neste artigo, aprendeu a criar um parâmetro de pesquisa. Em seguida, pode aprender a reindexar o servidor FHIR.
FHIR® é uma marca registada do HL7 e é utilizada com a permissão de HL7.