Cette page explique comment gérer les ressources FHIR en exécutant des groupes FHIR, qui rassemblent une collection de ressources FHIR et d'opérations à effectuer sur ces ressources.
La méthode ExecuteBundle
met en œuvre l'interaction standard FHIR par lot/transaction (DSTU2, STU3 et R4) et les opérations d'historique.
Groupes FHIR
Un groupe FHIR contient un tableau d'entrées, chacune représentant une opération, par exemple, la création, la mise à jour ou la suppression sur une ressource, telle qu'une observation ou un patient. Consultez les descriptions détaillées des éléments de la ressource groupée.
Lorsque vous exécutez un groupe FHIR, le type de groupe détermine comment les opérations du groupe sont effectuées. Les types de groupes suivants sont disponibles :
batch
: exécute les opérations en tant que plusieurs requêtes indépendantes.transaction
: exécute les opérations en tant que plusieurs requêtes interdépendantes.history
: insère les entrées dans l'historique d'une ressource.
Par exemple, supposons qu'un groupe de transactions comprenne la création d'une ressource Patient et d'une ressource Observation. Si la requête de création de ressource Patient échoue, la ressource Observation n'est pas créée.
Si une opération échoue lorsque le type de groupe est batch
, l'API Cloud Healthcare exécute les opérations restantes dans le groupe. Si une opération échoue lorsque le type de groupe est transaction
, l'API Cloud Healthcare arrête l'exécution des opérations et effectue un rollback de la transaction.
Lots d'historiques
Les bundles d'historique sont des extensions personnalisées de la norme FHIR qui prennent en charge les cas d'utilisation de sauvegarde et de restauration, tels que la synchronisation. Vous pouvez utiliser des bundles d'historique pour insérer ou remplacer des versions de ressources dans l'historique d'une ressource FHIR. Vous ne pouvez supprimer des versions de ressources qu'à l'aide de la méthode Resource-purge
. Le groupe history
est exécuté en tant que transaction unique avec une limite de 100 entrées par groupe. Si une version de ressource du bundle history
possède un code temporel supérieur à la dernière version du datastore FHIR, la dernière version sera mise à jour en conséquence. Si le bundle history
est correctement inséré, une réponse vide est renvoyée. Sinon, une OperationOutcome
est renvoyée pour décrire l'échec.
La prise en charge des lots d'historique n'est pas activée par défaut. Un administrateur de store FHIR doit définir enableHistoryModifications
sur true
dans la configuration du store FHIR.
Vous ne pouvez pas utiliser de bundles d'historique si disableResourceVersioning
est défini sur true
dans la configuration du magasin FHIR.
Les bundles d'historique sont fournis au même format que celui dans lequel ils sont renvoyés à partir de la méthode fhir.history
. Pour être valide, chaque entrée de bundle nécessite un ID de ressource, un code temporel de modification et un état. De plus, toutes les entrées doivent avoir le même ID de ressource. L'ID de ressource est fourni avec le champ resource.id
ou le champ request.url
. Si des champs sont fournis, l'ID de ressource doit être le même. L'horodatage de la ressource est fourni avec le champ meta.lastUpdated
dans la ressource ou le champ response.lastModified
.
Accorder des autorisations pour exécuter des groupes
Le rôle d'autorisation datasets.fhirStores.fhir.executeBundle
est requis pour exécuter des groupes. Pour accorder cette autorisation, utilisez le rôle healthcare.fhirResourceReader
. Pour connaître les étapes à suivre pour accorder cette autorisation, consultez la section Modifier une stratégie.
Pour exécuter des groupes d'historique, le rôle d'autorisation datasets.fhirStores.fhir.import
est également requis.
L'API Cloud Healthcare vérifie les autorisations pour chaque opération du groupe.
Si vous disposez de l'autorisation healthcare.fhirResources.create
, mais pas de l'autorisation healthcare.fhirResources.update
, vous ne pouvez exécuter que des groupes contenant des opérations healthcare.fhirResources.create
.
Exécuter un groupe
Pour exécuter un groupe FHIR, utilisez la méthode projects.locations.datasets.fhirStores.fhir.executeBundle
.
Dans les exemples suivants, BUNDLE.Json correspond au chemin d'accès et au nom de fichier d'un groupe FHIR encodé au format JSON. Vous pouvez également inclure le groupe dans le corps de la requête.
L'exemple de groupe suivant crée une ressource Patient et en supprime une autre :
{
"resourceType": "Bundle",
"id": "bundle-transaction",
"meta": {
"lastUpdated": "2018-03-11T11:22:16Z"
},
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Smith",
"given": [
"Darcy"
]
}
],
"gender": "female",
"address": [
{
"line": [
"123 Main St."
],
"city": "Anycity",
"state": "CA",
"postalCode": "12345"
}
]
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"request": {
"method": "DELETE",
"url": "Patient/1234567890"
}
}
]
}
Les exemples suivants montrent comment exécuter un groupe.
curl
Pour exécuter un groupe, exécutez une requête POST
et spécifiez les informations suivantes :
- Le nom et l'emplacement de l'ensemble de données parent et du magasin FHIR
- L'emplacement du fichier de groupe sur votre ordinateur local
- Un jeton d'accès
L'exemple suivant montre une requête POST
utilisant curl :
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
Quel que soit le résultat des opérations individuelles, après l'exécution d'un groupe par lot, le serveur renvoie une représentation encodée au format JSON d'une ressource Bundle
de type batch-response
. La ressource Bundle
contient une entrée pour chaque entrée de la requête et le résultat du traitement de l'entrée, pouvant se composer d'une combinaison de résultats de réussite et d'erreur.
Si un lot de transactions réussit, le serveur renvoie une représentation encodée au format JSON d'une ressource Bundle
de type transaction-response
contenant une entrée pour chaque entrée de la requête avec le résultat de réussite de l'opération.
Si une erreur se produit lors de l'exécution d'un groupe de transactions, le corps de la réponse ne contient aucun groupe. Au lieu de cela, il contient une ressource OperationOutcome
encodée au format JSON décrivant la raison de l'erreur. Les opérations réussies qui ont été annulées ne sont pas signalées dans la réponse.
L'exemple de groupe suivant correspond au résultat de l'exécution de l'exemple ci-dessus. La première entrée indique la réussite de l'opération de création d'un Patient et inclut l'ID de la nouvelle ressource. La deuxième entrée indique la réussite de l'opération de suppression.
{ "entry": [ { "response": { "location": projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID, "status": "201 Created" } }, { "response": { "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Pour exécuter un groupe, exécutez une requête POST
et spécifiez les informations suivantes :
- Le nom et l'emplacement de l'ensemble de données parent et du magasin FHIR
- L'emplacement du fichier de groupe sur votre ordinateur local
- Un jeton d'accès
L'exemple suivant montre une requête POST
utilisant Windows PowerShell :
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
Quel que soit le résultat des opérations individuelles, après l'exécution d'un groupe par lot, le serveur renvoie une représentation encodée au format JSON d'une ressource Bundle
de type batch-response
. La ressource Bundle
contient une entrée pour chaque entrée de la requête et le résultat du traitement de l'entrée, pouvant se composer d'une combinaison de résultats de réussite et d'erreur.
Si un lot de transactions réussit, le serveur renvoie une représentation encodée au format JSON d'une ressource Bundle
de type transaction-response
contenant une entrée pour chaque entrée de la requête avec le résultat de réussite de l'opération.
Si une erreur se produit lors de l'exécution d'un groupe de transactions, le corps de la réponse ne contient aucun groupe. Au lieu de cela, il contient une ressource OperationOutcome
encodée au format JSON décrivant la raison de l'erreur. Les opérations réussies qui ont été annulées ne sont pas signalées dans la réponse.
L'exemple de groupe suivant correspond au résultat de l'exécution de l'exemple ci-dessus. La première entrée indique la réussite de l'opération de création d'un Patient et inclut l'ID de la nouvelle ressource. La deuxième entrée indique la réussite de l'opération de suppression.
{ "entry": [ { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "location": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
Go
Java
Node.js
Un exemple de fichier de groupe est disponible dans le dépôt GitHub de l'exemple de code.
Python
Un exemple de fichier de groupe est disponible dans le dépôt GitHub de l'exemple de code.
Effectuer une requête PATCH
Vous pouvez utiliser des groupes FHIR pour effectuer des requêtes JSON PATCH
sur des ressources FHIR.
Pour en savoir plus, consultez la section Exécuter une requête PATCH
dans un groupe FHIR.
Résoudre les références aux ressources créées dans un groupe
Les ressources d'un groupe de transactions peuvent contenir des références à des ressources qui n'existent pas dans le système cible, mais qui sont créées lors de l'exécution du groupe. L'API Cloud Healthcare résout l'association entre les ressources à l'aide du champ entry.fullUrl
. Les références qui correspondent à la valeur entry.fullUrl
d'une autre ressource du groupe sont réécrites dans l'ID de la ressource correspondante dans le magasin. Cette opération réussit quel que soit l'ordre des opérations dans le groupe.
L'API Cloud Healthcare accepte fullUrl
aux formats suivants :
urn:uuid:UUID
urn:oid:OID
- N'importe quelle URL
- Un nom dla ressource au format
RESOURCE_TYPE/RESOURCE_ID
, par exemplePatient/123
. Il n'est pas recommandé d'utiliser ce format, carfullUrl
est un espace réservé local au groupe. Cela peut prêter à confusion si une ressource du magasin porte le même nom, mais que la ressource du groupe est associée à un nom différent suite à une opération de création.
L'exemple de groupe suivant crée une ressource Patient et une ressource Observation faisant référence à cette ressource Patient.
{
"resourceType": "Bundle",
"type": "transaction",
"entry":[
{
"request": {
"method":"POST",
"url":"Patient"
},
"fullUrl": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9",
"resource": {
"resourceType":"Patient",
"gender":"male"
}
},
{
"request": {
"method":"POST",
"url":"Observation"
},
"resource": {
"resourceType":"Observation",
"subject": {
"reference": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9"
},
"status":"preliminary",
"code": {
"text":"heart rate"
}
}
}
]
}
Les exemples suivants montrent comment exécuter un groupe.
curl
Un exemple de fichier de groupe est disponible dans le dépôt GitHub de l'exemple de code.
Pour exécuter un groupe, exécutez une requête POST et spécifiez les informations suivantes :
- Le nom et l'emplacement de l'ensemble de données parent et du magasin FHIR
- L'emplacement du fichier de groupe dans Cloud Storage
- Un jeton d'accès
L'exemple suivant montre une requête POST
utilisant curl :
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
L'exemple de groupe suivant correspond au résultat de l'exécution de l'exemple ci-dessus. La première entrée indique la réussite de l'opération de création d'un Patient et inclut l'ID de la nouvelle ressource. La deuxième entrée indique que l'opération a réussi à créer l'observation et inclut l'ID de la nouvelle ressource.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Un exemple de fichier de groupe est disponible dans le dépôt GitHub de l'exemple de code.
Pour exécuter un groupe, exécutez une requête POST et spécifiez les informations suivantes :
- Le nom et l'emplacement de l'ensemble de données parent et du magasin FHIR
- L'emplacement du fichier de groupe dans Cloud Storage
- Un jeton d'accès
L'exemple suivant montre une requête POST
utilisant Windows PowerShell :
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
L'exemple de groupe suivant correspond au résultat de l'exécution de l'exemple ci-dessus. La première entrée indique la réussite de l'opération de création d'un Patient et inclut l'ID de la nouvelle ressource. La deuxième entrée indique que l'opération a réussi à créer l'observation et inclut l'ID de la nouvelle ressource.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }