FHIR Pub/Sub-Benachrichtigungen

Auf dieser Seite wird erläutert, wie Sie Pub/Sub verwenden, um Benachrichtigungen zu erhalten, wenn in einem FHIR-Speicher ein klinisches Ereignis auftritt.

Sie können Pub/Sub-Benachrichtigungen für verschiedene Anwendungsfälle verwenden, z. B. um die nachgelagerte Verarbeitung oder Analyse neuer Daten auszulösen. Ein Machine-Learning-Modell kann beispielsweise Benachrichtigungen erhalten, wenn neue Daten für das Training verfügbar sind, und Erkenntnisse oder Vorhersagen generieren, um die Patientenversorgung zu verbessern.

Übersicht

Sie können Pub/Sub-Benachrichtigungen erhalten, wenn eine FHIR-Ressource in einem FHIR-Speicher erstellt, aktualisiert, gepatcht oder gelöscht wird. Die Cloud Healthcare API sendet keine Benachrichtigungen, wenn eine FHIR-Ressource aus Cloud Storage importiert wird.

Damit Sie Benachrichtigungen erhalten, müssen Sie ein Pub/Sub-Thema und ein Abo erstellen und dann den FHIR-Speicher so konfigurieren, dass Benachrichtigungen an das Thema gesendet werden.

Das folgende Diagramm zeigt, wie Pub/Sub-Benachrichtigungen erstellt und zugestellt werden, wenn eine FHIR-Ressource in einem FHIR-Speicher mit der Methode fhir.create erstellt wird. Die Schritte sind dieselben, wenn eine FHIR-Ressource aktualisiert, gepatcht oder gelöscht wird.

Abbildung 1. Pub/Sub-Benachrichtigungen für Änderungen in einem FHIR-Speicher verwenden.

Abbildung 1 zeigt die folgenden Schritte:

1. Ein Aufrufer stellt eine fhirStores.fhir.create-Anfrage zum Erstellen einer FHIR-Ressource.
2. Der FHIR-Speicher empfängt die Anfrage, erstellt eine Pub/Sub-Nachricht und sendet sie an das im FHIR-Speicher konfigurierte Pub/Sub-Thema.
3. Pub/Sub leitet die Nachricht an die Abos weiter, die dem Thema zugeordnet sind.
4. Die Abonnenten erhalten von ihrem Abo eine Benachrichtigung in Form einer Pub/Sub-Nachricht. Jedes Abo kann einen oder mehrere Abonnenten haben, um die Parallelität zu erhöhen.

Benachrichtigungskonfiguration

Sie können Pub/Sub-Benachrichtigungen und ihr Verhalten in einem FhirNotificationConfig-Objekt in einem FHIR-Speicher konfigurieren. Für jeden FHIR-Speicher können mehrere FhirNotificationConfig konfiguriert werden.

In der folgenden Tabelle werden die Felder im FhirNotificationConfig-Objekt beschrieben.

Benachrichtigungsformat und ‑inhalt

Jede Pub/Sub-Benachrichtigung enthält ein message-Objekt mit Informationen zum klinischen Ereignis. Das message-Objekt sieht etwa so aus:

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

Informationen zu zusätzlichen Feldern, die in jeder Pub/Sub-Nachricht enthalten sind, finden Sie unter ReceivedMessage und PubsubMessage.

In der folgenden Tabelle werden die einzelnen Felder des attributes-Objekts beschrieben:

In der folgenden Tabelle werden die verbleibenden Felder im message-Objekt beschrieben:

Informationen angeben, die in Benachrichtigungen enthalten sein sollen

Pub/Sub-Benachrichtigungen, wie in Benachrichtigungsformat und ‑inhalt beschrieben, enthalten einen Standardsatz von Feldern. Sie können entweder die vollständige FHIR-Ressource oder nur ihren Namen in jede Benachrichtigung aufnehmen. Der Ressourcenname enthält den vollständigen Pfad zur Ressource und die Ressourcen-ID in diesem Format:

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

Informationen zu FHIR-Ressourcen werden im Feld data als Base64-codierter String gespeichert.

Wenn Sie den gesamten Inhalt einer FHIR-Ressource einfügen, müssen Sie Pub/Sub und die Cloud Healthcare API nicht separat nach Ressourcendetails abfragen.

FHIR-Ressourcennamen abrufen

Wenn Sie beim Erstellen, Aktualisieren oder Patchen der Ressource nur den Namen einer FHIR-Ressource einfügen möchten, setzen Sie sendFullResource auf false. Wenn Sie beim Löschen einer FHIR-Ressource nur den Namen angeben möchten, legen Sie sendPreviousResourceOnDelete auf false fest.

Wenn Sie die Benachrichtigung aufrufen, sieht das message-Objekt in etwa so aus:

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

Beachten Sie in der Benachrichtigung Folgendes:

• Das Feld payloadType ist auf NameOnly gesetzt, um Folgendes über die Anfrage anzugeben:

  • Bei Erstellungs-, Aktualisierungs- und Patchvorgängen wird sendFullResource auf false gesetzt.
  • Bei Löschvorgängen wird sendPreviousResourceOnDelete auf false gesetzt.

• Nur der Name der FHIR-Ressource ist im Feld data enthalten. Der Name ist als base64-codierter String codiert.

Inhalte von erstellten, aktualisierten oder gepatchten FHIR-Ressourcen abrufen

Wenn Sie den vollständigen Inhalt einer FHIR-Ressource beim Erstellen, Aktualisieren oder Patchen der Ressource einfügen möchten, setzen Sie sendFullResource auf true.

Dieses Verhalten gilt nicht, wenn Sie eine FHIR-Ressource löschen. Wenn Sie eine FHIR-Ressource löschen und sendFullResource auf true, aber sendPreviousResourceOnDelete auf false festgelegt ist, entspricht die Benachrichtigung der Benachrichtigung, die Sie erhalten, wenn Sie nur den FHIR-Ressourcennamen abrufen. Informationen dazu, wie Sie die Inhalte der FHIR-Ressource einbeziehen, wenn eine FHIR-Ressource gelöscht wird, finden Sie unter Gelöschte FHIR-Ressourceninhalte abrufen.

Wenn Sie die Benachrichtigung aufrufen, sieht das message-Objekt in etwa so aus:

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

Beachten Sie in der Benachrichtigung Folgendes:

• payloadType ist auf FullResource gesetzt, um anzugeben, dass sendFullResource auf true gesetzt ist. Der vollständige Inhalt der FHIR-Ressource ist im Feld data als Base64-codierter String enthalten.
• Das Feld data enthält den Inhalt der FHIR-Ressource als base64-codierten String.

Inhalte gelöschter FHIR-Ressourcen abrufen

Wenn Sie beim Löschen einer FHIR-Ressource den vollständigen Inhalt einbeziehen möchten, setzen Sie sendPreviousResourceOnDelete auf true.

Wenn Sie die Benachrichtigung aufrufen, sieht das message-Objekt in etwa so aus:

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

Notieren Sie sich die Werte in den folgenden Feldern:

• payloadType ist auf FullResource gesetzt, auch wenn sendFullResource auf false gesetzt ist.

  Der vollständige Inhalt der FHIR-Ressource ist im Feld data als Base64-codierter String enthalten.

• Das Feld data enthält den Inhalt der FHIR-Ressource als Base64-codierten String, bevor die Ressource gelöscht wurde.

FHIR-Benachrichtigungen konfigurieren und ansehen

Die folgenden Beispiele zeigen, wie Sie die generierte Pub/Sub-Benachrichtigung aufrufen, wenn eine FHIR-Ressource in einem FHIR-Speicher erstellt wird.

Hinweise

Bevor Sie Pub/Sub-Benachrichtigungen konfigurieren und verwenden, sollten Sie die folgenden Abschnitte durcharbeiten:

Pub/Sub-Kontingent prüfen

Machen Sie sich mit den Pub/Sub-Kontingenten und ‑Limits vertraut. Informationen dazu, wie Sie Ihr Kontingent einsehen und ein höheres Kontingent anfordern und was geschieht, wenn Ihr Kontingent aufgebraucht ist, finden Sie unter Mit Kontingenten arbeiten.

Pub/Sub API aktivieren

Aktivieren Sie die Pub/Sub API in der Google Cloud Console:

API aktivieren

Pub/Sub-Berechtigungen konfigurieren

Damit Nachrichten von der Cloud Healthcare API in Pub/Sub veröffentlicht werden können, müssen Sie die Rolle pubsub.publisher zum Dienstkonto Ihres Projekts Cloud Healthcare-Dienst-Agent hinzufügen. Weitere Informationen zum Hinzufügen der erforderlichen Rolle finden Sie unter Pub/Sub-Berechtigungen für DICOM-, FHIR- und HL7v2-Speicher.

Pub/Sub-Thema erstellen

Informationen zum Erstellen eines Themas finden Sie unter Thema erstellen.

Einzelne Datenspeicher können ein eigenes Pub/Sub-Thema haben oder mehrere Datenspeicher können dasselbe Thema gemeinsam nutzen.

Verwenden Sie das folgende Format, wenn Sie das Pub/Sub-Thema angeben:

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID ist Ihre Google Cloud Projekt-ID und TOPIC_NAME der Name des Pub/Sub-Themas.

Pub/Sub-Abo erstellen

Um Nachrichten zu einem Thema zu erhalten, müssen Sie ein Pub/Sub-Abo erstellen. Jedes Pub/Sub-Thema benötigt mindestens ein Pub/Sub-Abo. Durch das Abo wird das Thema mit einer Abonnentenanwendung verbunden, die Nachrichten empfängt und verarbeitet, die für das Thema veröffentlicht wurden.

Informationen zum Erstellen eines Abos und zum Anhängen an ein Pub/Sub-Thema finden Sie unter Abos erstellen.

FHIR-Speicher erstellen oder bearbeiten

Erstellen oder bearbeiten Sie einen FHIR-Speicher mit einem konfigurierten FhirNotificationConfig-Objekt.

In den folgenden Beispielen wird gezeigt, wie Sie einen vorhandenen FHIR-Speicher bearbeiten. Die Felder sendFullResource und sendPreviousResourceOnDelete sind auf true gesetzt. Das bedeutet, dass Benachrichtigungen den vollständigen Inhalt der FHIR-Ressource enthalten, wenn eine Ressource erstellt, aktualisiert, gepatcht oder gelöscht wird.

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

FHIR-Ressource erstellen

Erstellen Sie eine FHIR-Ressource im FHIR-Speicher. Durch die Anfrage wird die Cloud Healthcare API veranlasst, eine Nachricht im konfigurierten Pub/Sub-Thema zu veröffentlichen.

Pub/Sub-Benachrichtigung ansehen

Rufen Sie die im Pub/Sub-Thema veröffentlichte Nachricht auf. Die folgende Nachricht wurde generiert, als eine Patientenressource in einem FHIR-Speicher erstellt wurde.

In der Beispielausgabe befindet sich der Inhalt der FHIR-Ressource in einem base64-codierten String im Feld data. Für den Inhalt müssen Sie den base64-codierten Wert decodieren. Die meisten Plattformen und Betriebssysteme haben Tools zum Decodieren von Base64-Text.

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

Verhalten, wenn eine FHIR-Ressource zu groß oder der Traffic hoch ist

Wenn die Größe einer FHIR-Ressource zu groß ist oder die Cloud Healthcare API-Server stark ausgelastet sind, enthält das Feld attributes möglicherweise nur den Ressourcennamen anstelle des vollständigen Ressourceninhalts. Dieses Verhalten tritt auch auf, wenn sendFullResource und sendPreviousResourceOnDelete auf true gesetzt sind.

Wenn Sie prüfen möchten, ob eine Pub/Sub-Benachrichtigung die vollständige FHIR-Ressource enthält, sehen Sie sich das Feld payloadType in der Antwort an, die beim Aufrufen der Benachrichtigung zurückgegeben wird. Wenn payloadType auf nameOnly gesetzt ist, wurde das Feld attributes nicht vollständig mit den FHIR-Ressourcendaten ausgefüllt. Sie müssen den Inhalt der FHIR-Ressource manuell aus dem FHIR-Speicher abrufen und nicht aus der Pub/Sub-Nachricht.

Cloud Healthcare API und Pub/Sub-Nachrichtenspeicherrichtlinie

Um sicherzustellen, dass sich die Cloud Healthcare API-Daten und die zugehörigen Daten in Pub/Sub-Nachrichten in derselben Region befinden, müssen Sie eine Pub/Sub-Nachrichtenspeicherrichtlinie festlegen.

Sie müssen die Nachrichtenspeicherrichtlinie für das im Datenspeicher konfigurierte Pub/Sub-Thema explizit festlegen, damit die Daten in derselben Region bleiben. Wenn sich Ihr Cloud Healthcare API-Dataset und Ihr FHIR-Speicher beispielsweise in us-central1 befinden, darf die Nachrichtenspeicherrichtlinie nur die Region us-central1 zulassen.

Informationen zum Konfigurieren einer Richtlinie für den Nachrichtenspeicher finden Sie unter Richtlinien für den Nachrichtenspeicher konfigurieren.

Fehlerbehebung bei fehlenden Pub/Sub-Nachrichten

Wenn eine Benachrichtigung nicht in Pub/Sub veröffentlicht werden kann, wird ein Fehler in Cloud Logging in Logs erfasst. Weitere Informationen finden Sie unter Fehlerlogs in Cloud Logging ansehen.

Wenn die Fehlergenerierungsrate ein Limit überschreitet, werden Fehler, die dieses Limit überschreiten, nicht an Cloud Logging gesendet.

FHIR-Benachrichtigungen mit der NotificationConfig-Konfiguration ansehen (eingestellt)

Die Ressource FhirStore enthält ein NotificationConfig-Objekt, in dem Sie ein Pub/Sub-Thema angeben können. Änderungen an FHIR-Ressourcen enthalten im Feld data der Pub/Sub-Nachricht immer die folgende Kennzeichnung:

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

Die folgenden Schlüssel/Wert-Paare sind immer im Feld attributes der Nachricht enthalten:

Nächste Schritte

• Mit der Flusssteuerung vorübergehende Spitzen im Pub/Sub-Nachrichtentraffic bewältigen
• Umgang mit Nachrichtenfehlern
• Nachrichten wiedergeben und dauerhaft löschen
• Architekturübersicht von Pub/Sub