FHIR-Ressourcenkonflikte mithilfe von ETags verhindern

Auf dieser Seite wird erläutert, wie Sie Entitäts-Tags (ETags) zur Parallelitätsverwaltung mit FHIR-Ressourcen in der Cloud Healthcare API verwenden. ETags tragen dazu bei, Datenverluste zu vermeiden und die Anwendungsleistung zu verbessern, indem sie die optimistische Nebenläufigkeitssteuerung und das clientseitige Caching ermöglichen.

ETags

Ein ETag dient als eindeutige Kennung für den aktuellen Status einer FHIR-Ressource auf dem Server, ähnlich wie eine Versionsnummer. Jedes Mal, wenn eine FHIR-Ressource erstellt oder geändert wird, wird ein neuer ETag-Wert generiert.

Sie können ETags in den folgenden Fällen verwenden, um die Datenintegrität zu gewährleisten und die Leistung zu optimieren:

• Optimistische Concurrent Control: Wenn Sie eine Anfrage zum Ändern einer FHIR-Ressource mit einem ETag senden, prüft die Cloud Healthcare API, ob das ETag mit der neuesten Version der FHIR-Ressource auf dem Server übereinstimmt. So wird verhindert, dass ein Client versehentlich Änderungen überschreibt, die von einem anderen Client vorgenommen wurden. Dies wird auch als Write-Write-Konflikt oder Lost-Update-Problem bezeichnet.

• Senden bedingter Anfragen: Mit ETags können Clients Anfragen nur dann bedingt senden, wenn bestimmte Bedingungen erfüllt sind. Dadurch wird die Datenabfrage optimiert und unnötiger Netzwerkverkehr reduziert. Sie können beispielsweise mithilfe der folgenden HTTP-Header bedingte Anfragen senden:

  • If-Match: Die Anfrage ist nur dann erfolgreich, wenn das angegebene ETag mit dem aktuellen ETag auf dem Server übereinstimmt. So wird sichergestellt, dass Sie die erwartete Version der FHIR-Ressource aktualisieren.
  • If-None-Match: Die Anfrage ist nur dann erfolgreich, wenn das angegebene ETag nicht mit dem aktuellen ETag auf dem Server übereinstimmt. So können Sie feststellen, ob die lokal im Cache gespeicherte Version einer Ressource noch aktuell ist. Dadurch muss nicht jedes Mal die vollständige Ressource vom Server abgerufen werden. Diese Methode wird häufig für effizientes Caching verwendet.

FHIR-ETags verwenden eine schwache Validierung. Das bedeutet, dass sie möglicherweise nicht für verschiedene Serverinstanzen identisch sind, aber dennoch effektiv Ressourcenänderungen nachverfolgen.

ETag abrufen

In den folgenden Beispielen wird gezeigt, wie Sie das ETag einer FHIR-Ressource abrufen.

Der ETag ist im vollständigen HTTP-Antwortheader enthalten, wenn Sie den Inhalt einer FHIR-Ressource abrufen. Das ETag stimmt mit dem Meta.versionId in der FHIR-Ressource überein.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• PROJECT_ID: die ID Ihres Google Cloud Projekts
• LOCATION ist der Standort des Datasets
• DATASET_ID: das übergeordnete Dataset des FHIR-Speichers
• FHIR_STORE_ID: die FHIR-Speicher-ID
• FHIR_RESOURCE_TYPE ist der FHIR-Ressourcentyp
• FHIR_RESOURCE_ID: die FHIR-Ressourcen-ID

Erforderliche Berechtigungen für diese Aufgabe

Zum Ausführen dieser Aufgabe benötigen Sie die folgenden Berechtigungen oder die folgenden IAM-Rollen (Identity and Access Management):

Berechtigungen

• healthcare.fhirResources.get

Rollen

• Healthcare-FHIR-Ressourcen-Leser (roles/healthcare.fhirResourceReader)

Sie können Ihren Administrator bitten, Ihnen diese IAM-Rollen (Identity and Access Management) zu gewähren. Eine Anleitung zum Zuweisen von Rollen finden Sie unter Zugriff verwalten oder Zugriff auf Cloud Healthcare API-Ressourcen steuern. Möglicherweise können Sie die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Hinweis: Wenn Sie für diesen Leitfaden ein Google Cloud Projekt erstellt haben, wird Ihnen als Projektersteller automatisch die IAM-Rolle „Inhaber“ (roles/owner) mit den erforderlichen Berechtigungen zugewiesen. Sie benötigen keine zusätzlichen IAM-Rollen.

curl

Verwenden Sie die Methode fhir.read. Das Flag -verbose gibt die HTTP-Header in der Antwort zurück, die das ETag enthalten.

curl -X GET \
    -verbose \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

Die Antwort enthält Folgendes:

< etag: W/"ETAG_VALUE"

PowerShell

Verwenden Sie die Methode fhir.read. Das Flag -Headers gibt die HTTP-Header in der Antwort zurück, die das ETag enthalten.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Headers

Die Antwort enthält Folgendes:

ETag                   {W/"ETAG_VALUE"}

Gleichzeitigkeit beim Aktualisieren einer FHIR-Ressource verwalten

In den folgenden Beispielen wird gezeigt, wie Sie beim Aktualisieren einer FHIR-Ressource ein ETag angeben.

In den Beispielen wird If-Match verwendet. Dabei gilt Folgendes:

• Wenn das ETag mit dem aktuellen ETag der FHIR-Ressource auf dem Server übereinstimmt, ist die Aktualisierung erfolgreich und der Server generiert ein neues ETag für die aktualisierte Ressource. So wird sichergestellt, dass Sie die erwartete Version der FHIR-Ressource aktualisieren.

• Wenn das ETag nicht übereinstimmt, schlägt die Aktualisierung mit dem Fehler 412 Precondition Failed fehl. Dies bedeutet, dass ein anderer Client die Ressource seit dem Abrufen des ursprünglichen ETags geändert hat. So wird verhindert, dass Daten durch versehentliches Überschreiben verloren gehen.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• ETAG_VALUE: der ETag-Wert der FHIR-Ressource
• PROJECT_ID: die ID Ihres Google Cloud Projekts
• LOCATION ist der Standort des Datasets
• DATASET_ID: das übergeordnete Dataset des FHIR-Speichers
• FHIR_STORE_ID: die FHIR-Speicher-ID
• FHIR_RESOURCE_TYPE ist der FHIR-Ressourcentyp
• FHIR_RESOURCE_ID: die FHIR-Ressourcen-ID

Erforderliche Berechtigungen für diese Aufgabe

Zum Ausführen dieser Aufgabe benötigen Sie die folgenden Berechtigungen oder die folgenden IAM-Rollen (Identity and Access Management):

Berechtigungen

• healthcare.fhirResources.update

Rollen

• Healthcare-FHIR-Ressourcen-Bearbeiter (roles/healthcare.fhirResourceEditor)

Sie können Ihren Administrator bitten, Ihnen diese IAM-Rollen (Identity and Access Management) zu gewähren. Eine Anleitung zum Zuweisen von Rollen finden Sie unter Zugriff verwalten oder Zugriff auf Cloud Healthcare API-Ressourcen steuern. Möglicherweise können Sie die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Hinweis: Wenn Sie für diesen Leitfaden ein Google Cloud Projekt erstellt haben, wird Ihnen als Projektersteller automatisch die IAM-Rolle „Inhaber“ (roles/owner) mit den erforderlichen Berechtigungen zugewiesen. Sie benötigen keine zusätzlichen IAM-Rollen.

curl

Verwenden Sie die Methode fhir.update.

Wichtig: Das Beispiel enthält das Flag -d @request.json. Sie benötigen eine gültige request.json-Datei im aktuellen Verzeichnis, um das Beispiel ausführen zu können. Beispiele für die Inhalte einer request.json-Datei finden Sie unter FHIR-Ressource aktualisieren.

curl -X PUT \
    -H "If-Match: W/\"ETAG_VALUE\"" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -d @request.json \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

Die Antwort enthält die aktualisierte FHIR-Ressource.

PowerShell

Verwenden Sie die Methode fhir.update.

Wichtig: Das Beispiel enthält ein -Infile request.json-Flag. Sie benötigen eine gültige request.json-Datei im aktuellen Verzeichnis, um das Beispiel ausführen zu können. Beispiele für die Inhalte einer request.json-Datei finden Sie unter FHIR-Ressource aktualisieren.

$cred = gcloud auth print-access-token
$etag = W/\"ETAG_VALUE\""
$headers = @{
  "Authorization" = "Bearer $cred"
  "If-Match"      = "$etag"}

Invoke-WebRequest `
    -Method PUT `
    -Headers $headers `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Content

Die Antwort enthält die aktualisierte FHIR-Ressource.

Clientseitiges Caching implementieren

Mit ETags können Sie clientseitiges Caching implementieren, was das Abrufen von Daten beschleunigt und zu einer reibungsloseren, reaktionsschnelleren Nutzererfahrung beiträgt.

Wenn Sie eine zuvor im Cache gespeicherte FHIR-Ressource abrufen möchten, können Sie das im Cache gespeicherte ETag in den Header If-None-Match einfügen. Dabei gilt Folgendes:

• Wenn die ETags übereinstimmen, antwortet der Server mit 304 Not Modified und der Client verwendet die im Cache gespeicherte Kopie. So wird die Bandbreite gespart und die Serverlast reduziert.

• Wenn die ETags nicht übereinstimmen, sendet der Server die aktualisierte FHIR-Ressource und ihr neues ETag, damit der Client seinen Cache aktualisieren kann.

In den folgenden Beispielen wird gezeigt, wie der Inhalt einer FHIR-Ressource mit einem ETag abgerufen wird, das mit dem ETag auf dem Server übereinstimmt.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• ETAG_VALUE: der ETag-Wert der FHIR-Ressource
• PROJECT_ID: die ID Ihres Google Cloud Projekts
• LOCATION ist der Standort des Datasets
• DATASET_ID: das übergeordnete Dataset des FHIR-Speichers
• FHIR_STORE_ID: die FHIR-Speicher-ID
• FHIR_RESOURCE_TYPE ist der FHIR-Ressourcentyp
• FHIR_RESOURCE_ID: die FHIR-Ressourcen-ID

Erforderliche Berechtigungen für diese Aufgabe

Zum Ausführen dieser Aufgabe benötigen Sie die folgenden Berechtigungen oder die folgenden IAM-Rollen (Identity and Access Management):

Berechtigungen

• healthcare.fhirResources.get

Rollen

• Healthcare-FHIR-Ressourcen-Leser (roles/healthcare.fhirResourceReader)

Sie können Ihren Administrator bitten, Ihnen diese IAM-Rollen (Identity and Access Management) zu gewähren. Eine Anleitung zum Zuweisen von Rollen finden Sie unter Zugriff verwalten oder Zugriff auf Cloud Healthcare API-Ressourcen steuern. Möglicherweise können Sie die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Hinweis: Wenn Sie für diesen Leitfaden ein Google Cloud Projekt erstellt haben, wird Ihnen als Projektersteller automatisch die IAM-Rolle „Inhaber“ (roles/owner) mit den erforderlichen Berechtigungen zugewiesen. Sie benötigen keine zusätzlichen IAM-Rollen.

curl

Verwenden Sie die Methode fhir.read. Mit dem Flag -verbose werden die HTTP-Header in der Antwort zurückgegeben, andernfalls wird keine Antwort zurückgegeben.

curl -X GET \
    -H "If-None-Match: W/\"ETAG_VALUE\"" \
    -v \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

Die Antwort enthält den Statuscode 304 Not Modified.

PowerShell

Verwenden Sie die Methode fhir.read. Wenn das Flag -Headers gesetzt ist, werden die HTTP-Header in der Antwort zurückgegeben. Andernfalls wird keine Antwort zurückgegeben.

$cred = gcloud auth print-access-token
$etag = W/\"ETAG_VALUE\""
$headers = @{
"Authorization" = "Bearer $cred"
  "If-None-Match"      = "$etag"}

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Headers

Die Antwort enthält den Statuscode 304 Not Modified.