Définition des paramètres de recherche personnalisés

  • Article

La spécification FHIR définit un ensemble de paramètres de recherche qui s’appliquent à toutes les ressources. En outre, FHIR définit de nombreux paramètres de recherche spécifiques à certaines ressources. Toutefois, il existe des scénarios dans lesquels vous pouvez effectuer une recherche sur un élément d’une ressource qui n’est pas défini par la spécification FHIR en tant que paramètre de recherche standard. Cet article explique comment définir vos propres paramètres de recherche personnalisés à utiliser dans le service FHIR dans Azure Health Data Services.

Remarque

Chaque fois que vous créez, mettez à jour ou supprimez un paramètre de recherche, vous devez exécuter un travail de réindexation pour activer le paramètre de recherche pour la production en direct. Ci-dessous, nous allons décrire comment tester les paramètres de recherche avant de réindexer l’ensemble de la base de données du service FHIR.

Créer un paramètre de recherche

Pour créer un paramètre de recherche, vous devez utiliser POST une SearchParameter ressource dans la base de données du service FHIR.

POST {{FHIR_URL}}/SearchParameter

Les exemples ci-dessous illustrent la création d’un nouveau paramètre de recherche personnalisé

Créer un paramètre de recherche par définition dans le Guide d’implémentation

L’exemple de code ci-dessous montre comment ajouter le paramètre de recherche US Core Race au Patient type de ressource dans votre base de données de service 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"
}

Créer un paramètre de recherche pour les attributs de ressource avec le type de référence

L’exemple de code montre comment créer un paramètre de recherche personnalisé pour rechercher des ressources MedicationDispense en fonction de l’emplacement où elles ont été distribuées. Il s’agit d’un exemple d’ajout d’un paramètre de recherche personnalisé pour un type Reference.

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

Remarque

Le nouveau paramètre de recherche apparaît dans l’instruction de capacité du service FHIR après POST avoir défini le paramètre de recherche dans la base de données et réindexé votre base de données. L’affichage de dans SearchParameter l’instruction de capacité est la seule façon de savoir si un paramètre de recherche est pris en charge dans votre service FHIR. Si vous ne trouvez pas le SearchParameter dans l’instruction de capacité, vous devez toujours réindexer votre base de données pour activer le paramètre de recherche. Vous pouvez utiliser POST plusieurs paramètres de recherche avant de déclencher une opération de réindexation.

Éléments importants d’une SearchParameter ressource :

  • url: clé unique pour décrire le paramètre de recherche. Les organisations telles que HL7 utilisent un format d’URL standard pour les paramètres de recherche qu’elles définissent, comme indiqué ci-dessus dans le paramètre de recherche US Core Race.

  • code: la valeur stockée dans l’élément de code est le nom utilisé pour le paramètre de recherche lorsqu’il est inclus dans un appel d’API. Pour l’exemple ci-dessus avec l’extension « US Core Race », vous devez rechercher où GET {{FHIR_URL}}/Patient?race=<code><code> se trouve la valeur définie à partir du système de codage spécifié. Cet appel récupérerait tous les patients d’une certaine race.

  • base: décrit le ou les types de ressources auxquels le paramètre de recherche s’applique. Si le paramètre de recherche s’applique à toutes les ressources, vous pouvez utiliser Resource; sinon, vous pouvez répertorier tous les types de ressources appropriés.

  • target: décrit le ou les types de ressources auxquels le paramètre de recherche correspond.

  • type: décrit le type de données du paramètre de recherche. Le type est limité par la prise en charge des types de données dans le service FHIR. Cela signifie que vous ne pouvez pas définir un paramètre de recherche de type Special ou définir un paramètre de recherche composite , sauf s’il s’agit d’une combinaison prise en charge.

  • expression: décrit comment calculer la valeur de la recherche. Lorsque vous décrivez un paramètre de recherche, vous devez inclure l’expression, même si elle n’est pas requise par la spécification. Cela est dû au fait que vous avez besoin de l’expression ou de la syntaxe xpath et que le service FHIR ignore la syntaxe xpath.

Tester de nouveaux paramètres de recherche

Bien que vous ne puissiez pas utiliser les nouveaux paramètres de recherche en production tant que vous n’avez pas exécuté un travail de réindexation, il existe plusieurs façons de tester vos paramètres de recherche personnalisés avant de réindexer l’ensemble de la base de données.

Tout d’abord, vous pouvez tester un nouveau paramètre de recherche pour voir quelles valeurs seront retournées. En exécutant la commande ci-dessous sur une ressource spécifique instance (en fournissant l’ID de ressource), vous obtenez une liste de paires de valeurs avec le nom du paramètre de recherche et la valeur stockée dans l’élément correspondant. Cette liste inclut tous les paramètres de recherche de la ressource. Vous pouvez faire défiler pour trouver le paramètre de recherche que vous avez créé. L’exécution de cette commande ne modifie aucun comportement dans votre service FHIR.

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

Par exemple, pour rechercher tous les paramètres de recherche d’un patient :

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

Le résultat ressemble à ceci :

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

Une fois que vous voyez que votre paramètre de recherche s’affiche comme prévu, vous pouvez réindexer une ressource unique pour tester la recherche avec votre nouveau paramètre de recherche. Pour réindexer une ressource unique :

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

L’exécution de cet POST appel définit les index pour tous les paramètres de recherche définis pour la ressource instance spécifiée dans la requête. Cet appel apporte une modification à la base de données du service FHIR. Vous pouvez désormais rechercher et définir l’en-tête x-ms-use-partial-indices sur true, ce qui entraîne le service FHIR à retourner des résultats pour toutes les ressources dont le paramètre de recherche est indexé, même si toutes les instances de ressources de ce type ne l’ont pas indexé.

Dans notre exemple, vous pouvez indexer un patient pour activer SearchParameter:

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

Puis effectuez une recherche de test

  1. Pour le patient par race :
GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
  1. Pour Location (type de référence) :
{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Une fois que vous avez testé votre nouveau paramètre de recherche et confirmé qu’il fonctionne comme prévu, exécutez ou planifiez votre travail de réindexation afin que les nouveaux paramètres de recherche puissent être utilisés en production en direct.

Pour plus d’informations sur la réindexation de votre base de données de service FHIR, consultez Exécution d’un travail de réindexation .

Mettre à jour un paramètre de recherche

Pour mettre à jour un paramètre de recherche, utilisez PUT pour créer une nouvelle version du paramètre de recherche. Vous devez inclure l’ID de paramètre de recherche dans le id champ dans le corps de la PUT demande, ainsi que dans la chaîne de la PUT demande.

Remarque

Si vous ne connaissez pas l’ID de votre paramètre de recherche, vous pouvez le rechercher à l’aide GET {{FHIR_URL}}/SearchParameterde . Cela retourne tous les paramètres de recherche personnalisés et standard, et vous pouvez faire défiler la liste pour trouver le paramètre de recherche dont vous avez besoin. Vous pouvez également limiter la recherche par nom. Comme indiqué dans l’exemple de demande ci-dessous, le nom de la ressource personnalisée SearchParameter instance est USCoreRace. Vous pouvez rechercher cette SearchParameter ressource par nom à l’aide de 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"
}

Le résultat de la demande ci-dessus sera une ressource mise à jour SearchParameter .

Avertissement

Soyez prudent lors de la mise à jour des paramètres de recherche. La modification d’un paramètre de recherche existant peut avoir un impact sur le comportement attendu. Nous vous recommandons d’exécuter immédiatement un travail de réindexation.

Supprimer un paramètre de recherche

Si vous devez supprimer un paramètre de recherche, utilisez les éléments suivants :

DELETE {{FHIR_URL}}/SearchParameter/{{SearchParameter_ID}}

Avertissement

Soyez prudent lors de la suppression des paramètres de recherche. La suppression d’un paramètre de recherche existant peut avoir un impact sur le comportement attendu. Nous vous recommandons d’exécuter immédiatement un travail de réindexation.

Étapes suivantes

Dans cet article, vous avez appris à créer un paramètre de recherche personnalisé. Vous découvrirez ensuite comment réindexer votre base de données de service FHIR. Pour plus d'informations, consultez la rubrique

Guide pratique pour exécuter un travail de réindexation

FHIR® est une marque déposée de HL7 utilisé avec l’autorisation de HL7.