Definindo parâmetros de pesquisa personalizados para a API do Azure para FHIR

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.

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"
}

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.

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.

Excluir um parâmetro de pesquisa

Se você precisar excluir um parâmetro de pesquisa, use o seguinte.

Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}

Próximas etapas

Neste artigo, você aprendeu como criar um parâmetro de pesquisa. Em seguida, você pode aprender como reindexar seu servidor FHIR.