Cette page explique comment utiliser Pub/Sub pour recevoir des notifications lorsqu'un événement clinique se produit dans un store FHIR.
Vous pouvez utiliser les notifications Pub/Sub pour plusieurs cas d'utilisation, y compris pour déclencher le traitement en aval ou l'analyse de nouvelles données. Par exemple, un modèle de machine learning peut recevoir des notifications lorsque de nouvelles données sont disponibles pour l'entraînement et générer des insights ou des prédictions pour améliorer les soins aux patients.
Présentation
Vous pouvez recevoir des notifications Pub/Sub lorsqu'une ressource FHIR est créée, mise à jour, corrigée ou supprimée dans un store FHIR. L'API Cloud Healthcare n'envoie pas de notifications lorsqu'une ressource FHIR est importée depuis Cloud Storage.
Pour recevoir des notifications, vous devez créer un sujet et un abonnement Pub/Sub, puis configurer le store FHIR pour qu'il envoie des notifications au sujet.
Le schéma suivant montre comment les notifications Pub/Sub sont créées et distribuées lorsqu'une ressource FHIR est créée dans un store FHIR à l'aide de la méthode fhir.create
. Les étapes sont les mêmes lorsqu'une ressource FHIR est mise à jour, corrigée ou supprimée.
Figure 1 : Utiliser des notifications Pub/Sub pour les modifications apportées à un store FHIR
La figure 1 illustre les étapes suivantes:
- Un appelant effectue une requête
fhirStores.fhir.create
pour créer une ressource FHIR. - Le store FHIR reçoit la requête, crée un message Pub/Sub et l'envoie au sujet Pub/Sub configuré dans le store FHIR.
- Pub/Sub transfère le message aux abonnements associés au sujet.
- Les abonnés reçoivent une notification, sous la forme d'un message Pub/Sub, de leur abonnement. Chaque abonnement peut avoir un ou plusieurs abonnés pour accroître le parallélisme.
Configuration des notifications
Vous pouvez configurer les notifications Pub/Sub et leur comportement dans un objet FhirNotificationConfig
d'un store FHIR. Chaque store FHIR peut avoir un FhirNotificationConfig
configuré.
Le tableau suivant décrit les champs de l'objet FhirNotificationConfig
.
Champ | Description | Exemple |
---|---|---|
pubsubTopic |
Sujet Pub/Sub à associer au store FHIR. Les notifications sont envoyées au sujet spécifié. | projects/my-project/topics/my-topic |
sendFullResource |
Permet d'inclure dans une notification le contenu complet d'une ressource FHIR créée, mise à jour ou corrigée. Ce champ n'a aucun effet sur les notifications envoyées lorsque des ressources FHIR sont supprimées. Pour inclure le contenu complet d'une ressource supprimée, définissez sendPreviousResourceOnDelete sur true . |
true |
sendPreviousResourceOnDelete |
Indique s'il faut inclure dans une notification le contenu complet d'une ressource FHIR supprimée. Ce champ n'a aucun effet sur les notifications envoyées lorsque des ressources FHIR sont créées, mises à jour ou corrigées. | true |
Format et contenu des notifications
Chaque notification Pub/Sub contient un objet message
contenant des informations sur l'événement clinique. L'objet message
se présente comme suit:
{ "message": { "attributes": { "action": "ACTION", "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME", "payloadType": "PAYLOAD_TYPE", "resourceType": "FHIR_RESOURCE_TYPE", "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID", "versionId": "VERSION_ID" }, "data": "BASE_64_ENCODED_DATA", "messageId": "MESSAGE_ID", "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" } }
Pour en savoir plus sur les champs supplémentaires inclus dans chaque message Pub/Sub, consultez les sections ReceivedMessage
et PubsubMessage
.
Le tableau suivant décrit chaque champ de l'objet attributes
:
Attribut | Description | Exemple |
---|---|---|
action |
Action qui s'est produite sur une ressource FHIR. Les valeurs possibles sont les suivantes:
|
CreateResource |
resourceType |
Type de ressource FHIR qui a été modifié. Les valeurs possibles incluent tout type de ressource FHIR compatible avec l'API Cloud Healthcare. | Patient |
payloadType |
Type de charge utile du message (NameOnly ou FullResource ). |
FullResource |
storeName |
Nom complet de la ressource du store FHIR dans lequel l'action s'est produite. | projects/my-project/locations/us/datasets/my-dataset/fhirStores/my-fhir-store |
lastUpdatedTime |
Horodatage de la dernière modification de la ressource FHIR. Le code temporel utilise le format RFC 1123. | Mon, 01 Jan 2020 00:00:00 UTC |
versionId |
ID de la version la plus récente de la ressource FHIR sur laquelle l'action s'est produite. Pour en savoir plus sur les ID de version, consultez la section Répertorier les versions des ressources FHIR. | MTY4MzA2MDQzOTI5NjIxMDAwMA |
Le tableau suivant décrit les champs restants dans l'objet message
:
Champ | Description | Exemple |
---|---|---|
data |
Chaîne encodée en base64 du nom de la ressource FHIR ou du contenu de la ressource FHIR, en fonction des valeurs spécifiées dans FhirNotificationConfig . |
|
messageId |
Identifiant du message Pub/Sub. | |
publishTime |
Heure à laquelle le serveur Pub/Sub a publié le message. |
Spécifier les informations à inclure dans les notifications
Les notifications Pub/Sub, comme indiqué dans la section Format et contenu des notifications, incluent un ensemble standard de champs. Vous pouvez inclure soit la ressource FHIR complète, soit uniquement son nom dans chaque notification. Le nom de la ressource contient le chemin d'accès complet à la ressource et l'ID de ressource au format suivant:
projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID
Les informations sur les ressources FHIR sont stockées dans le champ data
en tant que chaîne encodée en base64.
En incluant le contenu complet d'une ressource FHIR, vous n'avez pas besoin d'interroger séparément Pub/Sub et l'API Cloud Healthcare pour obtenir les détails de la ressource.
Obtenir le nom de la ressource FHIR
Pour n'inclure que le nom d'une ressource FHIR lorsque vous créez, mettez à jour ou corrigez la ressource, définissez sendFullResource
sur false
.
Pour n'inclure que le nom lorsque vous supprimez une ressource FHIR, définissez sendPreviousResourceOnDelete
sur false
.
Lorsque vous affichez la notification, l'objet message
se présente comme suit:
{ "message": { "attributes": { "action": "{CreateResource|PatchResource|UpdateResource|DeleteResource}", "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME", "payloadType": "NameOnly", "resourceType": "FHIR_RESOURCE_TYPE", "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID", "versionId": "VERSION_ID" }, "data": "BASE64_ENCODED_FHIR_RESOURCE_NAME", "messageId": "MESSAGE_ID", "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" } }
Notez les points suivants dans la notification:
Le champ
payloadType
est défini surNameOnly
pour fournir les informations suivantes concernant la requête:- Pour les opérations de création, de mise à jour et d'application de correctifs,
sendFullResource
est défini surfalse
. - Pour les opérations de suppression,
sendPreviousResourceOnDelete
est défini surfalse
.
- Pour les opérations de création, de mise à jour et d'application de correctifs,
Seul le nom de la ressource FHIR est inclus dans le champ
data
. Le nom est encodé en tant que chaîne encodée en base64.
Obtenir la création, la mise à jour ou le correctif du contenu des ressources FHIR
Pour inclure le contenu complet d'une ressource FHIR lorsque vous créez, mettez à jour ou corrigez la ressource, définissez sendFullResource
sur true
.
Ce comportement ne s'applique pas si vous supprimez une ressource FHIR. Si vous supprimez une ressource FHIR et que sendFullResource
est défini sur true
, mais que sendPreviousResourceOnDelete
est défini sur false
, la notification est la même que lorsque vous récupérez uniquement le nom de la ressource FHIR. Pour inclure le contenu des ressources FHIR lorsqu'une ressource FHIR est supprimée, consultez la section Obtenir le contenu des ressources FHIR supprimées.
Lorsque vous affichez la notification, l'objet message
se présente comme suit:
{ "message": { "attributes": { "action": "{CreateResource|PatchResource|UpdateResource}", "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME", "payloadType": "FullResource", "resourceType": "FHIR_RESOURCE_TYPE", "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID", "versionId": "VERSION_ID" }, "data": "BASE64_ENCODED_FHIR_RESOURCE_CONTENTS", "messageId": "MESSAGE_ID", "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" } }
Notez les points suivants dans la notification:
payloadType
est défini surFullResource
pour indiquer quesendFullResource
est défini surtrue
. Le contenu complet de la ressource FHIR est inclus dans le champdata
en tant que chaîne encodée en base64.- Le champ
data
contient le contenu de la ressource FHIR sous la forme d'une chaîne encodée en base64.
Récupérer le contenu des ressources FHIR supprimé
Pour inclure le contenu complet d'une ressource FHIR lorsque vous la supprimez, définissez sendPreviousResourceOnDelete
sur true
.
Lorsque vous affichez la notification, l'objet message
se présente comme suit:
{ "message": { "attributes": { "action": "DeleteResource", "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME", "payloadType": "FullResource", "resourceType": "FHIR_RESOURCE_TYPE", "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID", "versionId": "VERSION_ID" }, "data": "BASE64_ENCODED_FHIR_RESOURCE_CONTENTS", "messageId": "MESSAGE_ID", "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" } }
Notez les valeurs des champs suivants:
payloadType
est défini surFullResource
même sisendFullResource
est défini surfalse
.Le contenu complet de la ressource FHIR est inclus dans le champ
data
en tant que chaîne encodée en base64.Le champ
data
contient le contenu de la ressource FHIR sous forme de chaîne encodée en base64 avant la suppression de la ressource.
Configurer et afficher les notifications FHIR
Les exemples suivants montrent comment afficher la notification Pub/Sub générée lorsqu'une ressource FHIR est créée dans un store FHIR.
Avant de commencer
Avant de configurer et d'utiliser les notifications Pub/Sub, procédez comme suit:
Examiner le quota Pub/Sub
Familiarisez-vous avec les quotas et limites Pub/Sub. Pour savoir comment afficher votre quota, demander une augmentation de quota et savoir ce qui se passe si vous épuisez votre quota, consultez la section Les quotas et leur utilisation.
Activer l'API Pub/Sub
Dans la console Google Cloud, activez l'API Pub/Sub:
Configurer des autorisations Pub/Sub
Pour autoriser la publication de messages de l'API Cloud Healthcare vers Pub/Sub, vous devez ajouter le rôle pubsub.publisher
au compte de service Agent de service Cloud Healthcare de votre projet.
Consultez la section Autorisations Pub/Sub pour les magasins DICOM, FHIR et HL7v2 pour savoir comment ajouter le rôle requis.
Créer un sujet Pub/Sub
Pour créer un thème, consultez Créer un thème.
Un datastore individuel peut avoir son propre sujet Pub/Sub ou plusieurs datastores peuvent partager le même sujet.
Utilisez le format suivant lorsque vous spécifiez le sujet Pub/Sub:
projects/PROJECT_ID/topics/TOPIC_NAME
PROJECT_ID
correspond à l'ID de votre projet Google Cloud et TOPIC_NAME
au nom du sujet Pub/Sub.
Créer un abonnement Pub/Sub
Pour recevoir des messages publiés dans un sujet, vous devez créer un abonnement Pub/Sub. Chaque sujet Pub/Sub nécessite au moins un abonnement Pub/Sub. L'abonnement connecte le sujet à une application d'abonnés, qui reçoit et traite les messages publiés dans le sujet.
Pour créer un abonnement et l'associer à un sujet Pub/Sub, consultez la section Créer des abonnements.
Créer ou modifier un store FHIR
Créez ou modifiez un store FHIR avec un objet FhirNotificationConfig
configuré.
Les exemples suivants montrent comment modifier un store FHIR existant.
Les champs sendFullResource
et sendPreviousResourceOnDelete
sont définis sur true
, ce qui signifie que les notifications contiennent l'intégralité du contenu des ressources FHIR lorsqu'une ressource est créée, mise à jour, corrigée ou supprimée.
REST
Pour modifier le store FHIR, utilisez la méthode projects.locations.datasets.fhirStores.patch
.
Avant d'utiliser les données de requête, effectuez les remplacements suivants:
- PROJECT_ID : ID de votre projet Google Cloud
- LOCATION : emplacement de l'ensemble de données
- DATASET_ID : ensemble de données parent du magasin FHIR.
- FHIR_STORE_ID : ID du magasin FHIR.
- PUBSUB_TOPIC_ID : ID du sujet Pub/Sub
Corps JSON de la requête :
{ "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true, "sendPreviousResourceOnDelete": true } ] }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
.
Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :
cat > request.json << 'EOF' { "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true, "sendPreviousResourceOnDelete": true } ] } EOF
Exécutez ensuite la commande suivante pour envoyer votre requête REST :
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=notificationConfigs"
PowerShell
Enregistrez le corps de la requête dans un fichier nommé request.json
.
Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :
@' { "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true, "sendPreviousResourceOnDelete": true } ] } '@ | Out-File -FilePath request.json -Encoding utf8
Exécutez ensuite la commande suivante pour envoyer votre requête REST :
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=notificationConfigs" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON de ce type :
Créer une ressource FHIR
Créez une ressource FHIR dans le magasin FHIR. Cette requête force l'API Cloud Healthcare à publier un message dans le sujet Pub/Sub configuré.
Afficher la notification Pub/Sub
Affichez le message publié dans le sujet Pub/Sub. Le message suivant a été généré lorsqu'une ressource Patient a été créée dans un magasin FHIR.
Dans l'exemple de résultat, le contenu de la ressource FHIR se trouve dans une chaîne encodée en base64 du champ data
. Vous devez décoder la valeur encodée en base64 pour obtenir le contenu.
La plupart des plates-formes et des systèmes d'exploitation disposent d'outils pour décoder le texte en base64.
REST
Pour afficher le message publié dans le sujet Pub/Sub, utilisez la méthode projects.subscriptions.pull
. L'exemple suivant utilise le paramètre de requête ?maxMessages=10
pour spécifier le nombre maximal de messages à renvoyer dans la requête. Vous pouvez ajuster cette valeur en fonction de vos besoins.
Avant d'utiliser les données de requête, effectuez les remplacements suivants:
- PROJECT_ID : ID de votre projet Google Cloud
- PUBSUB_SUBSCRIPTION_ID : ID de l'abonnement associé au sujet Pub/Sub configuré dans le magasin FHIR
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
exécutez la commande suivante :
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=10"
PowerShell
exécutez la commande suivante :
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=10" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON de ce type :
gcloud
Pour afficher le message publié dans le sujet Pub/Sub, exécutez la commande gcloud pubsub subscriptions pull
.
L'exemple utilise les indicateurs Google Cloud CLI suivants:
--format=json
: affiche la sortie au format JSON.--auto-ack
: confirmer automatiquement chaque message extrait.
Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud
- PUBSUB_SUBSCRIPTION_ID : ID de l'abonnement associé au sujet Pub/Sub configuré dans le magasin FHIR
Exécutez la commande suivante:
Linux, macOS ou Cloud Shell
gcloud pubsub subscriptions pull \ projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID \ --auto-ack \ --format=json
Windows (PowerShell)
gcloud pubsub subscriptions pull ` projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ` --auto-ack ` --format=json
Windows (cmd.exe)
gcloud pubsub subscriptions pull ^ projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ^ --auto-ack ^ --format=json
Vous devriez obtenir un résultat semblable à celui-ci :
[ { "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR", "ackStatus": "SUCCESS", "message": { "attributes": { "action": "CreateResource", "lastUpdatedTime": "Mon, 01 Jan 2020 00:00:00 UTC", "payloadType": "FullResource", "resourceType": "Patient", "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID", "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA" }, "data": "wogICJiaXJ0aERhdGUiOiAiMTk3MC0wMS0wMSIsCiAgImdlbmRlciI6ICJmZW1hbGUiLAogICJpZCI6ICIyYmMwODg4Yi00MGRmLTQwYzctOWRhYi0wMzc4YTFiZWE0MGIiLAogICJtZXRhIjogewogICAgImxhc3RVcGRhdGVkIjogIjIwMjMtMDUtMDJUMjA6NDc6MTkuMjk2MjEwKzAwOjAwIiwKICAgICJ2ZXJzaW9uSWQiOiAiTVRZNE16QTJNRFF6T1RJNU5qSXhNREF3TUEiCiAgfSwKICAibmFtZSI6IFsKICAgIHsKICAgICAgImZhbWlseSI6ICJTbWl0aCIsCiAgICAgICJnaXZlbiI6IFsKICAgICAgICAiRGFyY3kiCiAgICAgIF0sCiAgICAgICJ1c2UiOiAib2ZmaWNpYWwiCiAgICB9CiAgXSwKICAicmVzb3VyY2VUeXBlIjogIlBhdGllbnQiCn0=", "messageId": "7586159156345265", "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" } } ]
Comportement lorsqu'une ressource FHIR est trop volumineuse ou que le trafic est élevé
Si la taille d'une ressource FHIR est trop importante ou si les serveurs de l'API Cloud Healthcare génèrent un trafic important, le champ attributes
peut ne contenir que le nom de la ressource et non son contenu complet.
Ce comportement se produit même si sendFullResource
et sendPreviousResourceOnDelete
sont définis sur true
.
Pour vérifier si une notification Pub/Sub contient la ressource FHIR complète, vérifiez le champ payloadType
dans la réponse après avoir affiché la notification.
Si payloadType
est défini sur nameOnly
, le champ attributes
n'a pas rempli entièrement les données de la ressource FHIR. Vous devez ensuite obtenir manuellement le contenu de la ressource FHIR à partir du store FHIR au lieu du message Pub/Sub.
Règles de stockage des messages de l'API Cloud Healthcare et Pub/Sub
Pour vous assurer que les données de l'API Cloud Healthcare et les données associées dans les messages Pub/Sub se trouvent dans la même région, vous devez définir une règle de stockage des messages Pub/Sub.
Vous devez définir explicitement la règle de stockage des messages sur le sujet Pub/Sub configuré sur le data store pour vous assurer que les données restent dans la même région. Par exemple, si l'ensemble de données et le magasin FHIR de l'API Cloud Healthcare sont dans la région us-central1
, la règle de stockage des messages doit autoriser uniquement la région us-central1
.
Pour configurer une règle de stockage des messages, consultez la page Configurer des règles de stockage des messages.
Résoudre les problèmes de messages Pub/Sub manqués
Si une notification ne peut pas être publiée dans Pub/Sub, une erreur est consignée dans Cloud Logging. Pour en savoir plus, consultez la section Afficher les journaux d'erreurs dans Cloud Logging.
Si le taux de génération d'erreurs dépasse une limite, les erreurs qui dépassent cette limite ne sont pas envoyées à Cloud Logging.
Afficher les notifications FHIR à l'aide de la configuration NotificationConfig
(obsolète)
La ressource FhirStore
contient un objet NotificationConfig
dans lequel vous pouvez spécifier un sujet Pub/Sub.
Les modifications apportées aux ressources FHIR contiennent toujours l'identifiant suivant dans le champ data
du message Pub/Sub:
projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID
L'ensemble de paires clé / valeur suivant est toujours inclus dans le champ attributes
du message:
Nom de l'attribut | Valeurs possibles | Exemple | Description |
---|---|---|---|
action |
|
CreateResource |
Type d'événement qui vient de se produire. |
resourceType |
Tout type de ressource FHIR. | Patient |
Type de ressource qui a été modifié. |
Étapes suivantes
- Gérez les pics temporaires de trafic des messages Pub/Sub à l'aide du contrôle de flux.
- Gérer les échecs de message
- Relire et supprimer définitivement des messages
- Consultez la présentation de l'architecture Pub/Sub.