Questa pagina spiega come utilizzare Pub/Sub per ricevere notifiche quando si verifica un evento clinico in un datastore FHIR.
Puoi utilizzare le notifiche Pub/Sub per più casi d'uso, tra cui l'attivazione dell'elaborazione o dell'analisi downstream di nuovi dati. Ad esempio, un modello di machine learning può ricevere notifiche quando nuovi dati sono disponibili per l'addestramento e generare approfondimenti o previsioni per migliorare l'assistenza ai pazienti.
Panoramica
Puoi ricevere notifiche Pub/Sub quando una risorsa FHIR viene creata, aggiornata, sottoposta a patch o eliminata in un datastore 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 una sottoscrizione Pub/Sub, quindi configurare l'archivio FHIR per inviare notifiche all'argomento.
Il seguente diagramma mostra come vengono create e inviate le notifiche Pub/Sub quando viene creata una risorsa FHIR in un datastore 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 datastore FHIR.
La figura 1 illustra i seguenti passaggi:
- Un chiamante effettua una richiesta
fhirStores.fhir.create
per creare una risorsa FHIR. - Il datastore FHIR riceve la richiesta, crea un messaggio Pub/Sub e lo invia all'argomento Pub/Sub configurato nell'archivio FHIR.
- Pub/Sub inoltra il messaggio alle sottoscrizioni collegate all'argomento.
- I sottoscrittori ricevono una notifica, sotto forma di messaggio Pub/Sub, dalla sottoscrizione. 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
su un datastore FHIR. Per ogni datastore FHIR è possibile configurare un FhirNotificationConfig
.
La tabella seguente descrive i campi nell'oggetto FhirNotificationConfig
.
Campo | Descrizione | Esempio |
---|---|---|
pubsubTopic |
L'argomento Pub/Sub da collegare al datastore FHIR. Le notifiche vengono inviate all'argomento specificato. | projects/my-project/topics/my-topic |
sendFullResource |
Indica se includere i contenuti completi di una risorsa FHIR creata, aggiornata o con patch in una notifica. Questo campo non ha effetto sulle notifiche inviate quando vengono eliminate le risorse FHIR. Per includere i contenuti completi di una risorsa eliminata, imposta sendPreviousResourceOnDelete su true . |
true |
sendPreviousResourceOnDelete |
Indica se includere i contenuti completi di una risorsa FHIR eliminata in una notifica. Questo campo non ha effetto sulle notifiche inviate quando le risorse FHIR vengono create, aggiornate o applicate con patch. | true |
Formato e contenuti delle notifiche
Ogni notifica Pub/Sub contiene un oggetto message
contenente informazioni sull'evento clinico. L'oggetto message
è 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, vedi ReceivedMessage
e PubsubMessage
.
La tabella seguente descrive ogni campo nell'oggetto attributes
:
Attributo | Descrizione | Esempio |
---|---|---|
action |
L'azione che si è verificata su una risorsa FHIR. I valori possibili sono:
|
CreateResource |
resourceType |
Il tipo di risorsa FHIR che è stato modificato. I valori possibili includono qualsiasi tipo di risorsa FHIR supportato nell'API Cloud Healthcare. | Patient |
payloadType |
Il tipo di payload del messaggio, uno tra NameOnly o FullResource . |
FullResource |
storeName |
Il nome completo della risorsa del datastore FHIR in cui si è verificata l'azione. | projects/my-project/locations/us/datasets/my-dataset/fhirStores/my-fhir-store |
lastUpdatedTime |
Un timestamp dell'ultima modifica della risorsa FHIR. Il timestamp utilizza il formato RFC 1123. | Mon, 01 Jan 2020 00:00:00 UTC |
versionId |
L'ID della versione più recente della risorsa FHIR in cui si è verificata l'azione. Per ulteriori informazioni sugli ID versione, consulta l'elenco delle versioni delle risorse FHIR. | MTY4MzA2MDQzOTI5NjIxMDAwMA |
La tabella seguente descrive i campi rimanenti nell'oggetto message
:
Campo | Descrizione | Esempio |
---|---|---|
data |
Una stringa con codifica Base64 del nome della risorsa FHIR o dei contenuti della risorsa FHIR, a seconda dei valori specificati in FhirNotificationConfig . |
|
messageId |
Identificatore del messaggio Pub/Sub. | |
publishTime |
L'ora in cui il server Pub/Sub ha pubblicato il messaggio. |
Specifica le informazioni da includere nelle notifiche
Le notifiche Pub/Sub, come descritto in dettaglio in Formato e contenuto 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 sono archiviate nel campo data
come stringa con codifica Base64.
Se includi l'intero contenuto di una risorsa FHIR, non devi eseguire separatamente query su Pub/Sub e sull'API Cloud Healthcare per i dettagli delle risorse.
recupera il nome della risorsa FHIR
Per includere solo il nome di una risorsa FHIR quando crei, aggiorni o applichi la patch alla risorsa, 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
è 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 suNameOnly
per indicare quanto segue in merito alla richiesta:- Per le operazioni di creazione, aggiornamento e applicazione di patch,
sendFullResource
è impostato sufalse
. - Per le operazioni di eliminazione, il campo
sendPreviousResourceOnDelete
è impostato sufalse
.
- Per le operazioni di creazione, aggiornamento e applicazione di patch,
Solo il nome della risorsa FHIR è incluso nel campo
data
. Il nome è codificato come stringa con codifica Base64.
Ottieni contenuti delle risorse FHIR creati, aggiornati o con patch
Per includere l'intero contenuto di una risorsa FHIR quando crei, aggiorni o applichi la patch alla risorsa, 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 equivale a quando recuperi solo il
nome della risorsa FHIR. Per includere i contenuti delle risorse FHIR quando viene eliminata una risorsa FHIR, consulta Recupero dei contenuti eliminati delle risorse FHIR.
Quando visualizzi la notifica, l'oggetto message
è 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 suFullResource
per indicare chesendFullResource
è impostato sutrue
. L'intero contenuto della risorsa FHIR è incluso nel campodata
come stringa con codifica Base64.- Il campo
data
contiene i contenuti della risorsa FHIR come stringa con codifica Base64.
Ottieni contenuti eliminati delle risorse FHIR
Per includere i contenuti completi di una risorsa FHIR quando la elimini, imposta sendPreviousResourceOnDelete
su true
.
Quando visualizzi la notifica, l'oggetto message
è 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 suFullResource
anche sesendFullResource
è impostato sufalse
.L'intero contenuto della risorsa FHIR è incluso nel campo
data
come stringa con codifica Base64.Il campo
data
contiene i contenuti della risorsa FHIR come stringa con codifica Base64 prima che la risorsa fosse eliminata.
Configura e visualizza le notifiche FHIR
I seguenti esempi mostrano come visualizzare la notifica Pub/Sub generata quando una risorsa FHIR viene creata in un datastore FHIR.
Prima di iniziare
Prima di configurare e utilizzare le notifiche Pub/Sub, completa le seguenti sezioni:
Rivedi quota Pub/Sub
Impara a conoscere le quote e i limiti di Pub/Sub. Per informazioni su come visualizzare e richiedere una quota 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:
Configura le autorizzazioni Pub/Sub
Per consentire la pubblicazione dei messaggi in Pub/Sub dall'API Cloud Healthcare, devi aggiungere il ruolo pubsub.publisher
all'account di servizio dell'agente di servizio Cloud Healthcare del progetto.
Per conoscere la 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, vedi Creare un argomento.
I singoli datastore possono avere il proprio argomento Pub/Sub oppure più datastore possono condividere lo stesso argomento.
Utilizza il formato seguente quando specifichi 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.
crea 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 datastore FHIR
Crea o modifica un datastore FHIR con un oggetto FhirNotificationConfig
configurato.
I seguenti esempi mostrano come modificare un datastore 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.
REST
Per modificare il datastore FHIR, utilizza il metodo projects.locations.datasets.fhirStores.patch
.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: l'ID del tuo progetto Google Cloud
- LOCATION: la posizione del set di dati
- DATASET_ID: il set di dati padre del datastore FHIR
- FHIR_STORE_ID: l'ID datastore FHIR
- PUBSUB_TOPIC_ID: l'ID dell'argomento Pub/Sub
Corpo JSON della richiesta:
{ "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true, "sendPreviousResourceOnDelete": true } ] }
Per inviare la richiesta, scegli una delle seguenti opzioni:
arricciatura
Salva il corpo della richiesta in un file denominato request.json
.
Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:
cat > request.json << 'EOF' { "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true, "sendPreviousResourceOnDelete": true } ] } EOF
Quindi esegui questo comando per inviare la richiesta 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
Salva il corpo della richiesta in un file denominato request.json
.
Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:
@' { "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true, "sendPreviousResourceOnDelete": true } ] } '@ | Out-File -FilePath request.json -Encoding utf8
Quindi esegui questo comando per inviare la richiesta 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
Dovresti ricevere una risposta JSON simile alla seguente:
Crea una risorsa FHIR
Crea una risorsa FHIR nel datastore FHIR. A seguito della richiesta, l'API Cloud Healthcare pubblica un messaggio nell'argomento Pub/Sub configurato.
Visualizzare la notifica Pub/Sub
Visualizzare il messaggio pubblicato nell'argomento Pub/Sub. Il seguente messaggio è stato generato quando è stata creata una risorsa Patient in un datastore FHIR.
Nell'output di esempio, i contenuti della risorsa FHIR sono in una stringa con codifica Base64 nel campo data
. Devi decodificare il valore con codifica Base64 per ottenere i contenuti.
La maggior parte delle piattaforme e dei sistemi operativi dispone di strumenti per la decodifica del testo base64.
REST
Per visualizzare il messaggio pubblicato nell'argomento Pub/Sub, utilizza il metodo projects.subscriptions.pull
. L'esempio seguente utilizza il parametro di query ?maxMessages=10
per specificare il numero massimo di messaggi da restituire nella richiesta. Puoi modificare il valore in base alle tue esigenze.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: l'ID del tuo progetto Google Cloud
- PUBSUB_SUBSCRIPTION_ID: l'ID della sottoscrizione collegata all'argomento Pub/Sub configurato nell'archivio FHIR
Per inviare la richiesta, scegli una delle seguenti opzioni:
arricciatura
Esegui questo comando:
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
Esegui questo comando:
$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
Dovresti ricevere una risposta JSON simile alla seguente:
gcloud
Per visualizzare il messaggio pubblicato nell'argomento Pub/Sub, esegui il comando gcloud pubsub subscriptions pull
.
L'esempio utilizza i seguenti flag di Google Cloud CLI:
--format=json
: visualizza l'output come JSON.--auto-ack
: conferma automaticamente ogni messaggio pull.
Prima di utilizzare uno qualsiasi dei dati di comando riportati di seguito, effettua le seguenti sostituzioni:
- PROJECT_ID: l'ID del tuo progetto Google Cloud
- PUBSUB_SUBSCRIPTION_ID: l'ID della sottoscrizione collegata all'argomento Pub/Sub configurato nell'archivio FHIR
Esegui questo comando:
Linux, macOS o 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
Dovresti ricevere una risposta simile alla seguente:
[ { "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 se i server dell'API Cloud Healthcare registrano un traffico elevato, il campo attributes
potrebbe contenere solo il nome della risorsa anziché l'intero contenuto 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 dalla visualizzazione della notifica.
Se payloadType
è impostato su nameOnly
, il campo attributes
non ha completato completamente i dati delle risorse FHIR. Devi quindi recuperare manualmente i contenuti della risorsa FHIR dal datastore FHIR anziché dal messaggio Pub/Sub.
Criterio di archiviazione dei messaggi Pub/Sub e API Cloud Healthcare
Per assicurarti che i dati dell'API Cloud Healthcare e i dati associati nei messaggi Pub/Sub risiedano nella stessa regione, devi impostare un criterio di archiviazione dei messaggi di Pub/Sub.
Devi impostare esplicitamente il criterio di archiviazione dei messaggi nell'argomento Pub/Sub configurato nel datastore per assicurarti che i dati rimangano nella stessa regione. Ad esempio, se il set di dati dell'API Cloud Healthcare e il datastore FHIR 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, vedi Configurazione dei criteri dell'archivio messaggi.
Risolvere i problemi relativi ai messaggi Pub/Sub non ricevuti
Se non è possibile pubblicare una notifica in Pub/Sub, viene registrato un errore in Cloud Logging. Per maggiori informazioni, consulta Visualizzazione dei log degli errori in Cloud Logging.
Se la percentuale di generazione degli errori supera un limite, gli errori che superano il limite non vengono inviati a Cloud Logging.
Visualizza 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 insieme di coppie chiave-valore viene sempre incluso nel campo attributes
del messaggio:
Nome dell'attributo | Valori possibili | Esempio | Descrizione |
---|---|---|---|
action |
|
CreateResource |
Il tipo di evento che si è verificato. |
resourceType |
Qualsiasi tipo di risorsa FHIR. | Patient |
Il tipo di risorsa modificata. |
Passaggi successivi
- Utilizza il controllo del flusso per gestire i picchi di traffico dei messaggi Pub/Sub temporanei.
- Gestire gli errori relativi ai messaggi.
- Riprodurre di nuovo ed eliminare i messaggi.
- Consulta la panoramica dell'architettura Pub/Sub.