Notifications Pub/Sub FHIR

Cette page explique comment utiliser Pub/Sub pour recevoir des notifications lorsqu'un événement clinique se produit dans un datastore 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 la prise en charge des 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 magasin 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 magasin FHIR pour envoyer des notifications au sujet.

Le diagramme suivant montre comment les notifications Pub/Sub sont créées et envoyées lorsqu'une ressource FHIR est créée dans un datastore FHIR à l'aide de la méthode fhir.create. La procédure est identique lorsque vous mettez à jour, corrigez ou supprimez une ressource FHIR.

Figure 1 : Utilisation des notifications Pub/Sub pour les modifications apportées à un datastore FHIR

La figure 1 illustre les étapes suivantes:

1. Un appelant envoie une requête fhirStores.fhir.create pour créer une ressource FHIR.
2. Le magasin FHIR reçoit la requête, crée un message Pub/Sub et l'envoie au sujet Pub/Sub configuré sur le magasin FHIR.
3. Pub/Sub transfère le message aux abonnements associés au sujet.
4. 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 sur un magasin FHIR. Chaque magasin FHIR peut avoir un FhirNotificationConfig configuré.

Le tableau suivant décrit les champs de l'objet FhirNotificationConfig.

Format et contenu des notifications

Chaque notification Pub/Sub contient un objet message qui contient des informations sur l'événement clinique. L'objet message ressemble à ceci:

{
  "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 ReceivedMessage et PubsubMessage.

Le tableau suivant décrit chaque champ de l'objet attributes:

Le tableau suivant décrit les autres champs de l'objet 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 la ressource FHIR complète ou simplement son nom dans chaque notification. Le nom de la ressource contient le chemin d'accès complet à la ressource et l'ID de la 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 sous la forme d'une 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 la créez, la mettez à jour ou la corrigez, 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 ressemble à ceci:

{
  "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"
  }
}

Veuillez noter les points suivants dans la notification:

• Le champ payloadType est défini sur NameOnly pour indiquer les informations suivantes sur la requête:

  • Pour les opérations de création, de mise à jour et de correction, sendFullResource est défini sur false.
  • Pour les opérations de suppression, sendPreviousResourceOnDelete est défini sur false.

• Seul le nom de la ressource FHIR est inclus dans le champ data. Le nom est encodé sous la forme d'une chaîne encodée en base64.

Obtenir le contenu des ressources FHIR créées, mises à jour ou corrigées

Pour inclure l'intégralité du contenu d'une ressource FHIR lorsque vous la créez, la mettez à jour ou la corrigez, 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 identique à celle que vous obtenez lorsque vous ne récupérez que le nom de la ressource FHIR. Pour inclure le contenu d'une ressource FHIR lorsqu'elle est supprimée, consultez Obtenir le contenu des ressources FHIR supprimées.

Lorsque vous affichez la notification, l'objet message ressemble à ceci:

{
  "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"
  }
}

Veuillez noter les points suivants dans la notification:

• payloadType est défini sur FullResource pour indiquer que sendFullResource est défini sur true. Le contenu complet de la ressource FHIR est inclus dans le champ data sous la forme d'une 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.

Obtenir le contenu des ressources FHIR supprimées

Pour inclure l'intégralité du contenu d'une ressource FHIR lorsque vous la supprimez, définissez sendPreviousResourceOnDelete sur true.

Lorsque vous affichez la notification, l'objet message ressemble à ceci:

{
  "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 sur FullResource, même si sendFullResource est défini sur false.

  Le contenu complet de la ressource FHIR est inclus dans le champ data sous la forme d'une chaîne encodée en base64.

• Le champ data contient le contenu de la ressource FHIR sous forme de chaîne encodée en base 64 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 datastore FHIR.

Avant de commencer

Avant de configurer et d'utiliser les notifications Pub/Sub, suivez les étapes décrites dans les sections suivantes:

Examiner le quota Pub/Sub

Familiarisez-vous avec les quotas et limites de 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:

Activer l'API

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 sujet, consultez Créer un sujet.

Un datastore individuel peut avoir son propre sujet Pub/Sub ou plusieurs datastores peuvent partager le même sujet.

Utilisez le format suivant pour spécifier le sujet Pub/Sub:

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID est l'ID de votre projet Google Cloud et TOPIC_NAME le 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 datastore FHIR

Créez ou modifiez un magasin FHIR avec un objet FhirNotificationConfig configuré.

Les exemples suivants montrent comment modifier un datastore FHIR existant. Les champs sendFullResource et sendPreviousResourceOnDelete sont définis sur true, ce qui signifie que les notifications contiennent le contenu complet de la ressource FHIR lorsqu'une ressource est créée, mise à jour, corrigée ou supprimée.

{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}

cat > request.json << 'EOF'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}
EOF

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"

@'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "R4",
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}

Créer une ressource FHIR

Créez une ressource FHIR dans le magasin FHIR. La requête déclenche la publication d'un message par l'API Cloud Healthcare 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é à la création d'une ressource Patient dans un magasin FHIR.

Dans l'exemple de sortie, le contenu de la ressource FHIR se trouve dans une chaîne encodée en base64 dans le 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 permettant de décoder le texte base64.

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"

$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

{
  "receivedMessages": [
    {
      "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
      "message": {
        "data": "wogICJiaXJ0aERhdGUiOiAiMTk3MC0wMS0wMSIsCiAgImdlbmRlciI6ICJmZW1hbGUiLAogICJpZCI6ICIyYmMwODg4Yi00MGRmLTQwYzctOWRhYi0wMzc4YTFiZWE0MGIiLAogICJtZXRhIjogewogICAgImxhc3RVcGRhdGVkIjogIjIwMjMtMDUtMDJUMjA6NDc6MTkuMjk2MjEwKzAwOjAwIiwKICAgICJ2ZXJzaW9uSWQiOiAiTVRZNE16QTJNRFF6T1RJNU5qSXhNREF3TUEiCiAgfSwKICAibmFtZSI6IFsKICAgIHsKICAgICAgImZhbWlseSI6ICJTbWl0aCIsCiAgICAgICJnaXZlbiI6IFsKICAgICAgICAiRGFyY3kiCiAgICAgIF0sCiAgICAgICJ1c2UiOiAib2ZmaWNpYWwiCiAgICB9CiAgXSwKICAicmVzb3VyY2VUeXBlIjogIlBhdGllbnQiCn0=",
        "attributes": {
          "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
          "action": "CreateResource",
          "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA",
          "resourceType": "Patient",
          "lastUpdatedTime": "Mon, 01 Jan 2020 00:00:00 UTC",
          "payloadType": "FullResource"
        },
        "messageId": "7586159156345265",
        "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
      }
    }
  ]
}

gcloud pubsub subscriptions pull \
    projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID \
    --auto-ack \
    --format=json

gcloud pubsub subscriptions pull `
    projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID `
    --auto-ack `
    --format=json

gcloud pubsub subscriptions pull ^
    projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ^
    --auto-ack ^
    --format=json

[
  {
    "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 important

Si la taille d'une ressource FHIR est trop importante ou si les serveurs de l'API Cloud Healthcare enregistrent un trafic important, le champ attributes ne peut contenir que le nom de la ressource au lieu de 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 à l'affichage de la notification. Si payloadType est défini sur nameOnly, le champ attributes n'a pas entièrement renseigné les données de ressource FHIR. Vous devez ensuite obtenir manuellement le contenu de la ressource FHIR à partir du magasin 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 dépassant 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:

Étape suivante

• Utilisez la gestion du débit pour gérer les pics de trafic de messages Pub/Sub temporaires.
• Gérez les échecs de message.
• Rouvrez et supprimez définitivement les messages.
• Consultez la présentation de l'architecture de Pub/Sub.