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

Artigo
06/01/2023

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(s) recurso(s). No entanto, há cenários em que talvez você queira pesquisar em um elemento em um recurso que não é definido pela especificação FHIR como um parâmetro de pesquisa padrão. 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

Sempre que você criar, atualizar ou excluir um parâmetro de pesquisa, será necessário executar um trabalho reindexar para permitir que o parâmetro de pesquisa seja usado em produção. Abaixo, descreveremos como você pode testar parâmetros de pesquisa antes de reexenciar 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 abaixo 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 capability do servidor FHIR depois que você POSTAR o parâmetro de pesquisa para o banco de dados e reindexar seu banco de dados. Exibir o SearchParameter na instrução capability é a única maneira de informar se há suporte para um parâmetro de pesquisa no servidor FHIR. Se você encontrar o parâmetro de pesquisa pesquisando o parâmetro de pesquisa, mas não puder vê-lo na instrução capability, ainda precisará 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:

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 definidos, conforme mostrado acima no parâmetro de pesquisa de corrida do US Core.
code: o valor armazenado no código é o que você usará ao pesquisar. Para o exemplo acima, 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 os recursos aos quais o parâmetro de pesquisa se aplica.
base: descreve a quais recursos 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 Especial 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 expressão ou da sintaxe xpath e a API do Azure para FHIR ignora a sintaxe xpath.

Testar parâmetros de pesquisa

Embora você não possa usar os parâmetros de pesquisa em produção até executar um trabalho reindexar, há algumas maneiras de testar os parâmetros de pesquisa antes de reexenciar todo o banco de dados.

Primeiro, você pode testar seu novo parâmetro de pesquisa para ver quais valores serão retornados. Executando o comando abaixo em uma instância de recurso específica (inserindo sua ID), você receberá de volta uma lista de pares de valores com o nome do parâmetro de pesquisa e o valor armazenado para o paciente específico. Isso incluirá todos os parâmetros de pesquisa para o recurso e você poderá rolar 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 para um paciente:

GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

O resultado terá esta aparência:

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

Executando isso, define os índices de 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 retornará resultados em que qualquer um dos recursos tiver o parâmetro de pesquisa indexado, mesmo que nem todos os recursos desse tipo o tenham indexado.

Continuando com nosso exemplo acima, você pode indexar um paciente para habilitar a Corrida SearchParameterdo Núcleo dos EUA:

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 testar e ficar satisfeito que o parâmetro de pesquisa está funcionando conforme o esperado, execute ou agende seu trabalho reindexar 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 solicitação PUT e na PUT chamada.

Observação

Se você não souber a ID do parâmetro de pesquisa, poderá pesquisá-la. Usar GET {{FHIR_URL}}/SearchParameter retornará todos os parâmetros de pesquisa personalizados e você poderá percorrer o parâmetro de pesquisa para localizar o parâmetro de pesquisa necessário. Você também pode limitar a pesquisa por nome. Com o exemplo abaixo, 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 será atualizado e a versão será incrementada SearchParameter .

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 reindexar 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 reindexar imediatamente.

Próximas etapas

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

Como executar um trabalho de reindexação

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

Share via

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

Criar novo parâmetro de pesquisa

Testar parâmetros de pesquisa

Atualizar um parâmetro de pesquisa

Excluir um parâmetro de pesquisa

Próximas etapas

Recursos adicionais