FHIR-Ressourcenkonflikte mithilfe von ETags verhindern

Auf dieser Seite wird erläutert, wie Sie Entitätstags (ETags) für die Verwaltung von Parallelität mit FHIR-Ressourcen in der Cloud Healthcare API verwenden. ETags tragen dazu bei, Datenverlust zu verhindern und die Anwendungsleistung zu verbessern, indem sie optimistische Nebenläufigkeitserkennung und clientseitiges Caching ermöglichen.

ETags verstehen

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

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

• So wird die optimistische Parallelitätssteuerung gewährleistet: Wenn Sie ein ETag in eine Anfrage zum Ändern einer FHIR-Ressource einfügen, 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 Schreib-Schreib-Konflikt oder Problem des verlorenen Updates bezeichnet.

• Bedingte Anfragen senden: Mit ETags können Clients Anfragen nur dann bedingt senden, wenn bestimmte Bedingungen erfüllt sind. Dadurch wird der Datenabruf optimiert und unnötiger Netzwerkverkehr reduziert. Sie können beispielsweise bedingte Anfragen mit den folgenden HTTP-Headern senden:

  • If-Match: Die Anfrage ist nur 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 erfolgreich, wenn das angegebene ETag nicht mit dem aktuellen ETag auf dem Server übereinstimmt. So können Sie feststellen, ob Ihre lokal im Cache gespeicherte Version einer Ressource noch aktuell ist. Dadurch muss die vollständige Ressource nicht jedes Mal vom Server abgerufen werden. Dies wird häufig für effizientes Caching verwendet.

FHIR-ETags verwenden die schwache Validierung. Das bedeutet, dass sie auf verschiedenen Serverinstanzen möglicherweise nicht identisch sind, aber dennoch Ressourcenänderungen effektiv nachverfolgen.

ETag abrufen

Die folgenden Beispiele zeigen, wie Sie das ETag einer FHIR-Ressource abrufen.

Der ETag ist im vollständigen HTTP-Antwort-Header 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

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"

< etag: W/"ETAG_VALUE"

$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

ETag                   {W/"ETAG_VALUE"}

Nebenläufigkeit beim Aktualisieren einer FHIR-Ressource verwalten

Die folgenden Beispiele zeigen, wie Sie beim Aktualisieren einer FHIR-Ressource ein ETag einfügen.

In den Beispielen wird If-Match verwendet, das sich so verhält:

• 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. Das bedeutet, dass ein anderer Client die Ressource seit dem Abrufen des ursprünglichen ETag geändert hat. So wird Datenverlust durch versehentliches Überschreiben verhindert.

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

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"

$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

Clientseitiges Caching implementieren

Mit ETags können Sie clientseitiges Caching implementieren, wodurch der Datenabruf beschleunigt und die Nutzerfreundlichkeit verbessert wird.

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

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

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

Die folgenden Beispiele zeigen, 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

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"

$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