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à. # Applicazione di patch su larga scala con `$bulk-patch` AWS HealthLake supporta l'`$bulk-patch`operazione per applicare le operazioni di patch a un gran numero di risorse FHIR in modo asincrono. È possibile scegliere come target un elenco specifico di risorse in base all'ID o tutte le risorse di un determinato tipo all'interno di un datastore. Con questa operazione, è possibile modificare le risorse su larga scala senza aggiornare ogni risorsa singolarmente. L'`$bulk-patch`operazione è particolarmente utile quando è necessario eseguire le seguenti operazioni: + Applica tag o etichette di metadati alle risorse di un intero datastore + Aggiorna campi specifici su migliaia o milioni di risorse + Esegui correzioni o arricchimenti di massa dei dati + Applica le modifiche relative alla conformità a tutti i tipi di risorse + Migra o standardizza gli elementi di dati su larga scala **Nota** L'`$bulk-patch`operazione applica la stessa patch a ogni risorsa mirata. Per modificare una singola risorsa, utilizzare l'operazione PATCH. Per ulteriori informazioni, consulta [Modifica delle risorse con l'operazione PATCH](managing-fhir-resources-patch.md). La patch in blocco applica ogni patch atomicamente a ciascuna risorsa. Ogni risorsa ha successo o ha esito negativo in modo indipendente. Le risorse che vengono eliminate o modificate dopo l'invio del lavoro vengono saltate anziché patchate, per evitare di sovrascrivere le modifiche simultanee. ## Utilizzo L'operazione è asincrona. `$bulk-patch` Per iniziare un lavoro, invia una richiesta POST: ``` POST [base]/$bulk-patch ``` Per verificare lo stato di un lavoro, usa l'endpoint di descrizione: ``` GET [base]/$bulk-patch/{jobId} ``` Per iniziare l'`$bulk-patch`operazione, procedi come segue: 1. Inviate una richiesta di patch in blocco che specifichi le risorse e le operazioni di patch di destinazione. La risposta include un ID del lavoro. 1. Esegui il polling dello stato del lavoro utilizzando l'endpoint di descrizione finché lo stato non è `COMPLETED` o. `COMPLETED_WITH_ERRORS` 1. Esamina il riepilogo del lavoro per vedere quante risorse sono riuscite, fallite o sono state ignorate. ## Parameters L'`$bulk-patch`operazione supporta i seguenti parametri. | Parametro | Tipo | Campo obbligatorio | Descrizione | | --- | --- | --- | --- | | resourceType | stringa | Sì | Il tipo di risorsa FHIR da applicare la patch, ad esempio Patient oObservation. | | resourceIds | stringa [] | No | L'elenco degli ID delle risorse da applicare alla patch. Quando si omette questo parametro, l'operazione applica una patch a tutte le risorse del tipo specificato. | | operations | oggetto | Sì | Le operazioni di patch da applicare. Accetta un array JSON Patch o una risorsa FHIR PatchParameters. | | clientToken | stringa | No | User-provided token utilizzato per garantire l'idempotenza. La reinvio di un lavoro con lo stesso token client restituisce il lavoro esistente invece di crearne uno nuovo. | | validationLevel | stringa | No | Il livello di convalida FHIR applicato durante l'aggiornamento di ogni risorsa. I valori accettati sono strict (impostazione predefinita)structure-only, e. minimal | ## Destinazione delle risorse È possibile indirizzare le risorse in due modalità. **Modalità tipo di risorsa** In modalità tipo di risorsa, l'operazione corregge tutte le risorse di un tipo specifico nel datastore. ``` { "resourceType": "Patient", "operations": { ... } } ``` **modalità Resource IDs** In modalità Resource IDs, l'operazione corregge un elenco specifico di risorse in base all'ID. Tutti gli ID delle risorse devono essere dello stesso tipo e corrispondere al `resourceType` parametro. Il formato può essere un riferimento completo (`[resourceType]/[id]`) o solo l'ID (`[id]`). L'elenco può contenere fino a 50.000 ID di risorse. ``` { "resourceType": "Patient", "resourceIds": ["Patient/001", "Patient/002", "Patient/003"], "operations": { ... } } ``` ## Formati di patch supportati L'`$bulk-patch`operazione supporta la sintassi JSON Patch (RFC 6902) e FHIR Patch (). FHIRPath-based Utilizza lo stesso set di operazioni supportate e la stessa sintassi dell'operazione PATCH sincrona. Per ulteriori informazioni, consulta [Modifica delle risorse con l'operazione PATCH](managing-fhir-resources-patch.md). ## Esempio di avvio di un processo di patch in blocco L'esempio seguente invia un patch job in blocco che aggiunge un tag di conformità a `Patient` risorse specifiche utilizzando FHIR Patch. **Richiesta di esempio** ``` POST [base]/$bulk-patch Content-Type: application/json { "resourceType": "Patient", "resourceIds": ["patient-1", "patient-2", "patient-3"], "validationLevel": "strict", "clientToken": "unique-idempotency-token-123", "operations": { "resourceType": "Parameters", "parameter": [ { "name": "operation", "part": [ {"name": "type", "valueCode": "add"}, {"name": "path", "valueString": "Patient.meta"}, {"name": "name", "valueString": "tag"}, {"name": "value", "valueCoding": { "system": "http://example.org/compliance", "code": "2026-audit-complete" }} ] } ] } } ``` **Risposta di esempio** ``` { "datastoreId": "datastoreId", "jobId": "jobId", "jobStatus": "SUBMITTED" } ``` ## Sondaggio in blocco dello stato del processo di patch Dopo aver inviato un job, esegui il polling sullo stato del job per monitorarne l'avanzamento e recuperare i risultati. Il processo passa da `SUBMITTED` e`IN_PROGRESS`, quindi allo stato terminale o. `COMPLETED` `COMPLETED_WITH_ERRORS` ``` GET [base]/$bulk-patch/{jobId} ``` L'esempio seguente mostra una risposta per un processo in corso. ``` { "datastoreId": "datastoreId", "jobId": "jobId", "status": "IN_PROGRESS", "submittedTime": "2026-09-14T06:53:31.429Z", "summary": { "estimatedResourceCount": 1000 } } ``` **Nota** `estimatedResourceCount`È esatto per la modalità ID delle risorse ed è uguale alla dimensione dell'elenco inviato. Per la modalità tipo di risorsa, il numero effettivo di risorse elaborate potrebbe differire leggermente perché le risorse possono essere create o eliminate mentre il lavoro è in esecuzione. Quando il processo raggiunge lo stato terminale, la risposta di descrizione include un riepilogo del conteggio delle risorse completate, non riuscite e saltate. Se alcune risorse non sono riuscite o sono state ignorate, la risposta elenca i motivi in e. `failedResources` `skippedResources` Lo stato del lavoro è `COMPLETED_WITH_ERRORS` quando si verificano degli errori, che si tratti di un errore del cliente o di un errore del server. La dimensione delle risposte limita gli `skippedResources` elenchi `failedResources` e, pertanto, potrebbero essere troncati. Controlla `failedResourcesTruncated` e `skippedResourcesTruncated` determina se l'elenco completo è incluso. ``` { "datastoreId": "datastoreId", "jobId": "jobId", "status": "COMPLETED_WITH_ERRORS", "submittedTime": "2026-09-14T06:53:31.429Z", "endTime": "2026-09-14T07:08:34.930Z", "summary": { "estimatedResourceCount": 1000, "totalResourcesProcessed": 1000, "succeeded": 985, "failedWithCustomerError": 5, "failedWithServerError": 0, "skipped": 10 }, "failedResources": [ { "resourceId": "Patient/patient-101", "message": "FHIR resource in payload failed FHIR validation rules." } ], "skippedResources": [ { "resourceId": "Patient/patient-201", "message": "Resource was modified after job submission" }, { "resourceId": "Patient/patient-202", "message": "Resource was deleted." }, { "resourceId": "Patient/patient-203", "message": "Resource not found." } ], "failedResourcesTruncated": false, "skippedResourcesTruncated": false } ``` ## Motivi comuni ignorati L'operazione ignora una risorsa quando rientra nell'ambito ma non può applicare una patch alla risorsa perché il suo stato è cambiato tra l'invio e l'elaborazione del lavoro. Le risorse ignorate non sono considerate errori. Di seguito sono riportati i motivi più comuni per cui una risorsa viene ignorata. + **La risorsa è stata modificata dopo l'invio del lavoro**: la risorsa è stata aggiornata da un'altra operazione dopo che il patch job collettivo ne ha acquisito la versione al momento dell'invio. In rari casi, una risorsa a cui è stata applicata correttamente la patch potrebbe essere segnalata come ignorata con il motivo modificato dopo l'invio del lavoro. Ciò è previsto e potrebbe verificarsi a una velocità molto bassa (1 su milioni di risorse). + **La risorsa è stata eliminata dopo l'invio del lavoro**: la risorsa è stata eliminata dopo l'invio del lavoro (modalità tipo di risorsa). Non è garantito che tutte le risorse eliminate vengano visualizzate nell'elenco ignorato. Se una risorsa viene eliminata prima dell'inizio dell'elaborazione, viene completamente esclusa dall'ambito del lavoro e non viene riflessa nei risultati del lavoro. + **La risorsa è stata eliminata**: l'ID della risorsa specificato è eliminato (modalità ID delle risorse). + **Risorsa non trovata**: l'ID della risorsa specificato non esiste (solo in modalità ID risorsa). ## Errori comuni dei clienti Una risorsa ha esito negativo quando l'operazione non è in grado di applicare la patch a causa di un problema con la risorsa o con le operazioni di patch. Le risorse non funzionanti includono un messaggio di errore con dettagli diagnostici. Di seguito sono riportati gli errori più comuni dei clienti. + **Errore di convalida FHIR**: la risorsa patchata non supera la convalida FHIR. La patch in blocco applica la convalida FHIR sull'intera risorsa patchata, non solo sui campi modificati. Questo errore può verificarsi quando la patch produce un valore di campo non valido o quando la risorsa contiene già campi non conformi al FHIR. Utilizzate il `validationLevel` parametro per controllare il rigore della convalida. + **Errore nell'applicazione della patch**: le operazioni di patch sono incompatibili con la struttura delle risorse, ad esempio la sostituzione di un campo che non esiste o l'aggiunta a un percorso non di matrice. ## Best practice Si consigliano le seguenti procedure consigliate quando si utilizza l'`$bulk-patch`operazione. + **Effettua prima il test con PATCH sincrono. ** AWS HealthLake convalida la sintassi delle operazioni delle patch al momento dell'invio del lavoro e rifiuta i payload non validi in modo sincrono. Tuttavia, le operazioni di patch sintatticamente valide possono comunque fallire in fase di elaborazione se non corrispondono alla struttura sottostante delle risorse archiviate. Comprendete le caratteristiche delle risorse di destinazione e testate le operazioni di patch con l'operazione PATCH sincrona prima di eseguire un patch job collettivo. Questo consente di evitare errori su larga scala. + **Usa i motivi di errore e quelli ignorati per eseguire il debug. ** Rivedi gli `skippedResources` elenchi `failedResources` e nella risposta descrittiva per capire perché le risorse specifiche non sono state corrette. + **Verifica lo stato delle risorse prima di riprovare. ** Le operazioni con le patch non sono idempotenti per natura. L'applicazione della stessa patch due volte può produrre risultati diversi, ad esempio, l'aggiunta di un tag già esistente crea un duplicato. Dopo aver visualizzato le risorse ignorate o non funzionanti, verificate lo stato corrente delle risorse prima di inviare un nuovo processo. ## Autorizzazione L'`$bulk-patch`operazione supporta i seguenti metodi di autorizzazione: + AWS Identity and Access Management (IAM) Signature Version 4 (SIGv4) per l'accesso programmatico. + SMART su FHIR con i seguenti ambiti richiesti: + **Livello di ambito**: sono supportati solo gli ambiti a livello di sistema. L'operazione rifiuta gli ambiti a livello di paziente e utente. + **Tipo di risorsa**: gli ambiti devono corrispondere al tipo di risorsa a cui è destinato il lavoro. + **Operazioni**: gli ambiti richiesti dipendono dalla modalità di lavoro e dalla versione SMART: + **Avvio di un lavoro (modalità tipo di risorsa)**: requisiti `read` e `write` ambiti di SMART v1. I datastore SMART v2 richiedono e ambiti. `search` `update` + **Avvio di un lavoro (modalità Resource IDs)**: requisiti e ambiti di SMART v1. `read` `write` I datastore SMART v2 richiedono e ambiti. `read` `update` + **Descrivi un lavoro**: richiede l'ambito. `read` ## Caratteristiche prestazionali L'`$bulk-patch`operazione è progettata per l'elaborazione di grandi volumi e viene eseguita in modo asincrono. + **Concorrenza**: ogni datastore supporta un massimo di 1 patch job simultaneo di massa. L'operazione mette in coda i job aggiuntivi e li avvia automaticamente al completamento del job corrente. + **Scalabilità**: ogni processo supporta fino a 2 miliardi di risorse. L'operazione rifiuta i lavori che superano questo limite. Questo limite impedisce tempi di elaborazione prolungati, durante i quali molte risorse possono cambiare stato, ed evita che i processi del datastore vengano mantenuti in contemporanea per un periodo prolungato. Utilizza la modalità Resource IDs per partizionare il carico di lavoro. Esempio di risposta quando un processo supera la scala supportata: ``` "status": "COMPLETED_WITH_ERRORS", "message": "The requested bulk patch operation exceeds the supported scale." ``` + **Operazioni parallele**: la patch in blocco non è compatibile con operazioni simultanee di eliminazione, importazione o esportazione in blocco sullo stesso datastore. + **Annullamento**: i lavori di patch in blocco non possono essere annullati dopo l'invio. ## Operazioni correlate + [Modifica delle risorse con l'operazione PATCH](managing-fhir-resources-patch.md)— Single-resource PATCH utilizzando JSON Patch o FHIR Patch. + [Eliminazione dei tipi di risorse con `$bulk-delete`](reference-fhir-operations-bulk-delete.md)— Eliminare tutte le risorse di un tipo specifico. + [Operazioni FHIR R4 $ `per` HealthLake](reference-fhir-operations.md)— Elenco completo delle operazioni supportate.