Utilizzo delle intestazioni Range e partNumber - Amazon Simple Storage Service
Fase 1: configura il punto di accesso Lambda per oggettiFase 2: implementa la gestione di Range o partNumber nella funzione Lambda

Utilizzo delle intestazioni Range e partNumber

Nota

A partire dal 7 novembre 2025, Lambda per oggetti S3 sarà disponibile solo per i clienti esistenti che attualmente utilizzano il servizio e per alcuni partner della Rete dei partner AWS (APN). Se desideri utilizzare il servizio, registrati prima del 7 novembre 2025. Per funzionalità simili a Lambda per oggetti S3, consulta Modifica della disponibilità di Lambda per oggetti Amazon S3.

Quando vengono utilizzati oggetti di grandi dimensioni in Amazon S3 Object Lambda, è possibile utilizzare l'intestazione HTTP Range per scaricare un intervallo di byte specificato da un oggetto. Puoi utilizzare connessioni simultanee ad Amazon S3 per recuperare diversi intervalli di byte all'interno dello stesso oggetto. Puoi inoltre specificare il parametro partNumber (un numero intero compreso tra 1 e 10.000) che esegue una richiesta basata su intervallo per la parte specificata dell'oggetto.

Perché ci sono diversi modi in cui potresti voler gestire una richiesta che include i parametri Range o partNumber, S3 Object Lambda non applica questi parametri all'oggetto trasformato. Invece, la funzione AWS Lambda deve implementare questa funzionalità in base ai requisiti dell'applicazione.

Per utilizzare i parametri Range e partNumber con S3 Object Lambda, procedi come segue:

  • Abilita questi parametri nella configurazione del punto di accesso Lambda per oggetti.

  • Scrivi una funzione Lambda in grado di gestire le richieste contenente questi parametri.

Di seguito viene descritto come realizzarlo.

Fase 1: configura il punto di accesso Lambda per oggetti

Per impostazione predefinita, gli punti di accesso Lambda per oggetti rispondono con un errore con codice di stato HTTP 501 (Not Implemented) a qualsiasi richiesta GetObject o HeadObject contenente un parametro Range o partNumber nelle intestazioni o nei parametri di query.

Per abilitare un punto di accesso Lambda per oggetti ad accettare tali richieste, devi includere GetObject-Range, GetObject-PartNumber, HeadObject-Range o HeadObject-PartNumber nella sezione AllowedFeatures della configurazione del punto di accesso Lambda per oggetti. Per ulteriori informazioni sull'aggiornamento della configurazione del punto di accesso Lambda per oggetti, consulta Creazione di punti di accesso Object Lambda.

Fase 2: implementa la gestione di Range o partNumber nella funzione Lambda

Quando il punto di accesso Lambda per oggetti richiama la funzione Lambda con una richiesta GetObject o HeadObject basata su intervallo, il parametro Range o partNumber è incluso nel contesto dell'evento. La posizione del parametro nel contesto dell'evento dipende dal parametro utilizzato e dal modo in cui è stato incluso nella richiesta originale al punto di accesso Lambda per oggetti, come illustrato nella tabella seguente.

Parametro Posizione del contesto dell'evento

Range (intestazione)

userRequest.headers.Range

Range (parametro di query)

userRequest.url (del parametro di query Range)

partNumber

userRequest.url (del parametro di query partNumber)
Importante

L'URL prefirmato fornito per il punto di accesso Lambda per oggetti non contiene il parametro Range o partNumber della richiesta originale. Consulta le seguenti opzioni su come gestire questi parametri nella funzione AWS Lambda.

Dopo aver estratto il valore Range o partNumber, è possibile adottare uno dei seguenti approcci in base alle esigenze dell'applicazione:

  1. Mappare il valore Range o partNumber richiesto all'oggetto trasformato (consigliato).

    Per gestire le richieste Range o partNumber nel modo più affidabile, procedi come segue:

    • Recupera l'oggetto completo da Amazon S3.

    • Trasforma l'oggetto.

    • Applica i parametri Range o partNumber obbligatori all'oggetto trasformato.

    Per fare ciò, utilizza l'URL prefirmato fornito per recuperare l'intero oggetto da Amazon S3 e quindi elaborare l'oggetto secondo necessità. Per un esempio di funzione Lambda che elabora un parametro Range in questo modo, consulta questo esempio nel repository GitHub di AWS Samples.

  2. Mappatura del Range richiesto all'URL prefirmato URL.

    In alcuni casi, la funzione Lambda può mappare il valore o il Range richiesto direttamente all'URL prefirmato per recuperare solo parte dell'oggetto da Amazon S3. Questo approccio è appropriato solo se la trasformazione soddisfa entrambi i seguenti criteri:

    1. La funzione di trasformazione può essere applicata a intervalli di oggetti parziali.

    2. Applicando il parametro Range prima o dopo la funzione di trasformazione produce lo stesso oggetto trasformato.

    Ad esempio, una funzione di trasformazione che converte tutti i caratteri di un oggetto con codifica ASCII in maiuscolo soddisfa entrambi i criteri precedenti. La trasformazione può essere applicata a una parte di un oggetto e applicando il parametro Range prima della trasformazione si ottiene lo stesso risultato dell'applicazione del parametro dopo la trasformazione.

    Al contrario, una funzione che inverte i caratteri in un oggetto con codifica ASCII non soddisfa questi criteri. Tale funzione soddisfa il criterio 1, poiché può essere applicata a intervalli di oggetti parziali. Tuttavia, non soddisfa il criterio 2, perché l'applicazione del parametro Range prima che la trasformazione raggiunga risultati diversi rispetto all'applicazione del parametro dopo la trasformazione.

    Considera una richiesta di applicare la funzione ai primi tre caratteri di un oggetto con il contenuto abcdefg. L'applicazione del parametro Range prima della trasformazione recupera solo abc e poi inverte i dati, restituendo cba. Ma se il parametro viene applicato dopo la trasformazione, la funzione recupera l'intero oggetto, lo inverte e quindi applica il parametro Range, restituendo gfe. Poiché questi risultati sono diversi, questa funzione non dovrebbe applicare il parametro Range durante il recupero dell'oggetto da Amazon S3. Invece, dovrebbe recuperare l'intero oggetto, eseguire la trasformazione e solo successivamente applicare il parametro Range.

    avvertimento

    In molti casi, l'applicazione del parametro Range o dell'URL prefirmato risulterà in un comportamento imprevisto da parte della funzione Lambda o del client richiedente. A meno che non sia sicuro che la tua applicazione funzioni correttamente quando recuperi solo un oggetto parziale da Amazon S3, ti consigliamo di recuperare e trasformare oggetti completi come descritto in precedenza nell'approccio A.

    Se l'applicazione soddisfa i criteri descritti in precedenza nell'approccio B, è possibile semplificare la funzione AWS Lambda recuperando solo l'intervallo di oggetti richiesto e quindi eseguendo la trasformazione su quell'intervallo.

    Il seguente esempio di codice Java illustra come eseguire le seguenti operazioni:

    • Recuperare l'intestazione Range dalla richiesta GetObject.

    • Aggiungere l'intestazione Range all'URL prefirmato che Lambda può utilizzare per recuperare l'intervallo richiesto da Amazon S3.

    private HttpRequest.Builder applyRangeHeader(ObjectLambdaEvent event, HttpRequest.Builder presignedRequest) {
    var header = event.getUserRequest().getHeaders().entrySet().stream()
            .filter(e -> e.getKey().toLowerCase(Locale.ROOT).equals("range"))
            .findFirst();

    // Add check in the query string itself.
    header.ifPresent(entry -> presignedRequest.header(entry.getKey(), entry.getValue()));
    return presignedRequest;
}