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á.
# Gerenciando recursos do FHIR em AWS HealthLake
Use as interações da RESTful API FHIR R4 para gerenciar recursos do FHIR em um armazenamento de dados. HealthLake As seções a seguir descrevem todas as interações da RESTful API FHIR R4 HealthLake suportadas disponíveis para o gerenciamento de recursos do FHIR. Para obter informações sobre HealthLake os recursos do armazenamento de dados e quais partes da especificação FHIR são compatíveis, consulte. [Declaração de capacidade do FHIR R4 para AWS HealthLake](reference-fhir-capability-statement.md)
**nota**
As interações FHIR listadas neste capítulo são construídas em conformidade com o padrão HL7 FHIR R4 para troca de dados de assistência médica. Por serem representações dos serviços da HL7 FHIR, não são oferecidos por meio AWS CLI de e. AWS SDKs Para obter mais informações, consulte [RESTful API](https://hl7.org/fhir/R4/http.html) na documentação da API **FHIR R4 RESTful **.
A tabela a seguir lista as interações FHIR R4 suportadas pelo. AWS HealthLake Para obter informações sobre os *tipos de recursos* do FHIR suportados pelo HealthLake, consulte. [Resource types](reference-fhir-resource-types.md)
**Interações FHIR R4 suportadas por AWS HealthLake**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/healthlake/latest/devguide/managing-fhir-resources.html)
**Topics**
+ [Criando um recurso FHIR](managing-fhir-resources-create.md)
+ [Lendo um recurso do FHIR](managing-fhir-resources-read.md)
+ [Lendo o histórico de recursos do FHIR](managing-fhir-resources-read-history.md)
+ [Atualizando um recurso FHIR](managing-fhir-resources-update.md)
+ [Modificando recursos com a operação PATCH](managing-fhir-resources-patch.md)
+ [Agrupando recursos do FHIR](managing-fhir-resources-bundle.md)
+ [Excluindo um recurso FHIR](managing-fhir-resources-delete.md)
+ [Idempotência e concorrência](managing-fhir-resources-idempotency.md)
# Criando um recurso FHIR
A `create` interação FHIR cria um novo recurso FHIR em um armazenamento de dados. HealthLake Para obter informações adicionais, consulte a [https://hl7.org/fhir/R4/http.html#create](https://hl7.org/fhir/R4/http.html#create)documentação da API **FHIR R4 RESTful **.
**Para criar um recurso FHIR**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Determine o tipo de FHIR `Resource` a ser criado. Para obter mais informações, consulte [Resource types](reference-fhir-resource-types.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake `region` `datastoreId` e. Inclua também o `Resource` tipo FHIR a ser criado. 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/Resource
```
1. Crie um corpo JSON para a solicitação, especificando os dados FHIR para o novo recurso. Para fins deste procedimento, estamos usando um `Patient` recurso FHIR, então salve o arquivo como. `create-patient.json`
```
{
"resourceType": "Patient",
"identifier": [
{
"system": "urn:oid:1.2.36.146.595.217.0.1",
"value": "12345"
}
],
"name": [
{
"family": "Silva",
"given": [
"Ana",
"Carolina"
]
}
],
"gender": "female",
"birthDate": "1992-02-10"
}
```
1. Envie a solicitação . A `create` interaçã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. Os exemplos a seguir criam um `Patient` recurso FHIR HealthLake usando o curl ou o console. HealthLake Para ver um exemplo inteiro, role até o botão **Copiar**.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request POST \
'https://healthlake.region.amazonaws.com/datastore/datastore-id/r4/Patient' \
--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 @create-patient.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).
------
#### [ AWS Console ]
**nota**
O HealthLake console suporta somente a autorização [AWS SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html).
1. Faça login na página [Executar consulta](https://console.aws.amazon.com/healthlake/home#/crud) no HealthLake console.
2. Na seção **Configurações da consulta**, faça as seguintes seleções.
+ **ID do armazenamento de dados** — escolha um ID do armazenamento de dados para gerar uma sequência de caracteres de consulta.
+ **Tipo de consulta** — escolha`Create`.
+ **Tipo de recurso** — escolha o tipo de [recurso FHIR a ser criado](reference-fhir-resource-types.md).
+ **Corpo da solicitação** — construa um corpo JSON para a solicitação, especificando os dados FHIR para o novo recurso.
3. Selecione **Executar consulta**.
------
**Configurando o nível de validação para criação de recursos**
Ao criar um recurso 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. 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.
Os recursos criados 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:
```
{
"url": "http://healthlake.amazonaws.com/fhir/StructureDefinition/validation-issue",
"valueString": "{\"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**
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.
# Lendo um recurso do FHIR
A `read` interação FHIR lê o estado atual de um recurso em um armazenamento de HealthLake dados. Para obter informações adicionais, consulte a [https://hl7.org/fhir/R4/http.html#read](https://hl7.org/fhir/R4/http.html#read)documentação da API **FHIR R4 RESTful **.
**Para ler um recurso do FHIR**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Determine o tipo de FHIR `Resource` para ler e coletar o valor associado`id`. Para obter mais informações, consulte [Resource types](reference-fhir-resource-types.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake `region` `datastoreId` e. Inclua também o `Resource` tipo FHIR e seus associados. `id` Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. Envie a solicitação . A `read` interação FHIR usa uma `GET` 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 `curl` exemplo a seguir lê o estado atual de um `Patient` recurso FHIR em. HealthLake Para ver o exemplo inteiro, role até o botão **Copiar**.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id' \
--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 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).
------
#### [ AWS Console ]
1. Faça login na página [Executar consulta](https://console.aws.amazon.com/healthlake/home#/crud) no HealthLake console.
2. Na seção **Configurações da consulta**, faça as seguintes seleções.
+ **ID do armazenamento de dados** — escolha um ID do armazenamento de dados para gerar uma sequência de caracteres de consulta.
+ **Tipo de consulta** — escolha`Read`.
+ **Tipo de recurso** — escolha o tipo de [recurso FHIR a ser lido](reference-fhir-resource-types.md).
+ **ID do recurso** — insira o ID do recurso FHIR.
3. Selecione **Executar consulta**.
------
# Lendo o histórico de recursos do FHIR
A `history` interação FHIR recupera o histórico de um recurso FHIR específico em um armazenamento de dados. HealthLake Usando essa interação, você pode determinar como o conteúdo de um recurso FHIR mudou ao longo do tempo. Também é útil em coordenação com os registros de auditoria para ver o estado de um recurso antes e depois da modificação. As interações `create` do FHIR e `delete` resultam em uma versão histórica do recurso a ser salvo. `update` Para obter informações adicionais, consulte a [https://hl7.org/fhir/R4/http.html#history](https://hl7.org/fhir/R4/http.html#history)documentação da API **FHIR R4 RESTful **.
**nota**
Você pode optar por não receber tipos `history` específicos de recursos do FHIR. Para optar por não participar, crie um caso usando [AWS Support Center Console](https://console.aws.amazon.com/support/home#/). Para criar seu caso, faça login no seu Conta da AWS e escolha **Criar caso**.
**Para ler o histórico de recursos do FHIR**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Determine o tipo de FHIR `Resource` para ler e coletar o valor associado`id`. Para obter mais informações, consulte [Resource types](reference-fhir-resource-types.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake `region` `datastoreId` e. Inclua também o `Resource` tipo de FHIR, seus parâmetros de pesquisa associados `id` e opcionais. Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id/_history{?[parameters]}
```
**HealthLake parâmetros de pesquisa suportados para interação FHIR `history`**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/healthlake/latest/devguide/managing-fhir-resources-read-history.html)
1. Envie a solicitação . A `history` interação FHIR usa uma `GET` 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 `curl` exemplo a seguir usa o parâmetro de `_count` pesquisa para retornar 100 resultados históricos de pesquisa por página para um `Patient` recurso FHIR em. HealthLake Para ver o exemplo inteiro, role até o botão **Copiar**.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastore-id/r4/Patient/id/_history?_count=100' \
--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 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 conteúdo de retorno de uma `history` interação está contido em um recurso FHIR`Bundle`, com o tipo definido como. `history` Ele contém o histórico de versões especificado, classificado com as versões mais antigas por último, e inclui recursos excluídos. Para obter mais informações, consulte a [https://hl7.org/fhir/R4/bundle.html](https://hl7.org/fhir/R4/bundle.html)documentação do **FHIR R4**.
## Lendo o histórico de recursos FHIR específico da versão
A `vread` interação FHIR realiza uma leitura específica da versão de um recurso em um armazenamento de dados. HealthLake Usando essa interação, você pode visualizar o conteúdo de um recurso FHIR como era em um determinado momento no passado.
**nota**
Se você usar a `history` interação FHIR *sem*`vread`, HealthLake sempre retornará a versão mais recente dos metadados do recurso.
HealthLake declara que oferece suporte ao controle de versão [https://hl7.org/fhir/R4/capabilitystatement-definitions.html#CapabilityStatement.rest.resource.versioning](https://hl7.org/fhir/R4/capabilitystatement-definitions.html#CapabilityStatement.rest.resource.versioning)para cada recurso suportado. Todos os armazenamentos de HealthLake dados incluem `Resource.meta.versionId` (`vid`) em todos os recursos.
Quando a `history` interação FHIR está ativada (por padrão para armazenamentos de dados criados após 25/10/2024 ou por solicitação para armazenamentos de dados mais antigos), a `Bundle` resposta inclui o como parte do `vid` elemento. [https://hl7.org/fhir/R4/bundle-definitions.html#Bundle.entry.response.location](https://hl7.org/fhir/R4/bundle-definitions.html#Bundle.entry.response.location) No exemplo a seguir, o é `vid` exibido como o número`1`. Para ver o exemplo completo, consulte [Exemplo de bundle/bundle-response](https://build.fhir.org/bundle-response.json.html) (JSON).
```
"response" : {
"status" : "201 Created",
"location" : "Patient/12423/_history/1",
...}
```
**Para ler o histórico de recursos FHIR específico da versão**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Determine o `Resource` tipo de FHIR para ler e coletar valores `id` e `vid` associados. Para obter mais informações, consulte [Resource types](reference-fhir-resource-types.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake e FHIR. Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id/_history/vid
```
1. Envie a solicitação . A `history` interação FHIR usa uma `GET` solicitação com [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) ou SMART na autorização FHIR. A `vread` interação a seguir retorna uma única instância com o conteúdo especificado para o `Patient` recurso FHIR para a versão dos metadados do recurso especificada pelo. `vid` Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastore-id/r4/Patient/id/_history/vid' \
--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 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).
------
# Atualizando um recurso FHIR
A `update` interação FHIR cria uma nova versão atual para um recurso existente ou cria uma versão inicial se nenhum recurso já existir para o determinado. `id` Para obter informações adicionais, consulte a [https://hl7.org/fhir/R4/http.html#update](https://hl7.org/fhir/R4/http.html#update)documentação da API **FHIR R4 RESTful **.
**Para atualizar um recurso FHIR**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Determine o tipo de FHIR `Resource` para atualizar e coletar o valor associado`id`. Para obter mais informações, consulte [Resource types](reference-fhir-resource-types.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake `region` `datastoreId` e. Inclua também o `Resource` tipo FHIR e seus associados. `id` Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
PUT https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. Crie um `JSON` corpo para a solicitação, especificando as atualizações de dados do FHIR a serem feitas. Para fins desse procedimento, salve o arquivo como`update-patient.json`.
```
{
"id": "2de04858-ba65-44c1-8af1-f2fe69a977d9",
"resourceType": "Patient",
"active": true,
"name": [
{
"use": "official",
"family": "Doe",
"given": [
"Jane"
]
},
{
"use": "usual",
"given": [
"Jane"
]
}
],
"gender": "female",
"birthDate": "1985-12-31"
}
```
1. Envie a solicitação . A `update` interação FHIR usa uma `PUT` 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 `curl` exemplo a seguir atualiza um `Patient` recurso em HealthLake. Para ver o exemplo inteiro, role até o botão **Copiar**.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request PUT \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id' \
--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 @update-patient.json
```
Sua solicitação retornará um código de status `200` HTTP se um recurso existente for *atualizado* ou um código de status `201` HTTP se um novo recurso for criado.
------
#### [ 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).
------
#### [ AWS Console ]
1. Faça login na página [Executar consulta](https://console.aws.amazon.com/healthlake/home#/crud) no HealthLake console.
2. Na seção **Configurações da consulta**, faça as seguintes seleções.
+ **ID do armazenamento de dados** — escolha um ID do armazenamento de dados para gerar uma sequência de caracteres de consulta.
+ **Tipo de consulta** — escolha`Update (PUT)`.
+ **Tipo de recurso** — escolha o [tipo de recurso](reference-fhir-resource-types.md) FHIR para atualizar ou criar.
+ **Corpo da solicitação** — construa um corpo JSON para a solicitação, especificando os dados FHIR com os quais atualizar o recurso.
3. Selecione **Executar consulta**.
------
## Atualização dos recursos do FHIR com base nas condições
A atualização condicional permite que você atualize um recurso existente com base em alguns critérios de pesquisa de identificação, em vez de usar o `id` FHIR lógico. Quando o servidor processa a atualização, ele realiza uma pesquisa usando seus recursos de pesquisa padrão para o tipo de recurso, com o objetivo de resolver uma única lógica `id` para a solicitação.
A ação que o servidor executa depende de quantas correspondências ele encontra:
+ **Sem correspondências, não `id` fornecido no corpo da solicitação**: o servidor cria o recurso FHIR.
+ **Nenhuma correspondência, `id` fornecida e o recurso ainda não existe com o `id`**: O servidor trata a interação como uma interação de atualização como criação.
+ **Nenhuma correspondência, `id` fornecida e já existe**: o servidor rejeita a atualização com um `409 Conflict` erro.
+ **Uma correspondência, nenhum recurso `id` fornecido OU (recurso `id` fornecido e corresponde ao recurso encontrado)**: O servidor executa a atualização em relação ao recurso correspondente conforme descrito acima, onde, se o recurso foi atualizado, o servidor DEVE retornar `200 OK` a.
+ **One Match, recurso `id` fornecido, mas não corresponde ao recurso encontrado**: o servidor retorna um `409 Conflict` erro indicando que a especificação do ID do cliente era um problema, preferencialmente com um `OperationOutcome`
+ **Várias correspondências**: o servidor retorna um `412 Precondition Failed` erro indicando que os critérios do cliente não foram seletivos o suficiente, de preferência com um OperationOutcome
O exemplo a seguir atualiza um `Patient` recurso cujo nome é peter, data de nascimento é 1º de janeiro de 2000 e número de telefone 1234567890.
```
PUT https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?name=peter&birthdate=2000-01-01&phone=1234567890
```
## Configurando o nível de validação para atualizações de recursos
Ao atualizar um recurso 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. 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 atualizados 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:
```
{
"url": "http://healthlake.amazonaws.com/fhir/StructureDefinition/validation-issue",
"valueString": "{\"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.
# Modificando recursos com a operação PATCH
AWS HealthLake suporta a operação PATCH para recursos do FHIR, permitindo que você modifique recursos direcionando elementos específicos para adicionar, substituir ou excluir sem atualizar o recurso inteiro. Essa operação é particularmente útil quando você precisa:
+ Faça atualizações direcionadas para grandes recursos
+ Reduza o uso da largura de banda da rede
+ Execute modificações atômicas em elementos de recursos específicos
+ Minimize o risco de sobrescrever alterações simultâneas
+ Atualize recursos como parte dos fluxos de trabalho em lotes e transações
## Formatos PATCH suportados
AWS HealthLake suporta dois formatos PATCH padrão:
### Correção JSON (RFC 6902)
Usa a sintaxe JSON Pointer para direcionar elementos de acordo com sua posição na estrutura do recurso.
**Tipo de conteúdo:** `application/json-patch+json`
### FHIRPath Patch (especificação FHIR R4)
Usa FHIRPath expressões para direcionar elementos de acordo com seu conteúdo e relacionamentos, fornecendo uma abordagem nativa do FHIR para a aplicação de patches.
**Tipo de conteúdo:** `application/fhir+json`
## Usage
### Operações diretas de PATCH
A operação PATCH pode ser invocada diretamente nos recursos do FHIR usando o método PATCH HTTP:
```
PATCH [base]/[resource-type]/[id]{?_format=[mime-type]}
```
### PATCH em pacotes
As operações PATCH podem ser incluídas como entradas em pacotes FHIR do tipo `batch` ou`transaction`, permitindo que você combine operações de patch com outras interações FHIR (criar, ler, atualizar, excluir) em uma única solicitação.
+ **Pacotes de transações**: todas as entradas são bem-sucedidas ou falham atomicamente
+ **Pacotes em lote**: cada entrada é processada de forma independente
## Formato de patch JSON
### Operações com Suporte
| Operation | Description |
| --- | --- |
| add | Adicione um novo valor ao recurso |
| remove | Remover um valor do recurso |
| replace | Substituir um valor existente no recurso |
| move | Remover um valor de um local e adicioná-lo a outro |
| copy | Copiar um valor de um local para outro |
| test | Teste se um valor no local de destino é igual a um valor especificado |
### Sintaxe do caminho
O JSON Patch usa a sintaxe JSON Pointer (RFC 6901):
| Exemplo de caminho | Description |
| --- | --- |
| /name/0/family | Elemento familiar do primeiro nome |
| /telecom/- | Anexar à matriz de telecomunicações |
| /active | Elemento ativo no nível da raiz |
| /address/0/line/1 | Segunda linha do primeiro endereço |
### Exemplos
**Solicitação direta de patch JSON com várias operações**
```
PATCH [base]/Patient/example
Content-Type: application/json-patch+json
If-Match: W/"1"
[
{
"op": "replace",
"path": "/name/0/family",
"value": "Smith"
},
{
"op": "add",
"path": "/telecom/-",
"value": {
"system": "phone",
"value": "555-555-5555",
"use": "home"
}
},
{
"op": "remove",
"path": "/address/0"
},
{
"op": "move",
"from": "/name/0/family",
"path": "/name/1/family"
},
{
"op": "test",
"path": "/gender",
"value": "male"
},
{
"op": "copy",
"from": "/name/0",
"path": "/name/1"
}
]
```
**Solicitação direta de patch JSON com operação única**
```
PATCH [base]/Patient/example
Content-Type: application/json-patch+json
[
{
"op": "replace",
"path": "/active",
"value": false
}
]
```
**Patch JSON no pacote**
Use um recurso binário contendo a carga útil do patch JSON codificada em base64:
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [{
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJhZGQiLCJwYXRoIjoiL2JpcnRoRGF0ZSIsInZhbHVlIjoiMTk5MC0wMS0wMSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/123"
}
}]
}
```
## FHIRPath Formato do patch
### Operações com Suporte
| Operation | Description |
| --- | --- |
| add | Adicionar um novo elemento a um recurso |
| insert | Inserir um elemento em uma posição específica em uma lista |
| delete | Remover um elemento de um recurso |
| replace | Substituir o valor de um elemento existente |
| move | Reordenar elementos em uma lista |
### Sintaxe do caminho
FHIRPath O patch usa FHIRPath expressões, oferecendo suporte a:
+ Acesso **baseado em índices**: `Patient.name[0]`
+ **Filtrando com `where()`**: `Patient.name.where(use = 'official')`
+ **Lógica booleana**: `Patient.telecom.where(system = 'phone' and use = 'work')`
+ **Funções de subconfiguração**:`first()`, `last()`
+ **Verificações de existência**:`exists()`, `count()`
+ **Navegação polimórfica**: `Observation.value`
### Exemplos
**Solicitação direta FHIRPath de patch**
```
PATCH [base]/Patient/123
Content-Type: application/fhir+json
Authorization: ...
{
"resourceType": "Parameters",
"parameter": [{
"name": "operation",
"part": [
{ "name": "type", "valueCode": "add" },
{ "name": "path", "valueString": "Patient" },
{ "name": "name", "valueString": "birthDate" },
{ "name": "value", "valueDate": "1990-01-01" }
]
}]
}
```
**FHIRPath Patch no pacote**
Use um recurso de Parâmetros como recurso de entrada com`method: PATCH`:
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [{
"resource": {
"resourceType": "Parameters",
"parameter": [{
"name": "operation",
"part": [
{ "name": "type", "valueCode": "add" },
{ "name": "path", "valueString": "Patient" },
{ "name": "name", "valueString": "birthDate" },
{ "name": "value", "valueDate": "1990-01-01" }
]
}]
},
"request": {
"method": "PATCH",
"url": "Patient/123"
}
}]
}
```
## Cabeçalhos de solicitação
| Cabeçalho | Obrigatório | Descrição |
| --- | --- | --- |
| Content-Type | Sim | application/json-patch\$1jsonpara JSON Patch ou application/fhir\$1json para FHIRPath Patch |
| If-Match | Não | Atualização condicional específica da versão usando ETag |
## Resposta da amostra
A operação retorna o recurso atualizado com as informações da nova versão:
```
HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"2"
Last-Modified: Mon, 05 May 2025 10:10:10 GMT
{
"resourceType": "Patient",
"id": "example",
"active": true,
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"telecom": [
{
"system": "phone",
"value": "555-555-5555",
"use": "home"
}
],
"meta": {
"versionId": "2",
"lastUpdated": "2025-05-05T10:10:10Z"
}
}
```
## Comportamento
A operação PATCH:
+ Valida a sintaxe do patch de acordo com a especificação apropriada (RFC 6902 para JSON Patch, FHIR R4 para Patch) FHIRPath
+ Aplica operações atomicamente - todas as operações são bem-sucedidas ou todas falham
+ Atualiza o ID da versão do recurso e cria uma nova entrada no histórico
+ Preserva o recurso original no histórico antes de aplicar as alterações
+ Valida as restrições de recursos do FHIR após a aplicação de patches
+ Suporta atualizações condicionais usando o cabeçalho If-Match com ETag
## Tratamento de erros
A operação trata das seguintes condições de erro:
+ **400 Solicitação incorreta**: sintaxe de patch inválida (solicitação não conforme ou documento de patch malformado)
+ **404 Não encontrado**: recurso não encontrado (o ID especificado não existe)
+ **409 Conflito**: conflito de versão (atualizações simultâneas ou ID de versão não atual fornecida)
+ **422 Entidade não processável**: as operações de patch não podem ser aplicadas aos elementos de recursos especificados
## Resumo dos recursos
| Recurso | Patch JSON | FHIRPath Patch |
| --- | --- | --- |
| Tipo de conteúdo | application/json-patch\$1json | application/fhir\$1json |
| Formato do caminho | Ponteiro JSON (RFC 6901) | FHIRPath expressões |
| API PATCH direta | Compatível | Compatível |
| Bundle Batch | Compatível (via binário) | Suportado (por meio de parâmetros) |
| Transação de pacote | Compatível (via binário) | Suportado (por meio de parâmetros) |
| Operações | adicionar, remover, substituir, mover, copiar, testar | adicionar, inserir, excluir, substituir, mover |
## Limitações
+ Operações PATCH condicionais usando condições de pesquisa não são suportadas
+ O patch JSON em pacotes deve usar recursos binários com conteúdo codificado em base64
+ FHIRPath O patch em pacotes deve usar recursos de parâmetros
## Recursos adicionais
Para obter mais informações sobre as operações PATCH, consulte:
+ [Documentação do FHIR R4 PATCH](https://hl7.org/fhir/http.html#patch)
+ [Especificação do patch FHIR R4 FHIRPath ](https://hl7.org/fhir/fhirpatch.html)
+ [RFC 6902 - Correção JSON](https://datatracker.ietf.org/doc/html/rfc6902#section-4)
+ [RFC 6901 - Ponteiro JSON](https://datatracker.ietf.org/doc/html/rfc6901)
# 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:
+ `_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).
### 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\$1PROGRESS” |
| 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.
# Excluindo um recurso FHIR
A `delete` interação FHIR remove um recurso FHIR existente de um armazenamento de dados. HealthLake Para obter informações adicionais, consulte a [https://hl7.org/fhir/R4/http.html#delete](https://hl7.org/fhir/R4/http.html#delete)documentação da API **FHIR R4 RESTful **.
**Para excluir um recurso FHIR**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Determine o tipo de FHIR `Resource` para excluir e coletar o valor associado`id`. Para obter mais informações, consulte [Resource types](reference-fhir-resource-types.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake `region` `datastoreId` e. Inclua também o `Resource` tipo FHIR e seus associados. `id` Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. Envie a solicitação . A `delete` interação FHIR usa uma `DELETE` 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 `curl` exemplo a seguir remove um `Patient` recurso FHIR existente de um armazenamento de HealthLake dados. Para ver o exemplo inteiro, role até o botão **Copiar**.
------
#### [ SigV4 ]
Autorização SigV4
```
curl --request DELETE \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id' \
--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'
```
O servidor retorna um código de status `204` HTTP confirmando que o recurso foi removido do armazenamento de HealthLake dados. Se uma solicitação de exclusão falhar, você receberá um código de status HTTP em `400` série indicando por que a solicitação falhou.
------
#### [ 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).
------
#### [ AWS Console ]
1. Faça login na página [Executar consulta](https://console.aws.amazon.com/healthlake/home#/crud) no HealthLake console.
2. Na seção **Configurações da consulta**, faça as seguintes seleções.
+ **ID do armazenamento de dados** — escolha um ID do armazenamento de dados para gerar uma sequência de caracteres de consulta.
+ **Tipo de consulta** — escolha`Delete`.
+ **Tipo de recurso** — escolha o tipo de [recurso FHIR a ser excluído](reference-fhir-resource-types.md).
+ **ID do recurso** — insira o ID do recurso FHIR.
3. Selecione **Executar consulta**.
------
## Excluindo recursos do FHIR com base nas condições
A exclusão condicional é particularmente útil quando você não sabe o ID específico do recurso FHIR, mas tem outras informações de identificação sobre o recurso que deseja excluir.
A exclusão condicional permite que você exclua um recurso existente com base nos critérios de pesquisa e não no ID lógico do FHIR. Quando o servidor processa a solicitação de exclusão, ele executa uma pesquisa usando recursos de pesquisa padrão para o tipo de recurso para resolver uma única ID lógica para a solicitação.
### Como funciona a exclusão condicional
**A ação do servidor depende de quantas correspondências ele encontra:**
1. **Sem resultados**: o servidor tenta uma exclusão normal e responde adequadamente (404 Não encontrado para recurso inexistente, 204 Sem conteúdo para recurso já excluído)
1. **Uma partida**: o servidor executa uma exclusão normal no recurso correspondente
1. **Várias correspondências**: retorna um erro 412 Precondition Failed indicando que os critérios do cliente não foram seletivos o suficiente
### Cenários de resposta
AWS HealthLake processa operações de exclusão condicional com os seguintes padrões de resposta:
**Operações bem-sucedidas**
+ Quando seus critérios de pesquisa identificam com sucesso um único recurso ativo, o sistema retorna **204 Sem conteúdo** após concluir a exclusão, assim como as operações de exclusão padrão.
**Exclusão condicional baseada em ID**
Ao realizar a exclusão condicional `id` com base em parâmetros adicionais (`createdAt``tag`, ou`_lastUpdated`):
+ **204 Sem conteúdo: o** recurso já foi excluído
+ **404 Não encontrado**: o recurso não existe
+ **409 Conflito**: o ID corresponde, mas outros parâmetros não coincidem
**Non-ID-Based Exclusão condicional**
Quando não `id` é fornecido ou ao usar parâmetros diferentes de `createdAt``tag`, ou`_lastUpdated`:
+ **404 Não encontrado**: Nenhuma correspondência encontrada
**Situações de conflito**
Vários cenários resultam em 412 respostas de falha na condição prévia:
+ Vários recursos correspondem aos seus critérios de pesquisa (critérios não específicos o suficiente)
+ Conflitos de versão ao usar ETag cabeçalhos com `If-Match`
+ Atualizações de recursos que ocorrem entre as operações de pesquisa e exclusão
**Exemplo de exclusão condicional bem-sucedida**
O exemplo a seguir exclui um recurso do paciente com base em critérios específicos:
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?name=peter&birthdate=2000-01-01&phone=1234567890
```
Essa solicitação exclui um recurso do paciente em que:
+ O nome é “peter”
+ A data de nascimento é 1º de janeiro de 2000
+ O número de telefone é 1234567890
**Práticas recomendadas**
1. Use critérios de pesquisa específicos para evitar várias correspondências e evitar 412 erros.
1. Considere ETag cabeçalhos para controle de versão quando necessário para lidar com modificações simultâneas.
1. Lide com as respostas de erro de forma adequada:
+ Para 404: Refine seus critérios de pesquisa
+ Para 412: torne os critérios mais específicos ou resolva conflitos de versão
1. Prepare-se para conflitos temporais em ambientes de alta simultaneidade, nos quais os recursos podem ser modificados entre as operações de pesquisa e exclusão.
# Idempotência e concorrência
## Chaves de idempotência
AWS HealthLake suporta chaves de idempotência para `POST` operações de FHIR, fornecendo um mecanismo robusto para garantir a integridade dos dados durante a criação de recursos. Ao incluir um UUID exclusivo como chave de idempotência no cabeçalho da solicitação, os aplicativos de saúde podem garantir que cada recurso FHIR seja criado exatamente uma vez, mesmo em cenários que envolvam instabilidade de rede ou novas tentativas automáticas.
Esse recurso é particularmente crucial para sistemas de saúde em que registros médicos duplicados podem ter consequências graves. Quando uma solicitação é recebida com a mesma chave de idempotência de uma solicitação anterior, HealthLake retornará o recurso original em vez de criar uma duplicata. Por exemplo, isso pode ocorrer durante um ciclo de repetição ou devido a pipelines de solicitação redundantes. O uso da chave de idempotência permite manter HealthLake a consistência dos dados e, ao mesmo tempo, fornecer uma experiência perfeita para aplicativos clientes que lidam com problemas de conectividade intermitentes.
### Implementação
```
POST //Patient
x-amz-fhir-idempotency-key: 123e4567-e89b-12d3-a456-426614174000
{
"resourceType": "Patient",
"name": [...]
}
```
### Cenários de resposta
Primeira solicitação (201 criada)
+ Novo recurso criado com sucesso
+ A resposta inclui ID do recurso
Solicitação duplicada (409 Conflito)
+ Mesma chave de idempotência detectada
+ Recurso original devolvido
+ Nenhum novo recurso criado
Solicitação inválida (400 solicitações inválidas)
+ UUID malformado
+ Campos obrigatórios ausentes
### Práticas recomendadas
+ Gere UUID exclusivo para cada criação de novo recurso
+ Armazene as chaves de idempotência para a lógica de repetição
+ Use um formato de chave consistente: recomendado o UUID v4
+ Implemente em aplicativos clientes que lidam com a criação de recursos
**nota**
Esse recurso é particularmente valioso para sistemas de saúde que exigem uma precisão rigorosa dos dados e evitam registros médicos duplicados.
## ETag na AWS HealthLake
AWS HealthLake usa ETags para controle otimista de simultaneidade em recursos do FHIR, fornecendo um mecanismo confiável para gerenciar modificações simultâneas e manter a consistência dos dados. An ETag é um identificador exclusivo que representa uma versão específica de um recurso, funcionando como um sistema de controle de versão por meio de cabeçalhos HTTP. Ao ler ou modificar recursos, os aplicativos podem ser usados ETags para evitar substituições não intencionais e garantir a integridade dos dados, especialmente em cenários com possíveis atualizações simultâneas.
### Exemplo de implementação
```
// Initial Read
GET /fhir/Patient/123
Response:
ETag: W/"1"
// Update with If-Match
PUT /fhir/Patient/123
If-Match: W/"1"
{resource content}
// Create with If-None-Match
PUT /fhir/Patient/123
If-None-Match: *
{resource content}
// Succeeds only if resource doesn't exist
// Fails with 412 if resource exists
```
### Cenários de resposta
Operação bem-sucedida (200 OK ou 204 sem conteúdo)
+ ETag corresponde à versão atual
+ A operação prossegue conforme o planejado
Conflito de versão (falha na pré-condição 412)
+ ETag não corresponde à versão atual
+ Atualização rejeitada para evitar perda de dados
### Práticas recomendadas
+ Incluir ETags em todas as operações de atualização e exclusão
+ Implemente a lógica de repetição para lidar com conflitos de versão
+ Use If-None-Match: \$1 para create-if-not-exists cenários
+ Sempre verifique o ETag frescor antes das modificações
Esse sistema de controle de concorrência é essencial para manter a integridade dos dados de saúde, especialmente em ambientes com vários usuários ou sistemas acessando e modificando os mesmos recursos.