Compartilhar via

Definindo parâmetros de pesquisa personalizados

  • Artigo

A especificação FHIR® define um conjunto de parâmetros de pesquisa que se aplicam a todos os recursos. Além disso, o FHIR define muitos parâmetros de pesquisa específicos para determinados recursos. No entanto, talvez você também 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 personalizados para uso no serviço FHIR nos Serviços de Dados de Integridade do Azure.

Observação

Cada vez que você criar, atualizar ou excluir um parâmetro de pesquisa, precisará executar um trabalho de reindexação para habilitar o parâmetro de pesquisa para produção ao vivo. Descreveremos como você pode testar os parâmetros de pesquisa antes de reindexar todo o banco de dados do serviço FHIR a seguir.

Criar novo parâmetro de pesquisa

Para criar um novo parâmetro de pesquisa, você precisa de POST um SearchParameter recurso para o banco de dados de serviço FHIR.

POST {{FHIR_URL}}/SearchParameter

Os exemplos a seguir demonstram a criação de um novo parâmetro de pesquisa personalizado.

Criar novo parâmetro de pesquisa por definição no Guia de implementação

O exemplo de código a seguir mostra como adicionar o parâmetro de pesquisa US Core Race ao Patient tipo de recurso no banco de dados de serviço FHIR.

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

Criar novo parâmetro de pesquisa para atributos de recurso com tipo de referência

O exemplo de código a seguir mostra como criar um parâmetro de pesquisa personalizado para pesquisar recursos MedicationDispense com base no local em que eles foram dispensados. Este é um exemplo de adição de um parâmetro de pesquisa personalizado para um tipo de referência.

{
 "resourceType": "SearchParameter",
  "id": "a3c28d46-fd06-49ca-aea7-5f9314ef0497",
  "url": "{{An absolute URI that is used to identify this search parameter}}",
  "version": "1.0",
  "name": "MedicationDispenseLocationSearchParameter",
  "status": "active",
  "description": "Search parameter for MedicationDispense by location",
  "code": "location",
  "base": ["MedicationDispense"],
  "target": ["Location"],
  "type": "reference",
  "expression": "MedicationDispense.location"
}

Observação

O novo parâmetro de pesquisa aparecerá na instrução de funcionalidade do serviço FHIR depois que você POST usar o parâmetro de pesquisa no banco de dados e reindexar seu banco de dados. Exibir a SearchParameter instrução in the capability é a única maneira de saber se há suporte para um parâmetro de pesquisa em seu serviço FHIR. Se você não conseguir encontrar o SearchParameter na instrução de capacidade, ainda será necessário reindexar seu banco de dados para ativar o parâmetro de pesquisa. Você pode POST pesquisar vários parâmetros antes de disparar uma operação de reindexação.

Elementos importantes de um SearchParameter recurso são:

  • url: Uma chave exclusiva para descrever o parâmetro de pesquisa. Organizações como a HL7 usam um formato de URL padrão para os parâmetros de pesquisa que definem, conforme mostrado acima no parâmetro de pesquisa US Core Race.

  • code: o valor armazenado no elemento code é o nome usado para o parâmetro de pesquisa quando ele é incluído em uma chamada à API. Para o exemplo anterior com a extensão "US Core Race", você pesquisaria com GET {{FHIR_URL}}/Patient?race=<code> where <code> is no valor definido do sistema de codificação especificado. Esta chamada recuperaria todos os pacientes de uma determinada raça.

  • base: descreve a quais tipos de recursos o parâmetro de pesquisa se aplica. Se o parâmetro search se aplicar a todos os recursos, você poderá usar Resource; caso contrário, você poderá listar todos os tipos de recursos relevantes.

  • target: descreve a quais tipos de recursos o parâmetro de pesquisa corresponde.

  • type: descreve o tipo de dados para o parâmetro de pesquisa. O tipo é limitado pelo suporte para tipos de dados no serviço 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.

  • expression: 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 o serviço FHIR ignora a sintaxe xpath.

Testar novos parâmetros de pesquisa

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

Primeiro, você pode testar um 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 (fornecendo a ID do recurso), você obtém uma lista de pares de valores com o nome do parâmetro de pesquisa e o valor armazenado no elemento correspondente. Essa lista inclui todos os parâmetros de pesquisa do recurso. Você pode rolar para encontrar o parâmetro de pesquisa criado. A execução desse comando não alterará nenhum comportamento no serviço FHIR.

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOURCE_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 será semelhante a este:

{
  "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 seu novo parâmetro de pesquisa. Para reindexar um único recurso, use o seguinte.

POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

A execução dessa POST chamada define os índices para todos os parâmetros de pesquisa definidos para a instância de recurso especificada na solicitação. Essa chamada faz uma alteração no banco de dados de serviço FHIR. Agora você pode pesquisar e definir o cabeçalho como true, o x-ms-use-partial-indices que faz com que o serviço FHIR retorne resultados para qualquer um dos recursos que tenham o parâmetro de pesquisa indexado, mesmo que nem todas as instâncias de recurso desse tipo o tenham indexado.

Continuando com nosso exemplo, você pode indexar um paciente para habilitar SearchParameter:

POST {{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

E então faça pesquisas de teste:

  1. Para o paciente por raça:
GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
  1. Para Localização (tipo de referência)
{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Depois de testar seu novo parâmetro de pesquisa e confirmar que ele está funcionando conforme o esperado, execute ou agende seu trabalho de reindexação para que os novos parâmetros de pesquisa possam ser usados na produção ao vivo.

Consulte Executando um trabalho de reindexação para obter informações sobre como reindexar seu banco de dados de serviço FHIR.

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 a ID do parâmetro de pesquisa no id campo no corpo da PUT solicitação e a PUT cadeia de caracteres da solicitação.

Observação

Se você não souber o ID do parâmetro de pesquisa, poderá pesquisá-lo usando GET {{FHIR_URL}}/SearchParameter. Isso retornará todos os parâmetros de pesquisa personalizados e padrão. Você pode rolar pela lista para encontrar o parâmetro de pesquisa de que precisa. Você também pode limitar a pesquisa por nome. Conforme mostrado na solicitação de exemplo a seguir, o nome da instância de recurso personalizado SearchParameter é USCoreRace. Você pode pesquisar esse SearchParameter recurso pelo nome usando 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 da solicitação acima será um recurso atualizado SearchParameter .

Aviso

Tenha cuidado ao atualizar os parâmetros de pesquisa. Alterar um parâmetro de pesquisa 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 parâmetros de pesquisa. A exclusão de um parâmetro de pesquisa existente pode ter impactos no comportamento esperado. Recomendamos executar um trabalho de reindexação imediatamente.

Próximas etapas

Neste artigo, você aprendeu a criar um parâmetro de pesquisa personalizado. Em seguida, você pode aprender como reindexar seu banco de dados de serviço FHIR. Para obter mais informações, confira

Como executar um trabalho de reindexação

Observação

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