As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Agrupando recursos do FHIR

Um FHIR Bundle é um contêiner para uma coleção de recursos do FHIR em. AWS HealthLake AWS HealthLake suporta dois tipos de pacotes com diferentes comportamentos de processamento.

Batchos pacotes processam cada recurso de forma independente. Se um recurso falhar, os recursos restantes ainda poderão ser bem-sucedidos. Cada operação é processada individualmente e o processamento continua mesmo quando algumas operações falham. Use pacotes de lotes para operações em massa em que o sucesso parcial seja aceitável, como o upload de vários registros de pacientes não relacionados.

Transactionos pacotes processam todos os recursos atomicamente como uma única unidade. Ou todas as operações de recursos são bem-sucedidas ou não AWS HealthLake comprometem nenhuma delas. Use pacotes de transações quando precisar de integridade referencial garantida em todos os recursos relacionados, como criar um paciente com observações e condições relacionadas em que todos os dados devem ser registrados juntos.

Você pode agrupar recursos de FHIR do mesmo tipo ou de tipos diferentes, e eles podem incluir uma combinação de operações de FHIR, como,create, e. read update delete patch Para obter informações adicionais, consulte Pacote de recursos na documentação do FHIR R4.

Veja a seguir exemplos de casos de uso para cada tipo de pacote.

O exemplo a seguir mostra um pacote de transações com vários tipos de recursos e operações.

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065",
      "resource": {
        "resourceType": "Patient",
        "id": "new-patient",
        "active": true,
        "name": [
          {
            "family": "Johnson",
            "given": [
              "Sarah"
            ]
          }
        ],
        "gender": "female",
        "birthDate": "1985-08-12",
        "telecom": [
          {
            "system": "phone",
            "value": "555-123-4567",
            "use": "home"
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    },
    {
      "fullUrl": "urn:uuid:7f83f473-d8cc-4a8d-86d3-9d9876a3248b",
      "resource": {
        "resourceType": "Observation",
        "id": "blood-pressure",
        "status": "final",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "85354-9",
              "display": "Blood pressure panel"
            }
          ],
          "text": "Blood pressure panel"
        },
        "subject": {
          "reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065"
        },
        "effectiveDateTime": "2023-10-15T09:30:00Z",
        "component": [
          {
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "8480-6",
                  "display": "Systolic blood pressure"
                }
              ]
            },
            "valueQuantity": {
              "value": 120,
              "unit": "mmHg",
              "system": "http://unitsofmeasure.org",
              "code": "mm[Hg]"
            }
          },
          {
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "8462-4",
                  "display": "Diastolic blood pressure"
                }
              ]
            },
            "valueQuantity": {
              "value": 80,
              "unit": "mmHg",
              "system": "http://unitsofmeasure.org",
              "code": "mm[Hg]"
            }
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Observation"
      }
    },
    {
      "resource": {
        "resourceType": "Appointment",
        "id": "appointment-123",
        "status": "booked",
        "description": "Annual physical examination",
        "start": "2023-11-15T09:00:00Z",
        "end": "2023-11-15T09:30:00Z",
        "participant": [
          {
            "actor": {
              "reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065"
            },
            "status": "accepted"
          }
        ]
      },
      "request": {
        "method": "PUT",
        "url": "Appointment/appointment-123"
      }
    },
    {
      "request": {
        "method": "DELETE",
        "url": "MedicationRequest/med-request-456"
      }
    }
  ]
}

Agrupando recursos do FHIR como entidades independentes

Para agrupar recursos do FHIR como entidades independentes

Condicional PUTs em pacotes

AWS HealthLake oferece suporte a atualizações condicionais em pacotes usando os seguintes parâmetros de consulta:

Quando você usa condicional PUTs em pacotes, AWS HealthLake avalia os parâmetros de consulta em relação aos recursos existentes e age com base nos resultados da correspondência.

No exemplo a seguir, pacote com uma atualização condicional, o Patient recurso com FHIR ID é 476 atualizado somente se a condição for atendida. _lastUpdated=lt2025-04-20

{
    "resourceType": "Bundle",
    "id": "bundle-batch",
    "meta": {
        "lastUpdated": "2014-08-18T01:43:30Z"
    },
    "type": "batch",
    "entry": [
        {
            "resource": {
                "resourceType": "Patient",
                "id": "476",
                "meta": {
                    "lastUpdated": "2022-06-03T17:53:36.724Z"
                },
                "active": true,
                "name": [
                    {
                        "use": "official",
                        "family": "Jackson",
                        "given": [
                            "Mateo",
                            "James"
                        ]
                    }
                ],
                "gender": "male",
                "birthDate": "1974-12-25"
            },
            "request": {
                "method": "PUT",
                "url": "Patient?_id=476&_lastUpdated=lt2025-04-20"
            }
        },
        {
            "resource": {
                "resourceType": "Medication",
                "id": "med0310",
                "contained": [
                    {
                        "resourceType": "Substance",
                        "id": "sub03",
                        "code": {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "55452001",
                                    "display": "Oxycodone (substance)"
                                }
                            ]
                        }
                    }
                ],
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "430127000",
                            "display": "Oral Form Oxycodone (product)"
                        }
                    ]
                },
                "form": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "385055001",
                            "display": "Tablet dose form (qualifier value)"
                        }
                    ]
                },
                "ingredient": [
                    {
                        "itemReference": {
                            "reference": "#sub03"
                        },
                        "strength": {
                            "numerator": {
                                "value": 5,
                                "system": "http://unitsofmeasure.org",
                                "code": "mg"
                            },
                            "denominator": {
                                "value": 1,
                                "system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
                                "code": "TAB"
                            }
                        }
                    }
                ]
            },
            "request": {
                "method": "POST",
                "url": "Medication"
            }
        }
    ]
}

Agrupando recursos do FHIR como uma única entidade

Para agrupar recursos do FHIR como uma única entidade

Configurando o nível de validação para pacotes

Ao agrupar recursos do FHIR, você pode especificar opcionalmente um cabeçalho x-amzn-healthlake-fhir-validation-level HTTP para configurar um nível de validação para o recurso. Esse nível de validação será definido para todas as solicitações de criação e atualização dentro do pacote. AWS HealthLake atualmente suporta os seguintes níveis de validação:

Recursos agrupados com o nível mínimo de validação podem ser ingeridos em um Datastore, apesar da falha na validação necessária para a indexação de pesquisas. Nesse caso, os recursos serão atualizados para incluir uma extensão específica do Healthlake para documentar essas falhas, e as entradas na resposta do pacote incluirão OperationOutcome os seguintes recursos:

{
    "resourceType": "Bundle",
    "type": "batch-response",
    "timestamp": "2025-08-25T22:58:48.846287342Z",
    "entry": [
        {
            "response": {
                "status": "201",
                "location": "Patient/195abc49-ba8e-4c8b-95c2-abc88fef7544/_history/1",
                "etag": "W/\"1\"",
                "lastModified": "2025-08-25T22:58:48.801245445Z",
                "outcome": {
                    "resourceType": "OperationOutcome",
                    "issue": [
                        {
                            "severity": "error",
                            "code": "processing",
                            "details": {
                                "text": "FHIR resource in payload failed FHIR validation rules."
                            },
                            "diagnostics": "FHIR resource in payload failed FHIR validation rules."
                        }
                    ]
                }
            }
        }
    ]
}

Além disso, o seguinte cabeçalho de resposta HTTP será incluído com o valor “true”:

x-amzn-healthlake-validation-issues : true

Suporte limitado para “mensagem” do tipo Bundle

HealthLake fornece suporte limitado para o tipo de pacote FHIR message por meio de um processo de conversão interno. Esse suporte foi projetado para cenários em que os pacotes de mensagens não podem ser reformatados na origem, como a ingestão de feeds ADT (Admissão, Descarga, Transferência) de sistemas hospitalares antigos.

Principais diferenças em relação ao processamento padrão de mensagens

Limitações importantes

Exemplo de estrutura de pacote de mensagens

{
              "resourceType": "Bundle",
              "type": "message",
              "entry": [
                {
                  "resource": {
                    "resourceType": "MessageHeader",
                    "eventCoding": {
                      "system": "http://hl7.org/fhir/us/davinci-alerts/CodeSystem/notification-event",
                      "code": "notification-admit"
                    },
                    "focus": [{"reference": "Encounter/example-id"}]
                  }
                },
                {
                  "resource": {"resourceType": "Patient", "id": "example-id"}
                },
                {
                  "resource": {"resourceType": "Encounter", "id": "example-id"}
                }
              ]
            }
            

Transações assíncronas de pacotes

AWS HealthLake suporta o Bundle tipo assíncrono transaction que permite enviar transações com até 500 recursos. Quando você envia uma transação assíncrona, ela é colocada em HealthLake fila para processamento e retorna imediatamente uma URL de pesquisa. Você pode usar esse URL para verificar o status e recuperar a resposta. Isso segue o padrão de pacote assíncrono FHIR.

Quando usar transações assíncronas

Enviando uma transação assíncrona

Para enviar uma transação assíncrona, envie uma POST solicitação ao endpoint do armazenamento de dados com o cabeçalho. Prefer: respond-async O pacote deve ter um tipotransaction. Pacotes com tipo não batch são suportados para processamento assíncrono de pacotes.

HealthLake faz as validações iniciais do pacote no momento do envio. Se a validação for bem-sucedida, HealthLake retornará HTTP 202 Accepted com um cabeçalho de content-location resposta que contém o URL da pesquisa.

Para enviar um tipo Bundle assíncrono transaction

Pesquisa sobre o status da transação

Depois de enviar uma transação assíncrona, use o URL de pesquisa do cabeçalho da content-location resposta para verificar o status da transação. Envie uma GET solicitação para o URL da pesquisa.

Envie uma GET solicitação para o URL da pesquisa. O exemplo a seguir usa a ferramenta de linha de curl comando.

SigV4

Autorização SigV4

curl --request GET \
  'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId' \
  --aws-sigv4 'aws:amz:region:healthlake' \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  --header "x-amz-security-token:$AWS_SESSION_TOKEN" \
  --header 'Accept: application/json'

SMART on FHIR

SMART na autorização do FHIR. O token de autorização deve incluir read permissões sobre o tipo de Transaction recurso.

curl --request GET \
  'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId' \
  --header 'Authorization: Bearer $SMART_ACCESS_TOKEN' \
  --header 'Accept: application/json'

A tabela a seguir descreve as respostas possíveis.

Os exemplos a seguir mostram cada tipo de resposta.

Transação em fila (202)

{
    "resourceType": "OperationOutcome",
    "id": "transactionId",
    "issue": [
        {
            "severity": "information",
            "code": "informational",
            "diagnostics": "SUBMITTED"
        }
    ]
}

Processamento de transações (202)

{
    "resourceType": "OperationOutcome",
    "id": "transactionId",
    "issue": [
        {
            "severity": "information",
            "code": "informational",
            "diagnostics": "IN_PROGRESS"
        }
    ]
}

Transação concluída (200)

{
    "resourceType": "Bundle",
    "type": "transaction-response",
    "entry": [
        {
            "response": {
                "status": "201",
                "location": "Patient/example-id/_history/1",
                "etag": "W/\"1\"",
                "lastModified": "2024-01-15T10:30:00.000Z"
            }
        },
        {
            "response": {
                "status": "201",
                "location": "Observation/example-id/_history/1",
                "etag": "W/\"1\"",
                "lastModified": "2024-01-15T10:30:00.000Z"
            }
        }
    ]
}

Falha na transação (4xx/5xx)

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "exception",
            "diagnostics": "Transaction failed: conflict detected on resource Patient/example-id"
        }
    ]
}

Pedido de processamento

Pacotes assíncronos do tipo transaction são colocados em fila, mas não são processados em uma ordem estrita de envio. HealthLake otimiza o processamento com base na capacidade disponível e na carga do sistema.

Cotas e limitação

As cotas e limites de taxa a seguir se aplicam às transações assíncronas.

Tratamento de erros

Para um pacote de “transação”, todos os recursos FHIR contidos no pacote são processados como uma operação atômica. Todos os recursos da operação devem ser bem-sucedidos, ou nenhuma operação no pacote será processada.

Os erros se enquadram em duas categorias: erros de envio que HealthLake retornam de forma síncrona e erros de processamento que você recupera por meio de enquetes.

Erros de envio

HealthLake valida o pacote no momento do envio e retorna os erros de forma síncrona antes que a transação seja colocada na fila. Os erros de envio incluem erros inválidos de validação de recursos do FHIR, tipos de recursos não suportados, exceder o limite de 500 operações e usar o Prefer: respond-async cabeçalho com pacotes de lotes. Se o limite de transações pendentes para o armazenamento de dados tiver sido atingido, HealthLake retorna ThrottlingException a. Quando ocorre um erro de envio, a transação não será colocada na fila.

Erros de processamento

Os erros de processamento ocorrem depois que a transação é colocada na fila e retornada por meio do URL da pesquisa. Isso inclui conflitos de transação, em que outra operação modificou um recurso que faz parte da transação, e erros do servidor durante o processamento. Quando ocorre um erro de processamento, nenhuma mutação de recurso é feita para os recursos na transação. O URL da pesquisa retornará um OperationOutcome com os detalhes do erro.