Fonctionnalités de l’API REST FHIR pour le service FHIR Azure Health Data Services
Dans cet article, nous allons aborder certaines des nuances des interactions RESTful du service FHIR Azure Health Data Services (ci-après appelé service FHIR).
Création/mise à jour conditionnelle
Le service FHIR prend en charge la création, la création conditionnelle, la mise à jour et la mise à jour conditionnelle telles que définies par la spécification FHIR. Un en-tête utile dans ces scénarios est l’en-tête If-Match . L’en-tête If-Match est utilisé et valide la version en cours de mise à jour avant d’effectuer la mise à jour. Si le ETag ne correspond pas au attendu ETag, le message d’erreur 412Condition préalable a échoué.
Suppression et suppression conditionnelle
Le service FHIR propose deux types de suppression. Il y a La suppression, qui est également connu comme Suppression matérielle + suppression réversible et suppression conditionnelle.
Supprimer (Suppression matérielle + réversible)
La suppression définie par la spécification FHIR nécessite qu’après la suppression d’une ressource, les lectures non spécifiques ultérieures d’une ressource retournent un code status HTTP 410. Par conséquent, la ressource n’est plus trouvée via la recherche. En outre, le service FHIR vous permet de supprimer complètement (y compris tout l’historique) la ressource. Pour supprimer complètement la ressource, vous pouvez passer un paramètre paramètres hardDelete à true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Si vous ne passez pas ce paramètre ou si vous n’avez pas la valeur hardDelete false, les versions historiques de la ressource seront toujours disponibles.
Notes
Si vous souhaitez uniquement supprimer l’historique, le service FHIR prend en charge une opération personnalisée appelée $purge-history. Cette opération vous permet de supprimer l’historique d’une ressource.
Suppression conditionnelle
La suppression conditionnelle vous permet de passer des critères de recherche pour supprimer une ressource. Par défaut, la suppression conditionnelle vous permet de supprimer un élément à la fois. Vous pouvez également spécifier le _count paramètre pour supprimer jusqu’à 100 éléments à la fois. Voici quelques exemples d’utilisation de la suppression conditionnelle.
Pour supprimer un seul élément à l’aide de la suppression conditionnelle, vous devez spécifier des critères de recherche qui retournent un seul élément.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Vous pouvez effectuer la même recherche, mais inclure hardDelete=true pour supprimer également tout l’historique.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Pour supprimer plusieurs ressources, incluez _count=100 le paramètre. Ce paramètre supprime jusqu’à 100 ressources qui correspondent aux critères de recherche.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Récupération des fichiers supprimés
Si vous n’utilisez pas le paramètre de suppression matérielle, les enregistrements dans le service FHIR doivent toujours exister. Les enregistrements peuvent être trouvés en effectuant une recherche dans l’historique sur la ressource et en recherchant la dernière version contenant des données.
Si l’ID de la ressource qui a été supprimée est connu, utilisez le modèle d’URL suivant :
<FHIR_URL>/<resource-type>/<resource-id>/_history
Par exemple : https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Si l’ID de la ressource n’est pas connu, effectuez une recherche d’historique sur l’ensemble du type de ressource :
<FHIR_URL>/<resource-type>/_history
Par exemple : https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
Une fois que vous avez trouvé l’enregistrement à restaurer, utilisez l’opération PUT pour recréer la ressource avec le même ID ou utilisez l’opération POST pour créer une nouvelle ressource avec les mêmes informations.
Notes
Il n’existe aucune expiration basée sur le temps pour les données d’historique/suppression réversible. La seule façon de supprimer des données d’historique/supprimées de manière réversible consiste à effectuer une suppression matérielle ou une opération d’historique de purge.
Lots et offres groupées de transactions
Dans FHIR, les offres groupées peuvent être considérées comme un conteneur qui contient plusieurs ressources. Les lots et les offres groupées de transactions permettent aux utilisateurs d’envoyer un ensemble d’actions à effectuer sur un serveur dans une requête/réponse HTTP unique. Les actions peuvent être effectuées indépendamment sous la forme d’un « lot » ou d’une « transaction » atomique unique où l’ensemble des modifications réussit ou échoue en tant qu’entité unique. Des actions sur plusieurs ressources de types identiques ou différents peuvent être envoyées, telles que la création, la mise à jour ou la suppression. Pour plus d’informations, consultez offres groupées FHIR.
Une interaction par lot ou par lot avec le service FHIR est effectuée avec la commande HTTP POST à l’URL de base.
POST {{fhir_url}}
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "patient-1",
"name": [
{
"given": ["Alice"],
"family": "Smith"
}
],
"gender": "female",
"birthDate": "1990-05-15"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Patient",
"id": "patient-2",
"name": [
{
"given": ["Bob"],
"family": "Johnson"
}
],
"gender": "male",
"birthDate": "1985-08-23"
},
"request": {
"method": "POST",
"url": "Patient"
}
}
}
]
}
Dans le cas d’un lot, chaque entrée est traitée comme une interaction ou une opération individuelle. Dans le cas d’un ensemble de transactions, toutes les interactions ou opérations réussissent ou échouent ensemble. Pour un lot ou un bundle de transactions réussi, la réponse contient une entrée pour chaque entrée de la demande. En cas d’échec de l’offre groupée de transactions, le service FHIR retourne une seule opérationOutcome.
Notes
Pour les lots groupés, il ne doit y avoir aucune interdépendance entre les différentes entrées dans le bundle FHIR. La réussite ou l’échec d’une entrée ne doit pas avoir d’impact sur la réussite ou l’échec d’une autre entrée.
Traitement parallèle de lots groupés en préversion publique
Actuellement, les lots et les offres groupées de transactions sont exécutés en série dans le service FHIR. Pour améliorer les performances et le débit, nous activez le traitement parallèle des lots groupés en préversion publique.
Pour utiliser la fonctionnalité de traitement par lots par lots parallèles :
- Définissez la valeur de l’en-tête « x-bundle-processing-logic » sur « parallel ».
- Vérifiez qu’il n’y a pas de chevauchement d’ID de ressource qui s’exécute sur les opérations DELETE, POST, PUT ou PATCH dans le même bundle.
Important
Le traitement parallèle de l’offre groupée est actuellement en préversion publique. Ces interfaces de programmation d’applications et kits de développement logiciel (SDK) en préversion sont fournis sans contrat au niveau du service. Nous vous recommandons de ne pas les utiliser pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d’utilisation supplémentaires pour microsoft Azure Previews
Correctif et correctif conditionnel
Le correctif est une opération RESTful précieuse lorsque vous devez mettre à jour uniquement une partie de la ressource FHIR. L’utilisation d’un correctif vous permet de spécifier le ou les éléments que vous souhaitez mettre à jour dans la ressource sans avoir à mettre à jour l’enregistrement entier. FHIR définit trois façons de corriger les ressources : JSON Patch, XML Patch et FHIRPath Patch. Le service FHIR prend en charge à la fois le correctif JSON et le correctif FHIRPath, ainsi que le correctif JSON conditionnel et le correctif conditionnel FHIRPath (qui vous permet de corriger une ressource en fonction d’un critère de recherche au lieu d’un ID de ressource). Pour parcourir quelques exemples, reportez-vous à l’exemple de fichier REST de correctif FHIRPath et au fichier REST de correctif JSON pour chaque approche. Pour plus d’informations, consultez la documentation HL7 sur les opérations correctives avec FHIR.
Notes
Lors de l’utilisation PATCH de STU3, et si vous demandez un bundle d’historique, la ressource corrigée est Bundle.entry.request.method mappée à PUT. Cela est dû au fait que STU3 ne contient pas de définition pour le PATCH verbe dans le jeu de valeurs HTTPVerb.
Corriger avec le correctif FHIRPath
Cette méthode de correctif est la plus puissante, car elle tire parti de FHIRPath pour sélectionner l’élément à cibler. Un scénario courant consiste à utiliser le correctif FHIRPath pour mettre à jour un élément dans une liste sans connaître l’ordre de la liste. Par exemple, si vous souhaitez supprimer les informations de télécommunications à domicile d’un patient sans connaître l’index, vous pouvez utiliser l’exemple ci-dessous.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Type de contenu : application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Toutes les opérations de correctif FHIRPath doivent avoir l’en-tête application/fhir+json Content-Type défini. FHIRPatch Patch prend en charge les opérations d’ajout, d’insertion, de suppression, de suppression et de déplacement. Les opérations de correctif FHIRPatch peuvent également être facilement intégrées à des bundles. Pour plus d’exemples, consultez l’exemple de fichier REST correctif FHIRPath.
Correctif avec le correctif JSON
Le correctif JSON dans le service FHIR est conforme à la spécification bien utilisée définie par le groupe de travail d’ingénierie Internet. Le format de charge utile n’utilise pas de ressources FHIR et utilise à la place un document JSON tirant parti de JSON-Pointers pour la sélection d’éléments. Le correctif JSON est plus compact et a une opération de test qui vous permet de vérifier qu’une condition est vraie avant d’effectuer le correctif. Par exemple, si vous souhaitez définir un patient comme décédé uniquement s’il n’est pas déjà marqué comme décédé, vous pouvez utiliser l’exemple ci-dessous.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Type de contenu : application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Toutes les opérations de correctif JSON doivent avoir l’en-tête application/json-patch+json Content-Type défini. JSON Patch prend en charge les opérations d’ajout, de suppression, de remplacement, de copie, de déplacement et de test. Pour plus d’exemples, consultez l’exemple de fichier REST de correctif JSON.
Correctif JSON dans les offres groupées
Par défaut, le correctif JSON n’est pas pris en charge dans les ressources groupées. Cela est dû au fait qu’un bundle prend uniquement en charge les ressources FHIR et que la charge utile de correctif JSON n’est pas une ressource FHIR. Pour contourner ce problème, nous allons utiliser des ressources binaires avec un type de contenu et "application/json-patch+json" l’encodage base64 de la charge utile JSON à l’intérieur d’un bundle. Pour plus d’informations sur cette solution de contournement, consultez cette rubrique sur le zulip de conversation FHIR.
Dans l’exemple ci-dessous, nous voulons remplacer le sexe du patient par une femme. Nous avons pris le correctif [{"op":"replace","path":"/gender","value":"female"}] JSON et l’avons encodé en base64.
POST https://{FHIR-SERVICE-HOST-NAME}/
Type de contenu : application/json
{
"resourceType": "Bundle",
"id": "bundle-batch",
"type": "batch",
"entry": [
{
"fullUrl": "Patient/{PatientID}",
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/{PatientID}"
}
}
]
}
Étapes suivantes
Dans cet article, vous avez découvert certaines des fonctionnalités REST du service FHIR. Ensuite, vous pouvez en savoir plus sur les aspects clés de la recherche de ressources dans le service FHIR.
(FHIR®) est une marque déposée de HL7 et est utilisé avec l’autorisation de HL7.