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 delle 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 bundle 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. Utilizza i pacchetti batch per operazioni in blocco in cui è accettabile un successo parziale, ad esempio il caricamento di più cartelle cliniche non correlate.

Transactioni bundle elaborano tutte le risorse in modo atomico come una singola unità. O tutte le operazioni sulle risorse hanno esito positivo o non AWS HealthLake ne esegue nessuna. Utilizza i pacchetti di transazioni quando hai bisogno di garantire l'integrità referenziale tra le risorse correlate, ad esempio creando un paziente con osservazioni correlate e condizioni in cui tutti i dati devono essere registrati insieme.

È possibile raggruppare risorse FHIR dello stesso tipo o di tipi diversi e possono includere una combinazione di operazioni FHIR, ad esempiocreate, 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 delle risorse FHIR come entità indipendenti

Raggruppare le risorse FHIR come entità indipendenti

PUT condizionali in pacchetti

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

Quando si utilizzano PUT condizionali nei pacchetti, AWS HealthLake valuta i parametri della query rispetto alle risorse esistenti e interviene in base ai risultati della corrispondenza.

Nel seguente pacchetto di esempio con 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 in un'unica entità

Per raggruppare le risorse FHIR come un'unica entità

Configurazione del livello di convalida per i pacchetti

Quando si raggruppano le risorse FHIR, è possibile specificare facoltativamente 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 incluse nel livello di convalida minimo possono essere inserite in un Datastore nonostante la convalida fallita richiesta per l'indicizzazione delle ricerche. In questo caso, le risorse verranno aggiornate per includere un'estensione specifica di Healthlake per documentare tali errori e le voci all'interno della risposta del pacchetto 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 della risposta HTTP verrà inclusa con il valore «true»:

x-amzn-healthlake-validation-issues : true

Supporto limitato per il tipo di pacchetto «messaggio»

HealthLake fornisce un supporto limitato per il tipo di pacchetto FHIR message attraverso un processo di conversione interno. Questo supporto è progettato per scenari in cui i pacchetti di messaggi non possono essere riformattati all'origine, ad esempio l'acquisizione di feed ADT (Admission, Discharge, Transfer) dai sistemi ospedalieri precedenti.

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 in 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 verificare 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 per il 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 di polling.

Per inviare una transazione asincrona di tipo Bundle

Sondaggio sullo stato della transazione

Dopo aver inviato una transazione asincrona, utilizza l'URL di polling nell'intestazione della content-location risposta per verificare lo stato della transazione. Invia una GET richiesta all'URL di polling.

Invia una GET richiesta all'URL del polling. 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 on 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 fallita (4xx/5xx)

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

Elaborazione dell'ordine

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 del sistema.

Quote e limitazioni

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

Gestione degli errori

Per un pacchetto «transazione», tutte le risorse FHIR contenute nel pacchetto vengono elaborate come un'operazione atomica. Tutte le risorse dell'operazione devono avere esito positivo, altrimenti nessuna operazione del pacchetto viene elaborata.

Gli errori si dividono in due categorie: errori di invio che vengono HealthLake restituiti in modo sincrono ed errori di elaborazione recuperati tramite 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 bundle batch. Prefer: respond-async Se è stato raggiunto il limite di transazioni in sospeso per il data store, 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 vengono apportate modifiche alle risorse della transazione. L'URL di polling restituirà un messaggio OperationOutcome con i dettagli dell'errore.