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à.

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.

Batchi 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.

Transactioni 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.

È possibile raggruppare risorse FHIR dello stesso tipo o di tipo diverso e queste possono includere una combinazione di operazioni FHIR, come,create, readupdate, delete e. patch Per ulteriori informazioni, vedere Resource Bundle nella documentazione di FHIR R4.

Di seguito sono riportati alcuni esempi di casi d'uso per ogni tipo di pacchetto.

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

Condizionale PUTs nei pacchetti

AWS HealthLake supporta gli aggiornamenti condizionali all'interno dei pacchetti utilizzando i seguenti parametri di query:

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.

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à

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:

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

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.

Principali differenze rispetto all'elaborazione standard dei messaggi

Limitazioni importanti

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"}
                }
              ]
            }
            

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.

Quando utilizzare le transazioni asincrone

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

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.

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.

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.

Quote e limitazioni

Le quote e i limiti di velocità seguenti si applicano alle transazioni asincrone.

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.