Notifiche Pub/Sub FHIR

Questa pagina spiega come utilizzare Pub/Sub per ricevere notifiche quando si verifica un evento clinico in un archivio FHIR.

Puoi utilizzare le notifiche Pub/Sub per più casi d'uso, ad esempio per attivare l'elaborazione o l'analisi a valle di nuovi dati. Ad esempio, un modello di machine learning può ricevere notifiche quando sono disponibili nuovi dati per l'addestramento e generare approfondimenti o previsioni per migliorare la cura dei pazienti.

Panoramica

Puoi ricevere notifiche Pub/Sub quando una risorsa FHIR viene creata, aggiornata, sottoposta a patch o eliminata in un archivio FHIR. L'API Cloud Healthcare non invia notifiche quando una risorsa FHIR viene importata da Cloud Storage.

Per ricevere le notifiche, devi creare un argomento e un abbonamento Pub/Sub, quindi configurare l'archivio FHIR in modo che invii notifiche all'argomento.

Il seguente diagramma mostra come vengono create e inviate le notifiche Pub/Sub quando viene creata una risorsa FHIR in un archivio FHIR utilizzando il metodo fhir.create. I passaggi sono gli stessi quando una risorsa FHIR viene aggiornata, sottoposta a patch o eliminata.

Figura 1. Utilizzo delle notifiche Pub/Sub per le modifiche in un archivio FHIR.

La figura 1 mostra i seguenti passaggi:

1. Un chiamante invia una richiesta fhirStores.fhir.create per creare una risorsa FHIR.
2. L'archivio FHIR riceve la richiesta, crea un messaggio Pub/Sub e lo invia all'argomento Pub/Sub configurato nell'archivio FHIR.
3. Pub/Sub inoltra il messaggio alle sottoscrizioni associate all'argomento.
4. Gli abbonati ricevono una notifica, sotto forma di messaggio Pub/Sub, dal loro abbonamento. Ogni abbonamento può avere uno o più abbonati per un maggiore parallelismo.

Configurazione delle notifiche

Puoi configurare le notifiche Pub/Sub e il relativo comportamento in un oggetto FhirNotificationConfig in un archivio FHIR. Ogni archivio FHIR può avere un FhirNotificationConfig configurato.

La tabella seguente descrive i campi dell'oggetto FhirNotificationConfig.

Formato e contenuti delle notifiche

Ogni notifica Pub/Sub contiene un oggetto message che contiene informazioni sull'evento clinico. L'oggetto message ha un aspetto simile al seguente:

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

Per informazioni sui campi aggiuntivi inclusi in ogni messaggio Pub/Sub, consulta ReceivedMessage e PubsubMessage.

La tabella seguente descrive ogni campo dell'oggetto attributes:

La tabella seguente descrive i campi rimanenti dell'oggetto message:

Specifica le informazioni da includere nelle notifiche

Le notifiche Pub/Sub, come descritto in Formato e contenuti delle notifiche, includono un insieme standard di campi. In ogni notifica puoi includere la risorsa FHIR completa o solo il suo nome. Il nome della risorsa contiene il percorso completo della risorsa e l'ID risorsa in questo formato:

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID

Le informazioni sulle risorse FHIR vengono memorizzate nel campo data come stringa con codifica base64.

Se includi i contenuti completi di una risorsa FHIR, non devi eseguire query separate su Pub/Sub e sull'API Cloud Healthcare per i dettagli della risorsa.

Ottenere il nome della risorsa FHIR

Per includere solo il nome di una risorsa FHIR quando la crei, la aggiorni o la correggi, imposta sendFullResource su false. Per includere il nome solo quando elimini una risorsa FHIR, imposta sendPreviousResourceOnDelete su false.

Quando visualizzi la notifica, l'oggetto message ha un aspetto simile al seguente:

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

Tieni presente quanto segue nella notifica:

• Il campo payloadType è impostato su NameOnly per indicare quanto segue sulla richiesta:

  • Per le operazioni di creazione, aggiornamento e applicazione di patch, sendFullResource è impostato su false.
  • Per le operazioni di eliminazione, sendPreviousResourceOnDelete è impostato su false.

• Nel campo data è incluso solo il nome della risorsa FHIR. Il nome viene codificato come stringa con codifica base 64.

Crea, aggiorna o applica patch ai contenuti delle risorse FHIR

Per includere i contenuti completi di una risorsa FHIR quando la crei, la aggiorni o la correggi, imposta sendFullResource su true.

Questo comportamento non si applica se elimini una risorsa FHIR. Se elimini una risorsa FHIR e sendFullResource è impostato su true, ma sendPreviousResourceOnDelete è impostato su false, la notifica è la stessa che viene visualizzata quando recuperi solo il nome della risorsa FHIR. Per includere i contenuti della risorsa FHIR quando una risorsa FHIR viene eliminata, consulta Ottenere i contenuti delle risorse FHIR eliminate.

Quando visualizzi la notifica, l'oggetto message ha un aspetto simile al seguente:

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

Tieni presente quanto segue nella notifica:

• payloadType è impostato su FullResource per indicare che sendFullResource è impostato su true. I contenuti completi della risorsa FHIR sono inclusi nel campo data come stringa codificata in base 64.
• Il campo data contiene i contenuti della risorsa FHIR come stringa codificata in base 64.

Recuperare i contenuti delle risorse FHIR eliminate

Per includere i contenuti completi di una risorsa FHIR quando la elimini, imposta sendPreviousResourceOnDelete su true.

Quando visualizzi la notifica, l'oggetto message ha un aspetto simile al seguente:

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

Prendi nota dei valori nei seguenti campi:

• payloadType è impostato su FullResource anche se sendFullResource è impostato su false.

  I contenuti completi della risorsa FHIR sono inclusi nel campo data come stringa codificata in base 64.

• Il campo data contiene i contenuti della risorsa FHIR come stringa codificata in base 64 prima dell'eliminazione della risorsa.

Configurare e visualizzare le notifiche FHIR

Gli esempi riportati di seguito mostrano come visualizzare la notifica Pub/Sub generata quando viene creata una risorsa FHIR in un archivio FHIR.

Prima di iniziare

Prima di configurare e utilizzare le notifiche Pub/Sub, completa le seguenti sezioni:

Controllare la quota di Pub/Sub

Acquisisci familiarità con le quote e i limiti di Pub/Sub. Per informazioni su come visualizzare la quota, richiederne una maggiore e cosa succede se esaurisci la quota, consulta Utilizzo delle quote.

Abilita l'API Pub/Sub

Nella console Google Cloud, abilita l'API Pub/Sub:

Abilitare l'API

Configurare le autorizzazioni Pub/Sub

Per consentire la pubblicazione dei messaggi dall'API Cloud Healthcare in Pub/Sub, devi aggiungere il ruolo pubsub.publisher all'account di servizio dell'agente di servizio Cloud Healthcare del progetto. Per informazioni sulla procedura per aggiungere il ruolo richiesto, consulta Autorizzazioni Pub/Sub per archivi DICOM, FHIR e HL7v2.

crea un argomento Pub/Sub

Per creare un argomento, consulta Creare un argomento.

I singoli datastore possono avere i propri argomenti Pub/Sub oppure più datastore possono condividere lo stesso argomento.

Utilizza il seguente formato per specificare l'argomento Pub/Sub:

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID è l'ID progetto Google Cloud e TOPIC_NAME è il nome dell'argomento Pub/Sub.

Creare una sottoscrizione Pub/Sub

Per ricevere i messaggi pubblicati in un argomento, devi creare una sottoscrizione Pub/Sub. Ogni argomento Pub/Sub richiede almeno una sottoscrizione Pub/Sub. La sottoscrizione collega l'argomento a un'applicazione del sottoscrittore che riceve ed elabora i messaggi pubblicati nell'argomento.

Per creare una sottoscrizione e collegarla a un argomento Pub/Sub, consulta Creare sottoscrizioni.

Crea o modifica un archivio FHIR

Crea o modifica un archivio FHIR con un oggetto FhirNotificationConfig configurato.

Gli esempi riportati di seguito mostrano come modificare un archivio FHIR esistente. I campi sendFullResource e sendPreviousResourceOnDelete sono impostati su true, il che significa che le notifiche contengono i contenuti completi della risorsa FHIR quando una risorsa viene creata, aggiornata, sottoposta a patch o eliminata.

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

Crea una risorsa FHIR

Crea una risorsa FHIR nell'archivio FHIR. La richiesta fa sì che l'API Cloud Healthcare pubblichi un messaggio nell'argomento Pub/Sub configurato.

Visualizza la notifica Pub/Sub

Visualizza il messaggio pubblicato nell'argomento Pub/Sub. Il seguente messaggio è stato generato quando è stata creata una risorsa Patient in un archivio FHIR.

Nell'output di esempio, i contenuti della risorsa FHIR sono in una stringa codificata in base64 nel campo data. Per recuperare i contenuti, devi decodificare il valore con codifica base64. La maggior parte delle piattaforme e dei sistemi operativi dispone di strumenti per decodificare il testo 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"
    }
  }
]

Comportamento quando una risorsa FHIR è troppo grande o il traffico è elevato

Se le dimensioni di una risorsa FHIR sono troppo grandi o i server dell'API Cloud Healthcare registrano un traffico elevato, il campo attributes potrebbe contenere solo il nome della risorsa anziché i contenuti completi della risorsa. Questo comportamento si verifica anche se sendFullResource e sendPreviousResourceOnDelete sono impostati su true.

Per verificare se una notifica Pub/Sub contiene la risorsa FHIR completa, controlla il campo payloadType nella risposta visualizzata dalla notifica. Se payloadType è impostato su nameOnly, il attributes campo non ha completato la compilazione dei dati della risorsa FHIR. Devi quindi recuperare manualmente i contenuti della risorsa FHIR dall'archivio FHIR anziché dal messaggio Pub/Sub.

API Cloud Healthcare e criterio di archiviazione dei messaggi Pub/Sub

Per assicurarti che i dati dell'API Cloud Healthcare e i dati associati nei messaggi Pub/Sub si trovino nella stessa regione, devi impostare un criterio di archiviazione dei messaggi Pub/Sub.

Devi impostare esplicitamente il criterio di archiviazione dei messaggi nell'argomento Pub/Sub configurato nell'datastore per assicurarti che i dati rimangano nella stessa regione. Ad esempio, se il set di dati e l'archivio FHIR dell'API Cloud Healthcare si trovano in us-central1, il criterio di archiviazione dei messaggi deve consentire solo la regione us-central1.

Per configurare un criterio di archiviazione dei messaggi, consulta Configurare i criteri del magazzino dei messaggi.

Risolvere i problemi relativi ai messaggi Pub/Sub persi

Se non è possibile pubblicare una notifica in Pub/Sub, viene registrato un errore in Cloud Logging. Per ulteriori informazioni, consulta Visualizzazione dei log degli errori in Cloud Logging.

Se la frequenza di generazione di errori supera un limite, gli errori in eccesso non vengono inviati a Cloud Logging.

Visualizzare le notifiche FHIR utilizzando la configurazione NotificationConfig (deprecata)

La risorsa FhirStore contiene un oggetto NotificationConfig in cui puoi specificare un argomento Pub/Sub. Le modifiche alle risorse FHIR contengono sempre il seguente identificatore nel campo data del messaggio Pub/Sub:

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID

Il seguente set di coppie chiave:valore viene sempre incluso nel campoattributes del messaggio:

Passaggi successivi

• Utilizza il controllo del flusso per gestire picchi di traffico dei messaggi Pub/Sub temporanei.
• Gestire gli errori relativi ai messaggi.
• Riproduci ed elimina i messaggi.
• Visualizza la panoramica dell'architettura di Pub/Sub.