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.
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction)os 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.
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction)os 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.
**Diferenças entre pacotes de lotes e de transações**
| Recurso | Batch | TRANSACTION |
| --- | --- | --- |
| Modelo de processamento | Cada operação é bem-sucedida ou falha de forma independente. | Todas as operações são bem-sucedidas ou falham como uma única unidade atômica. |
| Tratamento de falhas | O processamento continua mesmo se as operações individuais falharem. | O pacote inteiro falhará se uma única operação falhar. |
| Ordem de execução | A ordem de execução não é garantida. | As operações são processadas na ordem especificada. |
| Integridade referencial | Não aplicado em todas as operações. | Aplicado para recursos referenciados localmente dentro do pacote. |
| Melhor usado para | Operações em massa em que o sucesso parcial é aceitável. | Recursos relacionados que devem ser criados ou atualizados 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](https://hl7.org/fhir/R4/Bundle) do **FHIR R4**.
Veja a seguir exemplos de casos de uso para cada tipo de pacote.
Pacotes em lote
+ Faça upload de vários registros de pacientes não relacionados de diferentes instalações durante a sincronização noturna de dados.
+ Faça upload em massa de registros históricos de medicamentos em que alguns registros podem ter problemas de validação.
+ Carregue dados de referência, como organizações e profissionais, em que falhas individuais não afetem outras entradas.
Pacotes de transações
+ Crie um paciente com observações e condições relacionadas durante uma admissão no departamento de emergência, onde todos os dados devem ser registrados juntos.
+ Atualize a lista de medicamentos do paciente e as informações relacionadas à alergia que devem permanecer consistentes.
+ Registre um encontro completo com o paciente, observações, procedimentos e informações de cobrança como uma única unidade atômica.
**Importante**
Os pacotes de lotes e transações usam a mesma estrutura `Bundle` de recursos. A única diferença é o valor do `type` campo.
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**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake `region` `datastoreId` e. *Não* especifique um tipo de recurso FHIR no URL. Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
POST https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/
```
1. Crie um corpo JSON para a solicitação, especificando cada verbo HTTP como parte dos elementos. `method` O exemplo a seguir usa uma interação `batch` de tipo com o `Bundle` recurso para criar novos `Patient` `Medication` recursos. Todas as seções obrigatórias são comentadas adequadamente. Para fins desse procedimento, salve o arquivo como`batch-independent.json`.
```
{
"resourceType": "Bundle",
"id": "bundle-batch",
"meta": {
"lastUpdated": "2014-08-18T01:43:30Z"
},
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"meta": {
"lastUpdated": "2022-06-03T17:53:36.724Z"
},
"text": {
"status": "generated",
"div": "Some narrative"
},
"active": true,
"name": [
{
"use": "official",
"family": "Jackson",
"given": [
"Mateo",
"James"
]
}
],
"gender": "male",
"birthDate": "1974-12-25"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"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"
}
}
]
}
```
1. Envie a solicitação . O tipo de `Bundle` lote FHIR usa uma `POST` solicitação com [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) ou SMART na autorização FHIR. O exemplo de código a seguir usa a ferramenta de linha de `curl` comando para fins de demonstração.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request POST \
'https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/' \
--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' \
--data @batch-type.json
```
------
#### [ SMART on FHIR ]
SMART no exemplo de autorização FHIR para o tipo de [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)dados.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
O chamador pode atribuir permissões na autorização lambda. Para obter mais informações, consulte [OAuth escopos 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
O servidor retorna uma resposta mostrando `Patient` os `Medication` recursos criados como resultado da solicitação do tipo de `Bundle` lote.
## Condicional PUTs em pacotes
AWS HealthLake oferece suporte a atualizações condicionais em pacotes usando os seguintes parâmetros de consulta:
**nota**
PUTs As condicionais são suportadas somente em `batch` pacotes. `Transaction`pacotes não oferecem suporte a condicionais PUTs.
+ `_id`(autônomo)
+ `_id`em combinação com um dos seguintes:
+ `_tag`
+ `_createdAt`
+ `_lastUpdated`
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.
**Comportamento de atualização condicional**
| Cenário | Status HTTP | Ação tomada |
| --- | --- | --- |
| Recurso sem ID fornecido | 201 Criado | Sempre cria um novo recurso. |
| Recurso com novo ID (sem correspondência) | 201 Criado | Cria um novo recurso com o ID especificado. |
| Recurso com ID existente (correspondência única) | 200 OK | Atualiza o recurso correspondente. |
| Recurso com ID existente (conflito detectado) | 409 Conflito | Retorna um erro. Nenhuma alteração é feita. |
| Recurso com ID existente (incompatibilidade de ID) | 400 solicitação inválida | Retorna um erro. Nenhuma alteração é feita. |
| Vários recursos correspondem às condições | 412 Falha na pré-condição | Retorna um erro. Nenhuma alteração é feita. |
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**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake `region` `datastoreId` e. Inclua o tipo de recurso FHIR `Bundle` como parte do URL. Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
POST https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Bundle
```
1. Crie um corpo JSON para a solicitação, especificando os recursos FHIR a serem agrupados. O exemplo a seguir agrupa dois `Patient` recursos em HealthLake. Para fins desse procedimento, salve o arquivo como`batch-single.json`.
```
{
"resourceType": "Bundle",
"id": "bundle-minimal",
"language": "en-US",
"identifier": {
"system": "urn:oid:1.2.3.4.5",
"value": "28b95815-76ce-457b-b7ae-a972e527db4f"
},
"type": "document",
"timestamp": "2020-12-11T14:30:00+01:00",
"entry": [
{
"fullUrl": "urn:uuid:f40b07e3-37e8-48c3-bf1c-ae70fe12dabf",
"resource": {
"resourceType": "Composition",
"id": "f40b07e3-37e8-48c3-bf1c-ae70fe12dabf",
"status": "final",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "60591-5",
"display": "Patient summary Document"
}
]
},
"date": "2020-12-11T14:30:00+01:00",
"author": [
{
"reference": "urn:uuid:45271f7f-63ab-4946-970f-3daaaa0663ff"
}
],
"title": "Patient Summary as of December 7, 2020 14:30"
}
},
{
"fullUrl": "urn:uuid:45271f7f-63ab-4946-970f-3daaaa0663ff",
"resource": {
"resourceType": "Practitioner",
"id": "45271f7f-63ab-4946-970f-3daaaa0663ff",
"active": true,
"name": [
{
"family": "Doe",
"given": [
"John"
]
}
]
}
}
]
}
```
1. Envie a solicitação . O tipo de `Bundle` documento FHIR usa uma `POST` solicitação com o protocolo de [AWS assinatura Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). O exemplo de código a seguir usa a ferramenta de linha de `curl` comando para fins de demonstração.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request POST \
'https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Bundle' \
--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' \
--data @document-type.json
```
------
#### [ SMART on FHIR ]
SMART no exemplo de autorização FHIR para o tipo de [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)dados.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
O chamador pode atribuir permissões na autorização lambda. Para obter mais informações, consulte [OAuth escopos 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
O servidor retorna uma resposta mostrando dois `Patient` recursos criados como resultado da solicitação do tipo de `Bundle` documento.
## 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:
+ `strict`: os recursos são validados de acordo com o elemento de perfil do recurso ou com a especificação R4 se nenhum perfil estiver presente. Esse é o nível de validação padrão para AWS HealthLake.
+ `structure-only`: os recursos são validados em relação ao R4, ignorando quaisquer perfis referenciados.
+ `minimal`: os recursos são validados minimamente, ignorando certas regras do R4. Os recursos que falharem nas verificações de estrutura exigidas search/analytics serão atualizados para incluir um aviso para auditoria.
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
```
**nota**
Observe que os dados ingeridos que estão malformados de acordo com a especificação R4 podem não ser pesquisáveis conforme o esperado se esses erros estiverem presentes.
## 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.
**Atenção**
Esse recurso requer uma lista explícita de permissões de AWS contas e não impõe a semântica da mensagem FHIR R4 ou a integridade referencial. Entre em contato com o AWS Support para solicitar a ativação da sua conta antes de usar pacotes de mensagens.
### Principais diferenças em relação ao processamento padrão de mensagens
+ **Pacotes de mensagens** (especificação FHIR): a primeira entrada deve ser uma `MessageHeader` que faça referência a outros recursos. Os recursos não têm `request` objetos individuais e o MessageHeader evento determina as ações de processamento.
+ **HealthLake Processamento**: converte pacotes de mensagens em pacotes em lotes atribuindo automaticamente operações PUT a cada entrada de recurso. Os recursos são processados de forma independente, sem impor a semântica da mensagem ou a integridade referencial.
### Limitações importantes
+ As regras de processamento específicas de mensagens do FHIR R4 não são aplicadas
+ Sem integridade transacional em todos os recursos
+ As referências entre recursos não são validadas
+ Requer uma lista explícita de permissões da conta
### 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"}
}
]
}
```
**nota**
Cada recurso é armazenado de forma independente, como se fosse enviado por meio de operações PUT individuais. Se a semântica completa das mensagens FHIR ou a validação da integridade referencial forem necessárias, pré-processe os pacotes de mensagens ou implemente a validação em nível de aplicativo antes do envio.
## 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](https://hl7.org/fhir/async-bundle.html).
**Quando usar transações assíncronas**
+ Você precisa enviar mais de 100 recursos (limite síncrono) em uma única transação.
+ Você quer evitar o bloqueio do seu aplicativo enquanto aguarda a conclusão do processamento da transação.
+ Você precisa processar grandes volumes de recursos relacionados com melhor rendimento.
**Importante**
Os resultados da pesquisa estão disponíveis por 90 dias após a conclusão da transação. Após esse período de 90 dias, o URL da pesquisa não retorna mais os resultados. Projete sua integração para recuperar e armazenar resultados nessa janela.
**nota**
O `Bundle` tipo síncrono `transaction` continua suportando até 100 recursos e é o modo de processamento padrão. Se você enviar um `Bundle` tipo `transaction` com mais de 100 recursos sem o `Prefer: respond-async` cabeçalho, HealthLake retornará um `422 Unprocessable Entity` erro. Pacotes com tipo não `batch` são compatíveis com processamento assíncrono — somente `Bundle` tipos `transaction` podem ser enviados de forma assíncrona (com até 500 operações).
**nota**
`PATCH`operações e condicionais não PUTs são suportadas em transações assíncronas de pacotes.
### 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 tipo`transaction`. 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`**
1. Envie uma `POST` solicitação para o endpoint do armazenamento de HealthLake dados.
```
POST https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/
```
1. Construa um corpo JSON para a solicitação com o tipo de pacote. `transaction` Para fins desse procedimento, salve o arquivo como`async-transaction.json`.
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"active": true,
"name": [
{
"use": "official",
"family": "Smith",
"given": ["Jane"]
}
],
"gender": "female",
"birthDate": "1990-01-15"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Observation",
"status": "final",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "85354-9",
"display": "Blood pressure panel"
}
]
},
"subject": {
"reference": "urn:uuid:example-patient-id"
}
},
"request": {
"method": "POST",
"url": "Observation"
}
}
]
}
```
1. Envie a solicitação com o `Prefer: respond-async` cabeçalho. O tipo de `Bundle` transação FHIR usa uma `POST` solicitação com [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) ou SMART na autorização FHIR. O exemplo de código a seguir usa a ferramenta de linha de `curl` comando para fins de demonstração.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request POST \
'https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/' \
--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' \
--header 'Prefer: respond-async' \
--data @async-transaction.json
```
------
#### [ SMART on FHIR ]
SMART no exemplo de autorização FHIR para o tipo de [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)dados.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
O chamador pode atribuir permissões na autorização lambda. Para obter mais informações, consulte [OAuth escopos 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
1. Em caso de envio bem-sucedido, o servidor retorna HTTP 202 Accepted. O cabeçalho da `content-location` resposta contém o URL da pesquisa. O corpo da resposta é um `OperationOutcome` recurso.
```
HTTP/1.1 202 Accepted
content-location: https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Transaction/{{transactionId}}
```
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Submitted Asynchronous Bundle Transaction",
"location": [
"https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Transaction/{{transactionId}}"
]
}
]
}
```
### 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.
**nota**
Para SMART em armazenamentos de dados habilitados para FHIR, o token de autorização deve incluir `read` permissões sobre o tipo de `Transaction` recurso para pesquisar o status da transação. Para obter mais informações sobre SMART em escopos FHIR, consulte. [SMART em escopos FHIR OAuth 2.0 suportados por HealthLake](reference-smart-on-fhir-oauth-scopes.md)
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.
**Códigos de resposta da pesquisa**
| Status HTTP | Significado | Corpo da resposta |
| --- | --- | --- |
| 202 aceito | A transação está na fila | OperationOutcomecom diagnósticos “ENVIADOS” |
| 202 aceito | A transação está sendo processada | OperationOutcomecom diagnóstico “IN\_PROGRESS” |
| 200 OK | Transação concluída com sucesso | Bundlecom tipo transaction-response |
| 4xx/5xx | Falha na transação | OperationOutcomecom detalhes do erro |
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.
**Importante**
Não dependa de transações sendo processadas na ordem em que foram enviadas. Por exemplo, se você enviar a Transação A às 10h e a Transação B às 10h01, a Transação B poderá ser concluída antes da Transação A. Crie sua inscrição para:
Lide com out-of-order a conclusão.
Use o URL da pesquisa para rastrear cada transação de forma independente.
Implemente o sequenciamento em nível de aplicativo se a ordem for importante para seu caso de uso.
### Cotas e limitação
As cotas e limites de taxa a seguir se aplicam às transações assíncronas.
**Cotas de transações assíncronas**
| Quota | Valor | Ajustável |
| --- | --- | --- |
| Máximo de operações por transação assíncrona | 500 | Não |
| Máximo de transações pendentes por armazenamento de dados | 500 | Sim |
+ As transações assíncronas compartilham os mesmos limites de taxa de API definidos em. [Cotas de serviço](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas)
+ A pesquisa do status da transação compartilha os mesmos limites de taxa de API das operações read (`GET`) nos recursos do FHIR.
+ Se o limite de transações pendentes for atingido, os envios subsequentes retornarão um erro até que as transações existentes sejam concluídas.
### 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.