Partilhar via

Definição de 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, FHIR define muitos parâmetros de pesquisa que são específicos para determinados recursos. No entanto, você também pode querer pesquisar em relação a 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 Saúde do Azure.

Nota

Sempre que criar, atualizar ou excluir um parâmetro de pesquisa, você 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 em seu 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 onde 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"
}

Nota

O novo parâmetro de pesquisa aparecerá na instrução de capacidade do serviço FHIR depois que você POST 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 em seu serviço FHIR. Se você não conseguir encontrar o SearchParameter na instrução de capacidade, ainda precisará reindexar seu banco de dados para ativar o parâmetro de pesquisa. Você pode POST usar vários parâmetros de pesquisa antes de acionar uma operação de reindexação.

Os 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, como 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 de API. Para o exemplo anterior com a extensão "US Core Race", você pesquisaria com GET {{FHIR_URL}}/Patient?race=<code> onde <code> está no conjunto de valores 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 de pesquisa se aplicar a todos os recursos, você pode usar Resource, caso contrário, você pode 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 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 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 na 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 de volta uma lista de pares de valores com o nome do parâmetro de pesquisa e o valor armazenado no elemento correspondente. Esta lista inclui todos os parâmetros de pesquisa para o recurso. Você pode rolar para encontrar o parâmetro de pesquisa que você criou. A execução deste comando não alterará nenhum comportamento no seu serviço FHIR.

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

Por exemplo, para encontrar todos os parâmetros de pesquisa de um paciente:

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

O resultado tem 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"
    }
    ]
    ...}

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 quaisquer parâmetros de pesquisa definidos para a instância de recurso especificada na solicitação. Esta chamada faz uma alteração no banco de dados de serviço FHIR. Agora você pode pesquisar e definir o x-ms-use-partial-indices cabeçalho como true, o que faz com que o serviço FHIR retorne resultados para qualquer um dos recursos que têm o parâmetro de pesquisa indexado, mesmo que nem todas as instâncias de recursos desse tipo o tenham indexado.

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

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

E então faça pesquisas de teste:

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

Nota

Se não souber o ID do parâmetro de pesquisa, pode procurá-lo utilizando GET {{FHIR_URL}}/SearchParameter. Isso retornará todos os parâmetros de pesquisa personalizados e padrão. Pode percorrer a lista para encontrar o parâmetro de pesquisa de que necessita. 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 personalizada SearchParameter é USCoreRace. Você pode pesquisar este 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óximos passos

Neste artigo, você aprendeu como 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, consulte,

Como executar um trabalho de reindexação

Nota

FHIR® é uma marca registada da HL7 e é utilizada com a permissão da HL7.