Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Gestione delle risorse FHIR in AWS HealthLake
Utilizza le interazioni dell' RESTful API FHIR R4 per gestire le risorse FHIR in un archivio dati. HealthLake Le sezioni seguenti descrivono tutte le interazioni RESTful API FHIR R4 HealthLake supportate e disponibili per la gestione delle risorse FHIR. Per informazioni sulle funzionalità dell'archivio HealthLake dati e sulle parti della specifica FHIR supportate, vedere. [Dichiarazione di capacità FHIR R4 per AWS HealthLake](reference-fhir-capability-statement.md)
**Nota**
Le interazioni FHIR elencate in questo capitolo sono realizzate in conformità allo standard HL7 FHIR R4 per lo scambio di dati sanitari. Poiché sono rappresentazioni dei servizi HL7 FHIR, non vengono offerti tramite e. AWS CLI AWS SDKs Per ulteriori informazioni, consulta [RESTful API nella documentazione dell'API](https://hl7.org/fhir/R4/http.html) **FHIR RESTful R4**.
La tabella seguente elenca le interazioni FHIR R4 supportate da. AWS HealthLake Per informazioni sui tipi di *risorse FHIR supportati* da HealthLake, vedere. [Tipi di risorse](reference-fhir-resource-types.md)
**Interazioni FHIR R4 supportate da AWS HealthLake**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/healthlake/latest/devguide/managing-fhir-resources.html)
**Topics**
+ [Creazione di una risorsa FHIR](managing-fhir-resources-create.md)
+ [Leggere una risorsa FHIR](managing-fhir-resources-read.md)
+ [Leggere la cronologia delle risorse FHIR](managing-fhir-resources-read-history.md)
+ [Aggiornamento di una risorsa FHIR](managing-fhir-resources-update.md)
+ [Modifica delle risorse con l'operazione PATCH](managing-fhir-resources-patch.md)
+ [Raggruppamento di risorse FHIR](managing-fhir-resources-bundle.md)
+ [Eliminazione di una risorsa FHIR](managing-fhir-resources-delete.md)
+ [Idempotenza e concorrenza](managing-fhir-resources-idempotency.md)
# Creazione di una risorsa FHIR
L'`create`interazione FHIR crea una nuova risorsa FHIR in un HealthLake archivio dati. Per ulteriori informazioni, consulta la documentazione dell'[https://hl7.org/fhir/R4/http.html#create](https://hl7.org/fhir/R4/http.html#create)API **FHIR RESTful R4**.
**Per creare una risorsa FHIR**
1. Colleziona HealthLake `region` e `datastoreId` valorizza. Per ulteriori informazioni, consulta [Ottenere le proprietà dell'archivio dati](managing-data-stores-describe.md).
1. Determina il tipo di FHIR `Resource` da creare. Per ulteriori informazioni, consulta [Tipi di risorse](reference-fhir-resource-types.md).
1. Costruisci un URL per la richiesta utilizzando i valori raccolti per HealthLake `region` e. `datastoreId` Includi anche il `Resource` tipo FHIR da creare. Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
```
POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource
```
1. Costruisci un corpo JSON per la richiesta, specificando i dati FHIR per la nuova risorsa. Ai fini di questa procedura, stiamo usando una `Patient` risorsa FHIR, quindi salva il file con nome. `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. Inviare la richiesta . L'`create`interazione FHIR utilizza una `POST` richiesta con autorizzazione [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) o SMART on FHIR. Gli esempi seguenti creano una `Patient` risorsa FHIR HealthLake utilizzando curl o la Console. HealthLake Per visualizzare un intero esempio, scorri il pulsante **Copia**.
------
#### [ SigV4 ]
Autorizzazione 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 ]
Esempio di autorizzazione SMART on FHIR per il tipo di dati [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html).
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
#### [ AWS Console ]
**Nota**
[La HealthLake console supporta solo l'autorizzazione SigV4.AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)
1. Accedi alla pagina [Esegui interrogazione](https://console.aws.amazon.com/healthlake/home#/crud) sulla Console. HealthLake
2. Nella sezione **Impostazioni della query**, effettua le seguenti selezioni.
+ **Data Store ID**: scegli un ID del data store per generare una stringa di query.
+ **Tipo di query**: scegli`Create`.
+ **Tipo di risorsa**: scegli il [tipo di risorsa](reference-fhir-resource-types.md) FHIR da creare.
+ **Corpo della richiesta**: crea un corpo JSON per la richiesta, specificando i dati FHIR per la nuova risorsa.
3. Scegli **Esegui query**.
------
**Configurazione del livello di convalida per la creazione di risorse**
Quando si crea una risorsa FHIR, è possibile specificare facoltativamente un'intestazione `x-amzn-healthlake-fhir-validation-level` HTTP per configurare un livello di convalida per la risorsa. AWS HealthLake attualmente supporta i seguenti livelli di convalida:
+ `strict`: Le risorse vengono convalidate in base all'elemento del profilo della risorsa o alla specifica R4 se non è presente alcun profilo. Questo è il livello di convalida predefinito per. AWS HealthLake
+ `structure-only`: Le risorse vengono convalidate rispetto a R4, ignorando i profili di riferimento.
+ `minimal`: Le risorse vengono convalidate minimamente, ignorando alcune regole R4. Le risorse che non superano i controlli di struttura richiesti search/analytics verranno aggiornate per includere un avviso per l'audit.
Le risorse create con il livello di convalida minimo possono essere inserite in un Datastore nonostante la mancata convalida richiesta per l'indicizzazione della ricerca. In questo caso, le risorse verranno aggiornate per includere un'estensione specifica di Healthlake per documentare tali errori:
```
{
"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.\"}]}"
}
```
Inoltre, la seguente intestazione di risposta HTTP verrà inclusa con il valore «true»:
```
x-amzn-healthlake-validation-issues : true
```
**Nota**
I dati inseriti che presentano un formato errato secondo la specifica R4 potrebbero non essere ricercabili come previsto se sono presenti questi errori.
# Leggere una risorsa FHIR
L'`read`interazione FHIR legge lo stato corrente di una risorsa in un HealthLake archivio dati. Per ulteriori informazioni, consulta la documentazione dell'[https://hl7.org/fhir/R4/http.html#read](https://hl7.org/fhir/R4/http.html#read)API **FHIR RESTful R4**.
**Per leggere una risorsa FHIR**
1. Colleziona HealthLake `region` e `datastoreId` valorizza. Per ulteriori informazioni, consulta [Ottenere le proprietà dell'archivio dati](managing-data-stores-describe.md).
1. Determina il tipo di FHIR `Resource` per leggere e raccogliere il `id` valore associato. Per ulteriori informazioni, consulta [Tipi di risorse](reference-fhir-resource-types.md).
1. Costruisci un URL per la richiesta utilizzando i valori raccolti per HealthLake `region` e. `datastoreId` Includi anche il `Resource` tipo FHIR e il relativo associato. `id` Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. Inviare la richiesta . L'`read`interazione FHIR utilizza una `GET` richiesta con autorizzazione [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) o SMART on FHIR. L'`curl`esempio seguente legge lo stato corrente di una risorsa `Patient` FHIR in. HealthLake Per visualizzare l'intero esempio, scorrete il pulsante **Copia**.
------
#### [ SigV4 ]
Autorizzazione 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 ]
Esempio di autorizzazione SMART on FHIR per il tipo di dati [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html).
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
#### [ AWS Console ]
1. Accedi alla pagina [Esegui query](https://console.aws.amazon.com/healthlake/home#/crud) sulla console. HealthLake
2. Nella sezione **Impostazioni della query**, effettua le seguenti selezioni.
+ **Data Store ID**: scegli un ID del data store per generare una stringa di query.
+ **Tipo di query**: scegli`Read`.
+ **Tipo di risorsa**: scegli il [tipo di risorsa](reference-fhir-resource-types.md) FHIR da leggere.
+ **ID risorsa**: immettere l'ID della risorsa FHIR.
3. Scegli **Esegui query**.
------
# Leggere la cronologia delle risorse FHIR
L'`history`interazione FHIR recupera la cronologia di una particolare risorsa FHIR in un archivio dati. HealthLake Utilizzando questa interazione, è possibile determinare in che modo il contenuto di una risorsa FHIR è cambiato nel tempo. È anche utile, in coordinamento con i registri di controllo, per vedere lo stato di una risorsa prima e dopo la modifica. Le interazioni `create` FHIR danno come `delete` risultato una versione storica della risorsa da salvare. `update` Per ulteriori informazioni, vedere la documentazione [https://hl7.org/fhir/R4/http.html#history](https://hl7.org/fhir/R4/http.html#history)dell'API **FHIR R4 RESTful **.
**Nota**
È possibile disattivare tipi di risorse `history` FHIR specifici. Per annullare l'iscrizione, crea un caso utilizzando [AWS Support Center Console](https://console.aws.amazon.com/support/home#/). Per creare il tuo caso, accedi al tuo Account AWS e scegli **Crea caso**.
**Per leggere la cronologia delle risorse FHIR**
1. Colleziona HealthLake `region` e `datastoreId` valorizza. Per ulteriori informazioni, consulta [Ottenere le proprietà dell'archivio dati](managing-data-stores-describe.md).
1. Determina il tipo di FHIR `Resource` per leggere e raccogliere il `id` valore associato. Per ulteriori informazioni, consulta [Tipi di risorse](reference-fhir-resource-types.md).
1. Costruisci un URL per la richiesta utilizzando i valori raccolti per HealthLake `region` e. `datastoreId` Includi anche il `Resource` tipo FHIR, i relativi parametri di ricerca associati `id` e facoltativi. Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id/_history{?[parameters]}
```
**HealthLake parametri di ricerca supportati per l'interazione FHIR `history`**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/healthlake/latest/devguide/managing-fhir-resources-read-history.html)
1. Inviare la richiesta . L'`history`interazione FHIR utilizza una `GET` richiesta con autorizzazione [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) o SMART on FHIR. L'`curl`esempio seguente utilizza il parametro `_count` search per restituire 100 risultati di ricerca storici per pagina per una risorsa FHIR `Patient` in. HealthLake Per visualizzare l'intero esempio, scorri il pulsante **Copia**.
------
#### [ SigV4 ]
Autorizzazione 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 ]
Esempio di autorizzazione SMART on FHIR per il tipo di dati [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html).
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
Il contenuto restituito da un'`history`interazione è contenuto in una risorsa FHIR`Bundle`, con tipo impostato su. `history` Contiene la cronologia delle versioni specificata, ordinata in base alle ultime versioni più vecchie e include le risorse eliminate. Per ulteriori informazioni, vedere la documentazione [https://hl7.org/fhir/R4/bundle.html](https://hl7.org/fhir/R4/bundle.html)di **FHIR R4**.
## Leggere la cronologia delle risorse FHIR specifiche della versione
L'`vread`interazione FHIR esegue una lettura specifica della versione di una risorsa in un archivio dati. HealthLake Utilizzando questa interazione, è possibile visualizzare il contenuto di una risorsa FHIR com'era in un determinato momento del passato.
**Nota**
Se si utilizza l'`history`interazione FHIR *senza*`vread`, restituisce HealthLake sempre la versione più recente dei metadati della risorsa.
HealthLake dichiara il supporto per il controllo delle versioni per ogni risorsa supportata [https://hl7.org/fhir/R4/capabilitystatement-definitions.html#CapabilityStatement.rest.resource.versioning](https://hl7.org/fhir/R4/capabilitystatement-definitions.html#CapabilityStatement.rest.resource.versioning). Tutti gli archivi HealthLake dati includono `Resource.meta.versionId` (`vid`) su tutte le risorse.
Quando `history` l'interazione FHIR è abilitata (per impostazione predefinita per gli archivi dati creati dopo il 25/10/2024 o su richiesta per gli archivi dati più vecchi), la `Bundle` risposta include l'elemento `vid` come parte dell'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) Nell'esempio seguente, viene visualizzato come numero. `vid` `1` Per visualizzare l'esempio completo, vedi Example [bundle/bundle-response](https://build.fhir.org/bundle-response.json.html) (JSON).
```
"response" : {
"status" : "201 Created",
"location" : "Patient/12423/_history/1",
...}
```
**Per leggere la cronologia delle risorse FHIR specifica della versione**
1. Raccolta e valori HealthLake `region`. `datastoreId` Per ulteriori informazioni, consulta [Ottenere le proprietà dell'archivio dati](managing-data-stores-describe.md).
1. Determina il `Resource` tipo di FHIR da leggere e raccogliere i `vid` valori `id` e i valori associati. Per ulteriori informazioni, consulta [Tipi di risorse](reference-fhir-resource-types.md).
1. Costruisci un URL per la richiesta utilizzando i valori raccolti per HealthLake e FHIR. Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id/_history/vid
```
1. Inviare la richiesta . L'`history`interazione FHIR utilizza una `GET` richiesta con autorizzazione [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) o SMART on FHIR. La seguente `vread` interazione restituisce una singola istanza con il contenuto specificato per la `Patient` risorsa FHIR per la versione dei metadati della risorsa specificata da. `vid` Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
------
#### [ SigV4 ]
Autorizzazione 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 ]
Esempio di autorizzazione SMART on FHIR per il tipo di dati [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html).
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
# Aggiornamento di una risorsa FHIR
L'`update`interazione FHIR crea una nuova versione corrente per una risorsa esistente o crea una versione iniziale se non esiste già alcuna risorsa per la determinata risorsa. `id` Per ulteriori informazioni, consulta la [https://hl7.org/fhir/R4/http.html#update](https://hl7.org/fhir/R4/http.html#update)documentazione dell'API **FHIR R4 RESTful **.
**Per aggiornare una risorsa FHIR**
1. Colleziona HealthLake `region` e `datastoreId` valorizza. Per ulteriori informazioni, consulta [Ottenere le proprietà dell'archivio dati](managing-data-stores-describe.md).
1. Determina il tipo di FHIR `Resource` da aggiornare e raccogliere il `id` valore associato. Per ulteriori informazioni, consulta [Tipi di risorse](reference-fhir-resource-types.md).
1. Costruisci un URL per la richiesta utilizzando i valori raccolti per HealthLake `region` e. `datastoreId` Includi anche il `Resource` tipo FHIR e il relativo associato. `id` Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
```
PUT https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. Costruisci un `JSON` corpo per la richiesta, specificando gli aggiornamenti dei dati FHIR da effettuare. Ai fini di questa procedura, salva il file con nome. `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. Inviare la richiesta . L'`update`interazione FHIR utilizza una `PUT` richiesta con autorizzazione [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) o SMART on FHIR. L'`curl`esempio seguente aggiorna una `Patient` risorsa in. HealthLake Per visualizzare l'intero esempio, scorri il pulsante **Copia**.
------
#### [ SigV4 ]
Autorizzazione 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
```
La richiesta restituirà un codice di stato `200` HTTP se una risorsa esistente viene *aggiornata* o un codice di stato `201` HTTP se viene creata una nuova risorsa.
------
#### [ SMART on FHIR ]
Esempio di autorizzazione SMART on FHIR per il tipo di [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)dati.
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
#### [ AWS Console ]
1. Accedi alla pagina [Esegui query](https://console.aws.amazon.com/healthlake/home#/crud) sulla console. HealthLake
2. Nella sezione **Impostazioni della query**, effettua le seguenti selezioni.
+ **Data Store ID**: scegli un ID del data store per generare una stringa di query.
+ **Tipo di query**: scegli`Update (PUT)`.
+ **Tipo di risorsa**: scegli il [tipo di risorsa](reference-fhir-resource-types.md) FHIR da aggiornare o creare.
+ **Corpo della richiesta**: crea un corpo JSON per la richiesta, specificando i dati FHIR con cui aggiornare la risorsa.
3. Scegli **Esegui query**.
------
## Aggiornamento delle risorse FHIR in base alle condizioni
L'aggiornamento condizionale consente di aggiornare una risorsa esistente in base ad alcuni criteri di ricerca di identificazione, anziché tramite FHIR logico. `id` Quando il server elabora l'aggiornamento, esegue una ricerca utilizzando le funzionalità di ricerca standard per il tipo di risorsa, con l'obiettivo di risolvere una singola logica `id` per la richiesta.
L'azione intrapresa dal server dipende dal numero di corrispondenze trovate:
+ **Nessuna corrispondenza, non `id` fornita nel corpo della richiesta**: il server crea la risorsa FHIR.
+ **Nessuna corrispondenza, `id` fornita e la risorsa non esiste già con`id`: Il** server considera l'interazione come un'interazione Update as Create.
+ **Nessuna corrispondenza, `id` fornita e già esistente**: il server rifiuta l'aggiornamento con un `409 Conflict` errore.
+ **Una corrispondenza, nessuna risorsa `id` fornita OPPURE (risorsa `id` fornita e corrisponde alla risorsa trovata)**: il server esegue l'aggiornamento rispetto alla risorsa corrispondente come sopra dove, se la risorsa è stata aggiornata, il server DEVE restituire un`200 OK`.
+ **One Match, risorsa `id` fornita ma non corrispondente alla risorsa trovata**: il server restituisce un `409 Conflict` errore che indica che la specifica dell'ID del client era un problema, preferibilmente con un `OperationOutcome`
+ **Corrispondenze multiple**: Il server restituisce un `412 Precondition Failed` errore che indica che i criteri del client non erano sufficientemente selettivi, preferibilmente con un OperationOutcome
L'esempio seguente aggiorna una `Patient` risorsa il cui nome è peter, la data di nascita è il 1° gennaio 2000 e il numero di telefono è 1234567890.
```
PUT https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?name=peter&birthdate=2000-01-01&phone=1234567890
```
## Configurazione del livello di convalida per gli aggiornamenti delle risorse
Quando si aggiorna una risorsa FHIR, è possibile facoltativamente specificare un'intestazione `x-amzn-healthlake-fhir-validation-level` HTTP per configurare un livello di convalida per la risorsa. AWS HealthLake attualmente supporta i seguenti livelli di convalida:
+ `strict`: Le risorse vengono convalidate in base all'elemento del profilo della risorsa o alla specifica R4 se non è presente alcun profilo. Questo è il livello di convalida predefinito per. AWS HealthLake
+ `structure-only`: Le risorse vengono convalidate rispetto a R4, ignorando i profili di riferimento.
+ `minimal`: Le risorse vengono convalidate minimamente, ignorando alcune regole R4. Le risorse che non superano i controlli di struttura richiesti search/analytics verranno aggiornate per includere un avviso per l'audit.
Le risorse aggiornate con il livello di convalida minimo possono essere inserite in un Datastore nonostante la convalida non riuscita richiesta per l'indicizzazione della ricerca. In questo caso, le risorse verranno aggiornate per includere un'estensione specifica di Healthlake per documentare tali errori:
```
{
"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.\"}]}"
}
```
Inoltre, la seguente intestazione di risposta HTTP verrà inclusa con il valore «true»:
```
x-amzn-healthlake-validation-issues : true
```
**Nota**
Tieni presente che i dati inseriti in formato non corretto secondo la specifica R4 potrebbero non essere ricercabili come previsto se sono presenti questi errori.
# Modifica delle risorse con l'operazione PATCH
AWS HealthLake supporta l'operazione PATCH per le risorse FHIR, che consente di modificare le risorse prendendo di mira elementi specifici da aggiungere, sostituire o eliminare senza aggiornare l'intera risorsa. Questa operazione è particolarmente utile quando è necessario:
+ Effettuare aggiornamenti mirati a risorse di grandi dimensioni
+ Riduci l'utilizzo della larghezza di banda di rete
+ Esegui modifiche atomiche su elementi di risorse specifici
+ Riduci al minimo il rischio di sovrascrivere le modifiche simultanee
+ Aggiorna le risorse come parte dei flussi di lavoro in batch e delle transazioni
## Formati PATCH supportati
AWS HealthLake supporta due formati PATCH standard:
### Patch JSON (RFC 6902)
Utilizza la sintassi JSON Pointer per indirizzare gli elementi in base alla loro posizione nella struttura delle risorse.
**Tipo di contenuto:** `application/json-patch+json`
### FHIRPath Patch (specifica FHIR R4)
Utilizza FHIRPath le espressioni per indirizzare gli elementi in base al loro contenuto e alle loro relazioni, fornendo un approccio nativo FHIR all'applicazione delle patch.
**Tipo di contenuto:** `application/fhir+json`
## Utilizzo
### Operazioni PATCH dirette
L'operazione PATCH può essere richiamata direttamente sulle risorse FHIR utilizzando il metodo HTTP PATCH:
```
PATCH [base]/[resource-type]/[id]{?_format=[mime-type]}
```
### PATCH in pacchetti
Le operazioni PATCH possono essere incluse come voci all'interno di pacchetti FHIR di tipo `batch` oppure `transaction` consentono di combinare le operazioni di patch con altre interazioni FHIR (creazione, lettura, aggiornamento, eliminazione) in un'unica richiesta.
+ **Pacchetti di transazioni: tutte le** voci hanno esito positivo o negativo in modo atomico
+ **Pacchetti Batch**: ogni voce viene elaborata in modo indipendente
## Formato di patch JSON
### Operazioni supportate
| Operation | Description |
| --- | --- |
| add | Aggiungi un nuovo valore alla risorsa |
| remove | Rimuove un valore dalla risorsa |
| replace | Sostituisci un valore esistente nella risorsa |
| move | Rimuovi un valore da una posizione e aggiungilo a un'altra |
| copy | Copia un valore da una posizione all'altra |
| test | Verifica che un valore nella posizione di destinazione sia uguale a un valore specificato |
### Sintassi del percorso
JSON Patch utilizza la sintassi JSON Pointer (RFC 6901):
| Esempio di percorso | Description |
| --- | --- |
| /name/0/family | Elemento della famiglia del nome |
| /telecom/- | Aggiungi all'array di telecomunicazioni |
| /active | Elemento attivo a livello di root |
| /address/0/line/1 | Seconda riga del primo indirizzo |
### Esempi
**Richiesta diretta di patch JSON con più operazioni**
```
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"
}
]
```
**Richiesta diretta di patch JSON con singola operazione**
```
PATCH [base]/Patient/example
Content-Type: application/json-patch+json
[
{
"op": "replace",
"path": "/active",
"value": false
}
]
```
**Patch JSON in bundle**
Usa una risorsa binaria contenente il payload della patch JSON con codifica base64:
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [{
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJhZGQiLCJwYXRoIjoiL2JpcnRoRGF0ZSIsInZhbHVlIjoiMTk5MC0wMS0wMSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/123"
}
}]
}
```
## FHIRPath Formato della patch
### Operazioni supportate
| Operation | Description |
| --- | --- |
| add | Aggiungere un nuovo elemento a una risorsa |
| insert | Inserisce un elemento in una posizione specifica in un elenco |
| delete | Rimuove un elemento da una risorsa |
| replace | Sostituisci il valore di un elemento esistente |
| move | Riordina gli elementi all'interno di un elenco |
### Sintassi del percorso
FHIRPath La patch utilizza FHIRPath espressioni che supportano:
+ Accesso **basato su indici**: `Patient.name[0]`
+ **Filtraggio** con: `where()` `Patient.name.where(use = 'official')`
+ **Logica booleana:** `Patient.telecom.where(system = 'phone' and use = 'work')`
+ **Funzioni di sottoimpostazione**:, `first()` `last()`
+ **Controlli di esistenza**:`exists()`, `count()`
+ Navigazione **polimorfa:** `Observation.value`
### Esempi
**Richiesta diretta di patch FHIRPath**
```
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 inclusa nel pacchetto**
Usa una risorsa Parameters come risorsa di ingresso con`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"
}
}]
}
```
## Intestazioni di richiesta
| Header | Richiesto | Descrizione |
| --- | --- | --- |
| Content-Type | Sì | application/json-patch\$1jsonper JSON Patch o application/fhir\$1json per FHIRPath Patch |
| If-Match | No | Aggiornamento condizionale specifico della versione utilizzando ETag |
## Risposta di esempio
L'operazione restituisce la risorsa aggiornata con le informazioni sulla nuova versione:
```
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
L'operazione PATCH:
+ Convalida la sintassi della patch in base alle specifiche appropriate (RFC 6902 per JSON Patch, FHIR R4 per Patch) FHIRPath
+ Applica le operazioni in modo atomico: tutte le operazioni hanno esito positivo o negativo
+ Aggiorna l'ID della versione della risorsa e crea una nuova voce della cronologia
+ Conserva la risorsa originale nella cronologia prima di applicare le modifiche
+ Convalida i vincoli delle risorse FHIR dopo l'applicazione delle patch
+ Supporta gli aggiornamenti condizionali utilizzando l'intestazione If-Match con ETag
## Gestione errori
L'operazione gestisce le seguenti condizioni di errore:
+ **400 Bad Request**: sintassi della patch non valida (richiesta non conforme o documento di patch non valido)
+ **404 Not Found: risorsa non trovata** (l'ID specificato non esiste)
+ **409 Conflitto: conflitto** di versione (vengono forniti aggiornamenti simultanei o ID di versione non corrente)
+ **422 Entità non processabile**: le operazioni di patch non possono essere applicate agli elementi di risorsa specificati
## Riepilogo delle capacità
| Funzionalità | Patch JSON | FHIRPath Patch |
| --- | --- | --- |
| Tipo di contenuto | application/json-patch\$1json | application/fhir\$1json |
| Formato del percorso | Puntatore JSON (RFC 6901) | FHIRPath espressioni |
| API Patch diretta | Supportata | Supportata |
| Batch del pacchetto | Supportato (tramite binario) | Supportato (tramite parametri) |
| Transazione in bundle | Supportato (tramite binario) | Supportato (tramite parametri) |
| Operazioni | aggiungere, rimuovere, sostituire, spostare, copiare, testare | aggiungere, inserire, eliminare, sostituire, spostare |
## Limitazioni
+ Le operazioni PATCH condizionali che utilizzano condizioni di ricerca non sono supportate
+ La patch JSON nei bundle deve utilizzare risorse binarie con contenuto codificato in base64
+ FHIRPath Le patch nei bundle devono utilizzare risorse Parameters
## Risorse aggiuntive
Per ulteriori informazioni sulle operazioni PATCH, consulta:
+ [Documentazione FHIR R4 PATCH](https://hl7.org/fhir/http.html#patch)
+ [Specifiche della patch FHIR R4 FHIRPath ](https://hl7.org/fhir/fhirpatch.html)
+ [RFC 6902 - Patch JSON](https://datatracker.ietf.org/doc/html/rfc6902#section-4)
+ [RFC 6901 - Puntatore JSON](https://datatracker.ietf.org/doc/html/rfc6901)
# Raggruppamento di risorse FHIR
Un FHIR `Bundle` è un contenitore per una raccolta di risorse FHIR in. AWS HealthLake AWS HealthLake supporta due tipi di pacchetti con comportamenti di elaborazione diversi.
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction)i pacchetti elaborano ogni risorsa in modo indipendente. Se una risorsa fallisce, le risorse rimanenti possono comunque avere successo. Ogni operazione viene elaborata singolarmente e l'elaborazione continua anche quando alcune operazioni falliscono. Utilizzate pacchetti in batch per operazioni di massa in cui è accettabile un successo parziale, come il caricamento di più cartelle cliniche di pazienti non correlate.
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction)i pacchetti elaborano tutte le risorse in modo atomico come una singola unità. Tutte le operazioni relative alle risorse hanno esito positivo oppure nessuna di AWS HealthLake esse viene eseguita. Utilizza i pacchetti di transazioni quando hai bisogno di un'integrità referenziale garantita tra le risorse correlate, ad esempio per creare un paziente con osservazioni e condizioni correlate in cui tutti i dati devono essere registrati insieme.
**Differenze tra pacchetti batch e pacchetti di transazioni**
| Funzionalità | Archiviazione | Transaction |
| --- | --- | --- |
| Modello di elaborazione | Ogni operazione riesce o fallisce indipendentemente. | Tutte le operazioni hanno esito positivo o negativo come singola unità atomica. |
| Gestione degli errori | L'elaborazione continua anche se le singole operazioni falliscono. | L'intero pacchetto fallisce se una singola operazione fallisce. |
| Ordine di esecuzione | L'ordine di esecuzione non è garantito. | Le operazioni vengono elaborate nell'ordine specificato. |
| Integrità referenziale | Non applicato in tutte le operazioni. | Applicato per le risorse referenziate localmente all'interno del pacchetto. |
| Ideale per | Operazioni in blocco in cui il successo parziale è accettabile. | Risorse correlate che devono essere create o aggiornate insieme. |
È possibile raggruppare risorse FHIR dello stesso tipo o di tipo diverso e queste possono includere una combinazione di operazioni FHIR, come,`create`, `read``update`, `delete` e. `patch` **Per ulteriori informazioni, vedere [Resource Bundle](https://hl7.org/fhir/R4/Bundle) nella documentazione di FHIR R4.**
Di seguito sono riportati alcuni esempi di casi d'uso per ogni tipo di pacchetto.
Pacchetti Batch
+ Carica più cartelle cliniche dei pazienti non correlate da diverse strutture durante la sincronizzazione notturna dei dati.
+ Carica in blocco la cronologia dei farmaci, in cui alcuni dati potrebbero presentare problemi di convalida.
+ Carica dati di riferimento, ad esempio organizzazioni e professionisti, laddove i singoli errori non influiscano sulle altre voci.
Pacchetti di transazioni
+ Crea un paziente con le relative osservazioni e condizioni durante il ricovero al pronto soccorso, in cui tutti i dati devono essere registrati insieme.
+ Aggiorna l'elenco dei farmaci del paziente e le relative informazioni sulle allergie, che devono rimanere coerenti.
+ Registra un incontro completo con il paziente, le osservazioni, le procedure e le informazioni di fatturazione come un'unica unità atomica.
**Importante**
Sia i pacchetti batch che quelli di transazione utilizzano la stessa `Bundle` struttura di risorse. L'unica differenza è il valore del `type` campo.
L'esempio seguente mostra un pacchetto di transazioni con più tipi di risorse e operazioni.
```
{
"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"
}
}
]
}
```
## Raggruppamento di risorse FHIR come entità indipendenti
**Raggruppare le risorse FHIR come entità indipendenti**
1. Raccogli HealthLake `region` e `datastoreId` valorizza. Per ulteriori informazioni, consulta [Ottenere le proprietà dell'archivio dati](managing-data-stores-describe.md).
1. Costruisci un URL per la richiesta utilizzando i valori raccolti per HealthLake `region` e`datastoreId`. *Non* specificate un tipo di risorsa FHIR nell'URL. Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
```
POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
```
1. Costruisci un corpo JSON per la richiesta, specificando ogni verbo HTTP come parte degli elementi. `method` L'esempio seguente utilizza un'interazione `batch` di tipo con la `Bundle` risorsa per creare nuove risorse. `Patient` `Medication` Tutte le sezioni obbligatorie vengono commentate di conseguenza. Ai fini di questa procedura, salva il file con nome. `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. Inviare la richiesta . Il tipo di `Bundle` batch FHIR utilizza una `POST` richiesta con autorizzazione [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) o SMART on FHIR. Il seguente esempio di codice utilizza lo strumento da riga di `curl` comando a scopo dimostrativo.
------
#### [ SigV4 ]
Autorizzazione 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 ]
Esempio di autorizzazione SMART on FHIR per il tipo di dati [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html).
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
Il server restituisce una risposta che mostra le `Medication` risorse `Patient` e le risorse create a seguito della `Bundle` richiesta di tipo batch.
## Condizionale PUTs nei pacchetti
AWS HealthLake supporta gli aggiornamenti condizionali all'interno dei pacchetti utilizzando i seguenti parametri di query:
+ `_id`(autonomo)
+ `_id`in combinazione con uno dei seguenti:
+ `_tag`
+ `_createdAt`
+ `_lastUpdated`
Quando si utilizza il condizionale PUTs nei pacchetti, AWS HealthLake valuta i parametri della query rispetto alle risorse esistenti e interviene in base ai risultati della corrispondenza.
**Comportamento di aggiornamento condizionale**
| Scenario | Stato HTTP | Azione intrapresa |
| --- | --- | --- |
| Risorsa senza ID fornito | 201 Creato | Crea sempre una nuova risorsa. |
| Risorsa con nuovo ID (nessuna corrispondenza) | 201 Creato | Crea una nuova risorsa con l'ID specificato. |
| Risorsa con ID esistente (corrispondenza singola) | 200 OK | Aggiorna la risorsa corrispondente. |
| Risorsa con ID esistente (è stato rilevato un conflitto) | 409 Conflitto | Restituisce un errore. Non viene apportata alcuna modifica. |
| Risorsa con ID esistente (ID non corrispondente) | 400 Richiesta non valida | Restituisce un errore. Non viene apportata alcuna modifica. |
| Risorse multiple soddisfano le condizioni | 412 Precondizione non riuscita | Restituisce un errore. Non viene apportata alcuna modifica. |
Nel seguente esempio, abbinato a un aggiornamento condizionale, la `Patient` risorsa con ID FHIR si `476` aggiorna solo se la condizione `_lastUpdated=lt2025-04-20` è soddisfatta.
```
{
"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"
}
}
]
}
```
## Raggruppamento delle risorse FHIR come singola entità
**Per raggruppare le risorse FHIR come un'unica entità**
1. Raccogli HealthLake `region` e `datastoreId` valorizza. Per ulteriori informazioni, consulta [Ottenere le proprietà dell'archivio dati](managing-data-stores-describe.md).
1. Costruisci un URL per la richiesta utilizzando i valori raccolti per HealthLake `region` e`datastoreId`. Includi il tipo di risorsa FHIR `Bundle` come parte dell'URL. Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
```
POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Bundle
```
1. Costruisci un corpo JSON per la richiesta, specificando le risorse FHIR da raggruppare. L'esempio seguente raggruppa due risorse in. `Patient` HealthLake Ai fini di questa procedura, salva il file con nome`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. Inviare la richiesta . Il tipo di `Bundle` documento FHIR utilizza una `POST` richiesta con protocollo di [AWS firma Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Il seguente esempio di codice utilizza lo strumento da riga di `curl` comando a scopo dimostrativo.
------
#### [ SigV4 ]
Autorizzazione 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 ]
Esempio di autorizzazione SMART on FHIR per il tipo di dati [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html).
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
Il server restituisce una risposta che mostra due `Patient` risorse create a seguito della richiesta del `Bundle` tipo di documento.
## Configurazione del livello di convalida per i pacchetti
Quando raggruppate le risorse FHIR, potete facoltativamente specificare un'intestazione `x-amzn-healthlake-fhir-validation-level` HTTP per configurare un livello di convalida per la risorsa. Questo livello di convalida verrà impostato per tutte le richieste di creazione e aggiornamento all'interno del pacchetto. AWS HealthLake attualmente supporta i seguenti livelli di convalida:
+ `strict`: Le risorse vengono convalidate in base all'elemento del profilo della risorsa o alla specifica R4 se non è presente alcun profilo. Questo è il livello di convalida predefinito per. AWS HealthLake
+ `structure-only`: Le risorse vengono convalidate rispetto a R4, ignorando i profili di riferimento.
+ `minimal`: Le risorse vengono convalidate minimamente, ignorando alcune regole R4. Le risorse che non superano i controlli di struttura richiesti search/analytics verranno aggiornate per includere un avviso per l'audit.
Le risorse associate al livello di convalida minimo possono essere inserite in un Datastore nonostante la convalida non riuscita richiesta per l'indicizzazione della ricerca. In questo caso, le risorse verranno aggiornate per includere un'estensione specifica di Healthlake per documentare tali errori e le voci contenute nella risposta del Bundle includeranno le seguenti risorse: OperationOutcome
```
{
"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."
}
]
}
}
}
]
}
```
Inoltre, la seguente intestazione di risposta HTTP verrà inclusa con il valore «true»:
```
x-amzn-healthlake-validation-issues : true
```
**Nota**
Tieni presente che i dati inseriti in formato non corretto secondo la specifica R4 potrebbero non essere ricercabili come previsto se questi errori sono presenti.
## Supporto limitato per il tipo «message» di tipo Bundle
HealthLake fornisce un supporto limitato per il tipo FHIR Bundle `message` attraverso un processo di conversione interno. Questo supporto è progettato per scenari in cui i pacchetti di messaggi non possono essere riformattati all'origine, come l'importazione di feed ADT (Admission, Discharge, Transfer) da sistemi ospedalieri preesistenti.
**avvertimento**
Questa funzionalità richiede un elenco esplicito degli AWS account consentiti e non applica la semantica dei messaggi FHIR R4 o l'integrità referenziale. Contatta l' AWS assistenza per richiedere l'attivazione del tuo account prima di utilizzare i pacchetti di messaggi.
### Principali differenze rispetto all'elaborazione standard dei messaggi
+ **Pacchetti di messaggi** (specifica FHIR): la prima immissione deve essere una `MessageHeader` che faccia riferimento ad altre risorse. Alle risorse mancano i singoli `request` oggetti e l' MessageHeader evento determina le azioni di elaborazione.
+ **HealthLake Elaborazione**: converte i pacchetti di messaggi in pacchetti batch assegnando automaticamente le operazioni PUT a ciascuna risorsa immessa. Le risorse vengono elaborate in modo indipendente senza applicare la semantica dei messaggi o l'integrità referenziale.
### Limitazioni importanti
+ Le regole di elaborazione specifiche dei messaggi FHIR R4 non vengono applicate
+ Nessuna integrità transazionale tra le risorse
+ I riferimenti tra le risorse non vengono convalidati
+ Richiede un elenco esplicito degli account consentiti
### Esempio di struttura del pacchetto di messaggi
```
{
"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**
Ogni risorsa viene archiviata in modo indipendente come se fosse inviata tramite singole operazioni PUT. Se è richiesta la semantica completa della messaggistica FHIR o la convalida dell'integrità referenziale, preelabora i pacchetti di messaggi o implementa la convalida a livello di applicazione prima dell'invio.
## Transazioni di bundle asincrone
AWS HealthLake supporta il `Bundle` tipo asincrono `transaction` che consente di inviare transazioni con un massimo di 500 risorse. Quando invii una transazione asincrona, la mette in HealthLake coda per l'elaborazione e restituisce immediatamente un URL di polling. Puoi utilizzare questo URL per controllare lo stato e recuperare la risposta. Questo segue lo schema del pacchetto [asincrono FHIR](https://hl7.org/fhir/async-bundle.html).
**Quando utilizzare le transazioni asincrone**
+ È necessario inviare più di 100 risorse (limite sincrono) in una singola transazione.
+ Desiderate evitare di bloccare l'applicazione in attesa del completamento dell'elaborazione della transazione.
+ È necessario elaborare volumi elevati di risorse correlate con un throughput migliore.
**Importante**
I risultati dei sondaggi sono disponibili per 90 giorni dopo il completamento della transazione. Dopo questo periodo di 90 giorni, l'URL del sondaggio non restituisce più risultati. Progetta la tua integrazione per recuperare e archiviare i risultati all'interno di questa finestra.
**Nota**
Il `Bundle` tipo sincrono `transaction` continua a supportare fino a 100 risorse ed è la modalità di elaborazione predefinita. Se invii un `Bundle` tipo `transaction` con più di 100 risorse senza l'`Prefer: respond-async`intestazione, HealthLake restituisce un `422 Unprocessable Entity` errore. I pacchetti con tipo non `batch` sono supportati per l'elaborazione asincrona: solo i tipi `transaction` possono essere inviati in modo asincrono (con un massimo `Bundle` di 500 operazioni).
### Invio di una transazione asincrona
Per inviare una transazione asincrona, invia una `POST` richiesta all'endpoint del data store con l'intestazione. `Prefer: respond-async` Il pacchetto deve avere un tipo. `transaction` I pacchetti con tipo non `batch` sono supportati per l'elaborazione asincrona dei pacchetti.
HealthLake esegue le convalide iniziali del pacchetto al momento dell'invio. Se la convalida ha esito positivo, HealthLake restituisce HTTP 202 Accepted con un'intestazione di `content-location` risposta che contiene l'URL del polling.
**Per inviare un tipo asincrono `Bundle` `transaction`**
1. Invia una `POST` richiesta all'endpoint del HealthLake data store.
```
POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
```
1. Costruisci un corpo JSON per la richiesta con il tipo di bundle. `transaction` Ai fini di questa procedura, salva il file con nome. `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. Invia la richiesta con l'`Prefer: respond-async`intestazione. Il tipo di `Bundle` transazione FHIR utilizza una `POST` richiesta con autorizzazione [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) o SMART on FHIR. Il seguente esempio di codice utilizza lo strumento da riga di `curl` comando a scopo dimostrativo.
------
#### [ SigV4 ]
Autorizzazione 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 ]
Esempio di autorizzazione SMART on FHIR per il tipo di dati [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html).
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
1. In caso di invio riuscito, il server restituisce HTTP 202 Accepted. L'intestazione della `content-location` risposta contiene l'URL del sondaggio. Il corpo della risposta è una `OperationOutcome` risorsa.
```
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"
]
}
]
}
```
### Sondaggio sullo stato delle transazioni
Dopo aver inviato una transazione asincrona, utilizza l'URL di polling dall'intestazione della `content-location` risposta per verificare lo stato della transazione. Invia una `GET` richiesta all'URL del sondaggio.
**Nota**
Per gli archivi dati compatibili con SMART on FHIR, il token di autorizzazione deve includere `read` le autorizzazioni sul tipo di `Transaction` risorsa per verificare lo stato della transazione. Per ulteriori informazioni sugli ambiti SMART on FHIR, vedere. [SMART su ambiti FHIR OAuth 2.0 supportati da HealthLake](reference-smart-on-fhir-oauth-scopes.md)
Invia una `GET` richiesta all'URL del sondaggio. L'esempio seguente utilizza lo strumento da `curl` riga di comando.
------
#### [ SigV4 ]
Autorizzazione 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 ]
Autorizzazione SMART su FHIR. Il token di autorizzazione deve includere `read` le autorizzazioni sul tipo di `Transaction` risorsa.
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId' \
--header 'Authorization: Bearer $SMART_ACCESS_TOKEN' \
--header 'Accept: application/json'
```
------
La tabella seguente descrive le possibili risposte.
**Codici di risposta ai sondaggi**
| Stato HTTP | Significato | Corpo di risposta |
| --- | --- | --- |
| 202 Accettato | La transazione è in coda | OperationOutcomecon diagnostica «INVIATA» |
| 202 Accettato | La transazione è in fase di elaborazione | OperationOutcomecon diagnostica «IN\$1PROGRESS» |
| 200 OK | Transazione completata con successo | Bundlecon tipo transaction-response |
| 4xx/5xx | Transazione fallita | OperationOutcomecon dettagli sull'errore |
Gli esempi seguenti mostrano ogni tipo di risposta.
**Transazione in coda (202)**
```
{
"resourceType": "OperationOutcome",
"id": "transactionId",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "SUBMITTED"
}
]
}
```
**Elaborazione delle transazioni (202)**
```
{
"resourceType": "OperationOutcome",
"id": "transactionId",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "IN_PROGRESS"
}
]
}
```
**Transazione completata (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"
}
}
]
}
```
**Transazione non riuscita (4xx/5xx)**
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "exception",
"diagnostics": "Transaction failed: conflict detected on resource Patient/example-id"
}
]
}
```
### Ordine di elaborazione
I pacchetti di tipo asincrono vengono messi in coda ma non `transaction` vengono elaborati in un rigoroso ordine di invio. HealthLake ottimizza l'elaborazione in base alla capacità disponibile e al carico di sistema.
**Importante**
Non dipendono dal fatto che le transazioni vengano elaborate nell'ordine in cui sono state inviate. Ad esempio, se invii la Transazione A alle 10:00 e la Transazione B alle 10:01, la Transazione B potrebbe essere completata prima della Transazione A. Progetta la tua applicazione per:
Gestire out-of-order il completamento.
Utilizza l'URL del sondaggio per tracciare ogni transazione in modo indipendente.
Implementa il sequenziamento a livello di applicazione se l'ordine è importante per il tuo caso d'uso.
### Quote e limitazioni
Le quote e i limiti di velocità seguenti si applicano alle transazioni asincrone.
**Quote di transazione asincrone**
| Quota | Valore | Regolabile |
| --- | --- | --- |
| Numero massimo di operazioni per transazione asincrona | 500 | No |
| Numero massimo di transazioni in sospeso per archivio dati | 500 | Sì |
+ Le transazioni asincrone condividono gli stessi limiti di velocità API definiti in. [Service Quotas](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas)
+ Il polling sullo stato delle transazioni condivide gli stessi limiti di velocità API delle operazioni read (`GET`) sulle risorse FHIR.
+ Se viene raggiunto il limite di transazioni in sospeso, gli invii successivi restituiscono un errore fino al completamento delle transazioni esistenti.
### Gestione degli errori
Per un pacchetto di «transazioni», tutte le risorse FHIR contenute nel pacchetto vengono elaborate come un'operazione atomica. Tutte le risorse dell'operazione devono avere esito positivo, altrimenti non viene elaborata alcuna operazione nel pacchetto.
Gli errori si dividono in due categorie: gli errori di invio che vengono HealthLake restituiti in modo sincrono e gli errori di elaborazione recuperati tramite il polling.
**Errori di invio**
HealthLake convalida il pacchetto al momento dell'invio e restituisce gli errori in modo sincrono prima che la transazione venga messa in coda. Gli errori di invio includono errori di convalida delle risorse FHIR non validi, tipi di risorse non supportati, superamento del limite di 500 operazioni e utilizzo dell'intestazione con pacchetti batch. `Prefer: respond-async` Se è stato raggiunto il limite di transazioni in sospeso per l'archivio dati, restituisce un. HealthLake `ThrottlingException` Quando si verifica un errore di invio, la transazione non verrà messa in coda.
**Errori di elaborazione**
Gli errori di elaborazione si verificano dopo che la transazione è stata messa in coda e vengono restituiti tramite l'URL di polling. Questi includono i conflitti di transazione, in cui un'altra operazione ha modificato una risorsa che fa parte della transazione, e gli errori del server durante l'elaborazione. Quando si verifica un errore di elaborazione, non viene effettuata alcuna modifica delle risorse della transazione. L'URL di polling restituirà un `OperationOutcome` con i dettagli dell'errore.
# Eliminazione di una risorsa FHIR
L'`delete`interazione FHIR rimuove una risorsa FHIR esistente da un HealthLake archivio dati. Per ulteriori informazioni, consulta la documentazione dell'[https://hl7.org/fhir/R4/http.html#delete](https://hl7.org/fhir/R4/http.html#delete)API **FHIR RESTful R4**.
**Per eliminare una risorsa FHIR**
1. Raccogli HealthLake `region` e `datastoreId` valorizza. Per ulteriori informazioni, consulta [Ottenere le proprietà dell'archivio dati](managing-data-stores-describe.md).
1. Determina il tipo di FHIR `Resource` da eliminare e raccogli il `id` valore associato. Per ulteriori informazioni, consulta [Tipi di risorse](reference-fhir-resource-types.md).
1. Costruisci un URL per la richiesta utilizzando i valori raccolti per HealthLake `region` e. `datastoreId` Includi anche il `Resource` tipo FHIR e il relativo associato. `id` Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante **Copia**.
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. Inviare la richiesta . L'`delete`interazione FHIR utilizza una `DELETE` richiesta con autorizzazione [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) o SMART on FHIR. L'`curl`esempio seguente rimuove una `Patient` risorsa FHIR esistente da un HealthLake archivio dati. Per visualizzare l'intero esempio, scorrete il pulsante **Copia**.
------
#### [ SigV4 ]
Autorizzazione 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'
```
Il server restituisce un codice di stato `204` HTTP che conferma che la risorsa è stata rimossa dall' HealthLake archivio dati. Se una richiesta di eliminazione ha esito negativo, riceverai una `400` serie di codici di stato HTTP che indica il motivo per cui la richiesta non è riuscita.
------
#### [ SMART on FHIR ]
Esempio di autorizzazione SMART on FHIR per il tipo di [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)dati.
```
{
"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\"]}"
}
```
Il chiamante può assegnare le autorizzazioni nella lambda di autorizzazione. Per ulteriori informazioni, consulta [OAuth Cannocchiali 2.0](reference-smart-on-fhir-oauth-scopes.md).
------
#### [ AWS Console ]
1. Accedi alla pagina [Esegui query](https://console.aws.amazon.com/healthlake/home#/crud) sulla console. HealthLake
2. Nella sezione **Impostazioni della query**, effettua le seguenti selezioni.
+ **Data Store ID**: scegli un ID del data store per generare una stringa di query.
+ **Tipo di query**: scegli`Delete`.
+ **Tipo di risorsa**: scegli il [tipo di risorsa](reference-fhir-resource-types.md) FHIR da eliminare.
+ **ID risorsa**: immettere l'ID della risorsa FHIR.
3. Scegli **Esegui query**.
------
## Eliminazione delle risorse FHIR in base a condizioni
L'eliminazione condizionale è particolarmente utile quando non si conosce l'ID specifico della risorsa FHIR ma si hanno altre informazioni di identificazione sulla risorsa che si desidera eliminare.
L'eliminazione condizionale consente di eliminare una risorsa esistente in base a criteri di ricerca anziché in base all'ID FHIR logico. Quando il server elabora la richiesta di eliminazione, esegue una ricerca utilizzando funzionalità di ricerca standard per il tipo di risorsa per risolvere un singolo ID logico per la richiesta.
### Come funziona l'eliminazione condizionale
**L'azione del server dipende dal numero di corrispondenze che trova:**
1. **Nessuna corrispondenza**: il server tenta un'eliminazione ordinaria e risponde in modo appropriato (404 Not Found per una risorsa inesistente, 204 Nessun contenuto per una risorsa già eliminata)
1. **Una risposta: il server esegue un'eliminazione ordinaria sulla risorsa corrispondente**
1. **Corrispondenze multiple**: restituisce un errore 412 Precondition Failed che indica che i criteri del client non erano sufficientemente selettivi
### Scenari di risposta
AWS HealthLake gestisce le operazioni di eliminazione condizionale con i seguenti modelli di risposta:
**Operazioni riuscite**
+ Quando i criteri di ricerca identificano correttamente una singola risorsa attiva, il sistema restituisce **204 No Content** dopo aver completato l'eliminazione, proprio come le operazioni di eliminazione standard.
**Eliminazione condizionale basata su ID**
Quando si esegue l'eliminazione condizionale in base `id` a parametri aggiuntivi (`createdAt`,`tag`, o): `_lastUpdated`
+ **204 Nessun contenuto**: la risorsa è già stata eliminata
+ **404 Not Found**: La risorsa non esiste
+ **409 Conflitto**: l'ID corrisponde ma gli altri parametri non corrispondono
**Non-ID-Based Eliminazione condizionale**
Quando non `id` viene fornito o quando si utilizzano parametri diversi da `createdAt``tag`, oppure`_lastUpdated`:
+ **404 non trovato**: Nessuna corrispondenza trovata
**Situazioni di conflitto**
Diversi scenari generano 412 risposte non riuscite alla condizione preliminare:
+ Diverse risorse corrispondono ai criteri di ricerca (criteri non sufficientemente specifici)
+ La versione è in conflitto quando si utilizzano ETag intestazioni con `If-Match`
+ Aggiornamenti delle risorse che si verificano tra le operazioni di ricerca ed eliminazione
**Esempio di eliminazione condizionale riuscita**
L'esempio seguente elimina una risorsa Patient in base a criteri specifici:
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?name=peter&birthdate=2000-01-01&phone=1234567890
```
Questa richiesta elimina una risorsa Patient in cui:
+ Il nome è «peter»
+ La data di nascita è il 1 gennaio 2000
+ Il numero di telefono è 1234567890
**Best practice**
1. Utilizza criteri di ricerca specifici per evitare corrispondenze multiple ed evitare 412 errori.
1. Prendi in considerazione le ETag intestazioni per il controllo della versione quando necessario per gestire le modifiche simultanee.
1. Gestisci le risposte agli errori in modo appropriato:
+ Per 404: perfeziona i criteri di ricerca
+ Per 412: rendi i criteri più specifici o risolvi i conflitti di versione
1. Preparatevi ai conflitti temporali in ambienti ad alta concorrenza in cui le risorse possono essere modificate tra le operazioni di ricerca ed eliminazione.
# Idempotenza e concorrenza
## Chiavi di idempotenza
AWS HealthLake supporta le chiavi di idempotenza per le `POST` operazioni FHIR, fornendo un meccanismo robusto per garantire l'integrità dei dati durante la creazione delle risorse. Includendo un UUID univoco come chiave di idempotenza nell'intestazione della richiesta, le applicazioni sanitarie possono garantire che ogni risorsa FHIR venga creata esattamente una volta, anche in scenari che prevedono instabilità di rete o tentativi automatici.
Questa funzionalità è particolarmente importante per i sistemi sanitari in cui la duplicazione delle cartelle cliniche potrebbe avere gravi conseguenze. Quando una richiesta viene ricevuta con la stessa chiave di idempotenza di una richiesta precedente, HealthLake restituirà la risorsa originale invece di crearne una duplicata. Ad esempio, ciò potrebbe verificarsi durante un ciclo di tentativi o a causa di pipeline di richieste ridondanti. L'utilizzo della chiave di idempotenza consente di mantenere la coerenza dei dati fornendo HealthLake al contempo un'esperienza senza interruzioni per le applicazioni client che gestiscono problemi di connettività intermittenti.
### Implementazione
```
POST //Patient
x-amz-fhir-idempotency-key: 123e4567-e89b-12d3-a456-426614174000
{
"resourceType": "Patient",
"name": [...]
}
```
### Scenari di risposta
Prima richiesta (201 create)
+ Nuova risorsa creata con successo
+ La risposta include l'ID della risorsa
Richiesta duplicata (409 Conflict)
+ È stata rilevata la stessa chiave di idempotenza
+ Risorsa originale restituita
+ Nessuna nuova risorsa creata
Richiesta non valida (400 Richiesta errata)
+ UUID malformato
+ Campi obbligatori mancanti
### Best practice
+ Genera un UUID univoco per ogni nuova creazione di risorse
+ Memorizza le chiavi di idempotenza per la logica dei tentativi
+ Usa un formato di chiave coerente: UUID v4 consigliato
+ Implementa nelle applicazioni client per la gestione della creazione di risorse
**Nota**
Questa funzionalità è particolarmente utile per i sistemi sanitari che richiedono una rigorosa precisione dei dati e impediscono la duplicazione delle cartelle cliniche.
## ETag in AWS HealthLake
AWS HealthLake utilizza ETags un controllo ottimistico della concorrenza nelle risorse FHIR, fornendo un meccanismo affidabile per gestire le modifiche simultanee e mantenere la coerenza dei dati. An ETag è un identificatore univoco che rappresenta una versione specifica di una risorsa, che funziona come un sistema di controllo della versione tramite intestazioni HTTP. Durante la lettura o la modifica delle risorse, le applicazioni possono utilizzarle ETags per prevenire sovrascritture involontarie e garantire l'integrità dei dati, in particolare in scenari con potenziali aggiornamenti simultanei.
### Esempio di implementazione
```
// 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
```
### Scenari di risposta
Operazione riuscita (200 OK o 204 Nessun contenuto)
+ ETag corrisponde alla versione corrente
+ L'operazione procede come previsto
Conflitto di versione (condizione preliminare 412 non riuscita)
+ ETag non corrisponde alla versione corrente
+ Aggiornamento rifiutato per prevenire la perdita di dati
### Best practice
+ ETags Includi in tutte le operazioni di aggiornamento ed eliminazione
+ Implementa la logica dei tentativi per la gestione dei conflitti di versione
+ Usa If-None-Match: \$1 per gli scenari create-if-not-exists
+ Verifica sempre la ETag freschezza prima delle modifiche
Questo sistema di controllo simultaneo è essenziale per mantenere l'integrità dei dati sanitari, specialmente in ambienti con più utenti o sistemi che accedono e modificano le stesse risorse.