Fonctionnalités de l’API REST FHIR pour l’API Azure pour FHIR
Dans cet article, nous allons aborder certaines des nuances des interactions RESTful de l’API Azure pour FHIR.
Création/mise à jour conditionnelle
L’API Azure pour FHIR prend en charge la création, la création conditionnelle, la mise à jour et la mise à jour conditionnelle, comme défini 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, il génère le message d’erreur 412 Échec de la condition préalable.
Supprimer et supprimer conditionnel
L’API Azure pour FHIR offre deux types de suppression. Il y a Supprimer, qui est également connu sous le nom de Suppression réversible + Suppression réversible et Suppression conditionnelle.
Supprimer (Suppression définitive + 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 à la version ultérieures d’une ressource retournent un code d’état HTTP 410. Par conséquent, la ressource n’est plus trouvée par la recherche. En outre, l’API Azure pour 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 à hardDelete true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Si vous ne transmettez 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, l’API Azure pour 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 définitive, les enregistrements dans l’API Azure pour 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 avec des données.
Si l’ID de la ressource 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 dans l’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 que vous souhaitez 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 définitive ou une opération de vidage de l’historique.
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 du 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 FHIRPath conditionnel (ce 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 de correctif avec FHIR.
Notes
Lors de l’utilisation PATCH de stu3, et si vous demandez un bundle d’historique Bundle.entry.request.method , la ressource corrigée est mappée à PUT. Cela est dû au fait que STU3 ne contient pas de définition pour le PATCH verbe dans l’ensemble de valeurs HTTPVerb.
Correctif 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 FHIRPath Patch 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écommunication à 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 FHIRPath Patch 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 dans des bundles. Pour obtenir d’autres exemples, consultez l’exemple de fichier REST du 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. Json Patch 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
}
]
Toute opération de correctif JSON doit 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 obtenir d’autres exemples, consultez l’exemple de fichier REST de correctif JSON.
Correctif JSON dans les bundles
Par défaut, le correctif JSON n’est pas pris en charge dans les ressources bundle. Cela est dû au fait qu’un bundle prend uniquement en charge avec les ressources FHIR et que la charge utile du 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 de l’API Azure pour FHIR. Ensuite, vous pouvez en savoir plus sur les principaux aspects de la recherche de ressources dans FHIR.
(FHIR®) est une marque déposée de HL7 et est utilisé avec l’autorisation de HL7.