Définition de paramètres de recherche personnalisés pour l’API Azure pour FHIR
Important
L’API Azure pour FHIR sera mise hors service le 30 septembre 2026. Suivez les stratégies de migration pour passer au service FHIR® de Services de données de santé Azure d’ici à cette date. En raison de la mise hors service de l’API Azure pour FHIR, les nouveaux déploiements ne seront plus autorisés à compter du 1er avril 2025. Le service FHIR des Services de données de santé Azure est la version évoluée de l’API Azure pour FHIR qui permet aux clients de gérer les services FHIR, DICOM et MedTech avec des intégrations dans d’autres services Azure.
La spécification FHIR® (Fast Healthcare Interoperability Resources) définit un ensemble de paramètres de recherche pour toutes les ressources et paramètres de recherche spécifiques à une ressource. Toutefois, il existe des scénarios où vous souhaiterez peut-être effectuer une recherche sur un élément d’une ressource qui n’est pas définie comme paramètre de recherche standard par la spécification FHIR. Cet article explique comment définir vos propres paramètres de recherche à utiliser dans l’API Azure pour FHIR.
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 permettre au paramètre de recherche d’être utilisé en production. Cet article décrit comment tester les paramètres de recherche avant de réindexer l’ensemble du serveur FHIR.
Créer un paramètre de recherche
Pour créer un paramètre de recherche, vous POST êtes la SearchParameter ressource dans la base de données. L’exemple de code suivant montre comment ajouter us Core Race SearchParameter à la Patient ressource.
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"
}
Remarque
Le nouveau paramètre de recherche s’affiche dans l’instruction de fonctionnalité du serveur FHIR après avoir posté le paramètre de recherche sur la base de données et réindexé votre base de données. L’affichage de l’instruction SearchParameter de fonctionnalité est la seule façon de savoir si un paramètre de recherche est pris en charge dans votre serveur FHIR. Si vous pouvez trouver le paramètre de recherche, mais que vous ne pouvez pas le voir dans l’instruction de fonctionnalité, vous devez toujours indexer le paramètre de recherche. Vous pouvez PUBLIER plusieurs paramètres de recherche avant de déclencher une opération de réindexation.
Les éléments importants d’un SearchParameter élément incluent les éléments suivants.
URL : clé unique pour décrire le paramètre de recherche. De nombreuses organisations, telles que HL7, utilisent un format d’URL standard pour les paramètres de recherche qu’ils définissent, comme indiqué précédemment dans le paramètre de recherche de race US Core.
code : la valeur stockée dans le code est celle que vous utilisez lors de la recherche. Pour l’exemple précédent, vous recherchez avec
GET {FHIR_URL}/Patient?race=<code>pour obtenir tous les patients d’une race spécifique. Le code doit être unique pour la ressource à laquelle le paramètre de recherche s’applique.base : décrit la ressource à laquelle 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 toutes les ressources pertinentes.type : décrit le type de données du paramètre de recherche. Le type est limité par la prise en charge de l’API Azure pour 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 l’API Azure pour FHIR ignore la syntaxe xpath.
Paramètres de recherche de test
Bien que vous ne puissiez pas utiliser les paramètres de recherche en production tant que vous n’avez pas exécuté un travail de réindexation, vous pouvez tester vos paramètres de recherche avant de réindexer l’intégralité de la base de données.
Tout d’abord, vous pouvez tester votre nouveau paramètre de recherche pour voir quelles valeurs sont retournées. En exécutant la commande suivante sur une instance de ressource spécifique (en plaçant son ID), vous obtenez une liste de paires valeur avec le nom du paramètre de recherche et la valeur stockée pour le patient spécifique. Cela inclut tous les paramètres de recherche de la ressource. Vous pouvez faire défiler la liste retournée pour rechercher le paramètre de recherche que vous avez créé. L’exécution de cette commande ne modifie aucun comportement dans votre serveur FHIR.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
Par exemple, pour rechercher tous les paramètres de recherche d’un patient, utilisez ce qui suit.
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
Le résultat ressemble à ce qui suit.
{
"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 seule ressource pour tester la recherche avec l’élément. Tout d’abord, vous réindexez une seule ressource :
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
L’exécution de ce paramètre définit les index des paramètres de recherche pour la ressource spécifique que vous avez définie pour ce type de ressource. Cela effectue une mise à jour du serveur FHIR. Vous pouvez maintenant rechercher et définir l’en-tête d’index partiels sur true, ce qui signifie qu’il retourne les résultats où l’une des ressources qui ont le paramètre de recherche indexé, même si toutes les ressources de ce type l’ont indexée.
En continuant avec notre exemple, vous pouvez indexer un patient pour activer la course SearchParameter US Core comme suit.
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
Recherchez ensuite les patients qui ont une race spécifique :
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Une fois que vous êtes convaincu que votre paramètre de recherche fonctionne comme prévu, exécutez ou planifiez votre travail de réindexation afin que les paramètres de recherche puissent être utilisés dans le serveur FHIR pour les cas d’usage de production.
Mettre à jour un paramètre de recherche
Pour mettre à jour un paramètre de recherche, utilisez cette option PUT pour créer une nouvelle version du paramètre de recherche. Vous devez inclure l’élément SearchParameter ID id du corps de la PUT demande et dans l’appel PUT .
Remarque
Si vous ne connaissez pas l’ID de votre paramètre de recherche, vous pouvez le rechercher. L’utilisation GET {{FHIR_URL}}/SearchParameter retourne tous les paramètres de recherche personnalisés, et vous pouvez parcourir la liste pour rechercher le paramètre de recherche dont vous avez besoin. Vous pouvez également limiter la recherche par nom. Avec l’exemple suivant, vous pouvez rechercher le nom à l’aide USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRacede .
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 est une mise à jour SearchParameter et les incréments de version.
Avertissement
Soyez prudent lors de la mise à jour de SearchParameters qui ont déjà été indexés dans votre base de données. La modification du comportement d’un SearchParameter existant peut avoir des répercussions 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 ce qui suit.
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Avertissement
Soyez prudent lors de la suppression de SearchParameters qui ont déjà été indexés dans votre base de données. La modification du comportement d’un SearchParameter existant peut avoir des répercussions 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. Vous pouvez ensuite apprendre à réindexer votre serveur FHIR.
Remarque
FHIR® est une marque déposée de HL7 utilisé avec l’autorisation de HL7.