Evite conflitos de recursos FHIR através de ETags

Esta página explica como usar etiquetas de entidades (ETags) para gestão de concorrência com recursos FHIR na Cloud Healthcare API. As ETags ajudam a evitar a perda de dados e a melhorar o desempenho das aplicações ao ativar o controlo de simultaneidade otimista e o armazenamento em cache do lado do cliente.

Compreenda as ETags

Uma ETag funciona como um identificador exclusivo para o estado atual de um recurso FHIR no servidor, semelhante a um número de versão. Sempre que um recurso FHIR é criado ou modificado, é gerado um novo valor ETag.

Pode usar ETags para garantir a integridade dos dados e otimizar o desempenho nas seguintes situações:

  • Para garantir o controlo de concorrência otimista: quando inclui um ETag num pedido para modificar um recurso FHIR, a Cloud Healthcare API verifica se o ETag corresponde à versão mais recente do recurso FHIR no servidor. Isto ajuda a evitar que um cliente substitua acidentalmente as alterações feitas por outro cliente, também denominado conflito de escrita ou "problema de atualização perdida".

  • Envio de pedidos condicionais: as ETags permitem que os clientes enviem pedidos condicionalmente apenas quando forem cumpridas condições específicas. Isto otimiza a obtenção de dados e reduz o tráfego de rede desnecessário. Por exemplo, pode enviar pedidos condicionais através dos seguintes cabeçalhos HTTP:

    • If-Match: o pedido só é bem-sucedido se o ETag fornecido corresponder ao ETag atual no servidor. Isto garante que está a atualizar a versão esperada do recurso FHIR.
    • If-None-Match: o pedido só é bem-sucedido se o ETag fornecido não corresponder ao ETag atual no servidor. Isto permite-lhe saber se a versão em cache local de um recurso ainda está atualizada, reduzindo a necessidade de obter o recurso completo do servidor sempre. Isto é usado frequentemente para o armazenamento em cache eficiente.

As ETags FHIR usam a validação fraca, o que significa que podem não ser idênticas em diferentes instâncias do servidor, mas continuam a monitorizar eficazmente as alterações aos recursos.

Obtenha um ETag

Os exemplos seguintes mostram como obter o ETag de um recurso FHIR.

O ETag está incluído no cabeçalho de resposta HTTP completo quando obtém o conteúdo de um recurso FHIR. O ETag corresponde ao Meta.versionId no recurso FHIR.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do FHIR store
  • FHIR_STORE_ID: o ID da loja FHIR
  • FHIR_RESOURCE_TYPE: o tipo de recurso FHIR
  • FHIR_RESOURCE_ID: o ID do recurso FHIR

curl

Use o método fhir.read. A flag -verbose devolve os cabeçalhos HTTP na resposta, que contêm a ETag.

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"

A resposta contém o seguinte:

< etag: W/"ETAG_VALUE"

PowerShell

Use o método fhir.read. A flag -Headers devolve os cabeçalhos HTTP na resposta, que contêm o ETag.

$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

A resposta contém o seguinte:

ETag                   {W/"ETAG_VALUE"}

Faça a gestão da simultaneidade ao atualizar um recurso FHIR

Os exemplos seguintes mostram como incluir uma ETag ao atualizar um recurso FHIR.

Os exemplos usam If-Match, que tem o seguinte comportamento:

  • Se a ETag corresponder à ETag atual do recurso FHIR no servidor, a atualização é bem-sucedida e o servidor gera uma nova ETag para o recurso atualizado. Isto garante que está a atualizar a versão esperada do recurso FHIR.

  • Se a ETag não corresponder, a atualização falha com um erro 412 Precondition Failed, o que indica que outro cliente modificou o recurso desde que a ETag original foi obtida. Isto evita a perda de dados devido a substituições acidentais.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • ETAG_VALUE: o valor ETag do recurso FHIR
  • PROJECT_ID: o ID do seu Google Cloud projeto
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do FHIR store
  • FHIR_STORE_ID: o ID da loja FHIR
  • FHIR_RESOURCE_TYPE: o tipo de recurso FHIR
  • FHIR_RESOURCE_ID: o ID do recurso FHIR

curl

Use o método fhir.update.

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"

A resposta contém o recurso FHIR atualizado.

PowerShell

Use o método fhir.update.

$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

A resposta contém o recurso FHIR atualizado.

Implemente o armazenamento em cache do lado do cliente

Pode usar ETags para implementar o armazenamento em cache do lado do cliente, o que acelera a obtenção de dados e contribui para uma experiência do utilizador mais fluida e dinâmica.

Para obter um recurso FHIR previamente colocado em cache, pode incluir o ETag em cache no cabeçalho If-None-Match, que tem o seguinte comportamento:

  • Se as ETags corresponderem, o servidor responde com 304 Not Modified e o cliente usa a respetiva cópia em cache. Isto poupa largura de banda e reduz a carga do servidor.

  • Se as ETags não corresponderem, o servidor envia o recurso FHIR atualizado e a respetiva nova ETag, o que permite ao cliente atualizar a cache.

Os exemplos seguintes mostram como obter o conteúdo de um recurso FHIR usando um ETag que corresponda ao ETag no servidor.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • ETAG_VALUE: o valor ETag do recurso FHIR
  • PROJECT_ID: o ID do seu Google Cloud projeto
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do FHIR store
  • FHIR_STORE_ID: o ID da loja FHIR
  • FHIR_RESOURCE_TYPE: o tipo de recurso FHIR
  • FHIR_RESOURCE_ID: o ID do recurso FHIR

curl

Use o método fhir.read. A flag -verbose devolve os cabeçalhos HTTP na resposta. Caso contrário, não é devolvida nenhuma resposta.

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"

A resposta contém um código de estado 304 Not Modified.

PowerShell

Use o método fhir.read. A flag -Headers devolve os cabeçalhos HTTP na resposta. Caso contrário, não é devolvida nenhuma resposta.

$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

A resposta contém um código de estado 304 Not Modified.