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à.
Scrittura di funzioni Lambda per i punti di accesso Lambda per oggetti S3
Questa sezione descrive in dettaglio come scrivere AWS Lambda funzioni da utilizzare con gli access point Amazon S3 Object Lambda.
Per informazioni sulle end-to-end procedure complete per alcune attività di S3 Object Lambda, consulta quanto segue:
Argomenti
Utilizzo di richieste GetObject
in Lambda
Questa sezione presuppone che il punto di accesso Lambda per oggetti sia configurato per richiamare la funzione Lambda per GetObject
. S3 Object Lambda include l'operazione API Amazon S3 WriteGetObjectResponse
, che consente alla funzione Lambda di fornire dati personalizzati e intestazioni di risposta al chiamante GetObject
.
WriteGetObjectResponse
offre un ampio controllo su codice di stato, intestazioni di risposta e corpo della risposta, in base ai requisiti di elaborazione. È possibile utilizzare WriteGetObjectResponse
per rispondere con l'intero oggetto trasformato, con parti dell'oggetto trasformato o con altre risposte in base al contesto dell'applicazione. Nella sezione seguente sono illustrati esempi univoci di utilizzo dell'operazione API WriteGetObjectResponse
.
-
Esempio 1: risposta con un codice di stato HTTP 403 (Forbidden) (Accesso negato)
-
Esempio 2: Rispondere con un'immagine trasformata
-
Esempio 3: Streaming di contenuto compresso
Esempio 1: risposta con un codice di stato HTTP 403 (Forbidden) (Accesso negato)
È possibile utilizzare WriteGetObjectResponse
per rispondere con il codice di stato HTTP 403 (Non consentito) in base al contenuto dell'oggetto.
Esempio 2: Rispondere con un'immagine trasformata
Durante la trasformazione dell'immagine, è possibile che siano necessari tutti i byte dell'oggetto di fonte prima di poter iniziare a elaborarli. In questo caso, la tua richiesta WriteGetObjectResponse
restituisce l'intero oggetto all'applicazione richiedente in una sola chiamata.
Esempio 3: Streaming di contenuto compresso
Durante la compressione degli oggetti, i dati compressi vengono prodotti in modo incrementale. Di conseguenza, puoi utilizzare la richiesta WriteGetObjectResponse
per restituire i dati compressi non appena sono pronti. Come mostrato in questo esempio, non è necessario conoscere la lunghezza della trasformazione completata.
Nota
Sebbene S3 Object Lambda consente fino a 60 secondi per inviare una risposta completa al chiamante tramite la richiesta WriteGetObjectResponse
, la quantità effettiva di tempo disponibile potrebbe essere inferiore. Ad esempio, il timeout della funzione Lambda potrebbe essere inferiore a 60 secondi. In altri casi, il chiamante potrebbe avere timeout più rigorosi.
Affinché il chiamante originale riceva una risposta diversa dal codice di stato HTTP 500 (Internal Server Error) (Errore interno del server), la chiamata WriteGetObjectResponse
deve essere completata. Se la funzione Lambda restituisce un risultato, eccezionalmente o in altro modo, prima che l'operazione API WriteGetObjectResponse
venga richiamata, il chiamante originale riceverà una risposta 500 (Internal Server Error) (Errore interno del server). Le eccezioni generate durante il tempo necessario per completare la risposta comportano risposte troncate al chiamante. Se la funzione Lambda riceve una risposta con codice di stato HTTP 200 (OK) dalla chiamata API WriteGetObjectResponse
, il chiamante originale ha inviato la richiesta completa. La risposta della funzione Lambda, indipendentemente dal fatto che un'eccezione sia generata o meno, viene ignorata da S3 Object Lambda.
Quando viene richiamata l'operazione API WriteGetObjectResponse
, Amazon S3 richiede il token dell'instradamento e della richiesta dal contesto dell'evento. Per ulteriori informazioni, consulta Formato e utilizzo del contesto degli eventi.
I parametri relativi ai token dell'instradamento e della richiesta sono necessari per collegare la risposta WriteGetObjectResult
al chiamante originale. Sebbene sia sempre opportuno riprovare le risposte 500 (Internal Server Error) (Errore interno del server), è necessario considerare che il token della richiesta è un token monouso e i successivi tentativi di utilizzo possono comportare risposte con codice di stato 400 (Bad Request) (Richiesta non valida). Anche se la chiamata a WriteGetObjectResponse
con i token dell'instradamento e della richiesta non ha bisogno di essere effettuata dalla funzione Lambda richiamata, deve essere effettuata da un'identità nello stesso account. La chiamata deve anche essere completata prima che la funzione Lambda finisca l'esecuzione.
Utilizzo di richieste HeadObject
in Lambda
Questa sezione presuppone che il punto di accesso Lambda per oggetti sia configurato per richiamare la funzione Lambda per HeadObject
. Lambda riceverà un payload JSON contenente una chiave chiamata headObjectContext
. All'interno del contesto, esiste un'unica proprietà chiamata inputS3Url
, che è un URL prefirmato per il punto di accesso di supporto per HeadObject
.
L'URL prefirmato includerà le seguenti proprietà, se specificate:
-
versionId
(nei parametri della query) -
requestPayer
(nell'intestazionex-amz-request-payer
) -
expectedBucketOwner
(nell'intestazionex-amz-expected-bucket-owner
)
Le altre proprietà non saranno prefirmate e quindi non saranno incluse. Le opzioni non firmate inviate come intestazioni possono essere aggiunte manualmente alla richiesta quando si richiama l'URL prefirmato che si trova nelle intestazioni userRequest
. Le opzioni di crittografia lato server non sono supportate per HeadObject
.
Per i parametri URI della sintassi della richiesta, consulta HeadObject
nella Documentazione di riferimento delle API di Amazon Simple Storage Service.
Il seguente esempio mostra un payload di input Lambda JSON per HeadObject
.
{ "xAmzRequestId": "
requestId
", "**headObjectContext**": { "**inputS3Url**": "https://my-s3-ap-111122223333
.s3-accesspoint.us-east-1
.amazonaws.com/example?X-Amz-Security-Token=<snip>" }, "configuration": { "accessPointArn": "arn:aws:s3-object-lambda:us-east-1
:111122223333
:accesspoint/example-object-lambda-ap
", "supportingAccessPointArn": "arn:aws:s3:us-east-1
:111122223333
:accesspoint/example-ap
", "payload": "{}" }, "userRequest": { "url": "https://object-lambda-111122223333
.s3-object-lambda.us-east-1
.amazonaws.com/example
", "headers": { "Host": "object-lambda-111122223333
.s3-object-lambda.us-east-1
.amazonaws.com", "Accept-Encoding": "identity", "X-Amz-Content-SHA256": "e3b0c44298fc1example
" } }, "userIdentity": { "type": "AssumedRole", "principalId": "principalId
", "arn": "arn:aws:sts::111122223333
:assumed-role/Admin/example
", "accountId": "111122223333
", "accessKeyId": "accessKeyId
", "sessionContext": { "attributes": { "mfaAuthenticated": "false", "creationDate": "Wed Mar 10 23:41:52 UTC 2021" }, "sessionIssuer": { "type": "Role", "principalId": "principalId
", "arn": "arn:aws:iam::111122223333
:role/Admin", "accountId": "111122223333
", "userName": "Admin" } } }, "protocolVersion": "1.00" }
La funzione Lambda dovrebbe restituire un oggetto JSON contenente le intestazioni e i valori che verranno restituiti per la chiamata HeadObject
.
Il seguente esempio illustra la struttura dell'oggetto JSON della risposta Lambda per HeadObject
.
{ "statusCode": <number>; // Required "errorCode": <string>; "errorMessage": <string>; "headers": { "Accept-Ranges": <string>, "x-amz-archive-status": <string>, "x-amz-server-side-encryption-bucket-key-enabled": <boolean>, "Cache-Control": <string>, "Content-Disposition": <string>, "Content-Encoding": <string>, "Content-Language": <string>, "Content-Length": <number>, // Required "Content-Type": <string>, "x-amz-delete-marker": <boolean>, "ETag": <string>, "Expires": <string>, "x-amz-expiration": <string>, "Last-Modified": <string>, "x-amz-missing-meta": <number>, "x-amz-object-lock-mode": <string>, "x-amz-object-lock-legal-hold": <string>, "x-amz-object-lock-retain-until-date": <string>, "x-amz-mp-parts-count": <number>, "x-amz-replication-status": <string>, "x-amz-request-charged": <string>, "x-amz-restore": <string>, "x-amz-server-side-encryption": <string>, "x-amz-server-side-encryption-customer-algorithm": <string>, "x-amz-server-side-encryption-aws-kms-key-id": <string>, "x-amz-server-side-encryption-customer-key-MD5": <string>, "x-amz-storage-class": <string>, "x-amz-tagging-count": <number>, "x-amz-version-id": <string>, <x-amz-meta-headers>: <string>, // user-defined metadata "x-amz-meta-meta1": <string>, // example of the user-defined metadata header, it will need the x-amz-meta prefix "x-amz-meta-meta2": <string> ... }; }
L'esempio seguente mostra come utilizzare l'URL prefirmato per compilare la risposta modificando i valori dell'intestazione secondo necessità prima di restituire l'oggetto JSON.
Utilizzo di richieste ListObjects
in Lambda
Questa sezione presuppone che il punto di accesso Lambda per oggetti sia configurato per richiamare la funzione Lambda per ListObjects
. Lambda riceverà il payload JSON con un nuovo oggetto denominato listObjectsContext
. listObjectsContext
contiene un'unica proprietà inputS3Url
, che è un URL prefirmato per il punto di accesso di supporto per ListObjects
.
A differenza di GetObject
e HeadObject
, l'URL prefirmato includerà le seguenti proprietà, se specificate:
-
Tutti i parametri della query
-
requestPayer
(nell'intestazionex-amz-request-payer
) -
expectedBucketOwner
(nell'intestazionex-amz-expected-bucket-owner
)
Per i parametri URI della sintassi della richiesta, consulta ListObjects
nella Documentazione di riferimento delle API di Amazon Simple Storage Service.
Importante
Ti consigliamo di utilizzare la versione più recente, ListObjectsV2, per lo sviluppo di applicazioni. Per la compatibilità con le versioni precedenti, Amazon S3 continua a supportare ListObjects
.
Il seguente esempio illustra il payload di input Lambda JSON per ListObjects
.
{ "xAmzRequestId": "
requestId
", "**listObjectsContext**": { "**inputS3Url**": "https://my-s3-ap-111122223333
.s3-accesspoint.us-east-1
.amazonaws.com/?X-Amz-Security-Token=<snip>", }, "configuration": { "accessPointArn": "arn:aws:s3-object-lambda:us-east-1
:111122223333
:accesspoint/example-object-lambda-ap
", "supportingAccessPointArn": "arn:aws:s3:us-east-1
:111122223333
:accesspoint/example-ap
", "payload": "{}" }, "userRequest": { "url": "https://object-lambda-111122223333
.s3-object-lambda.us-east-1
.amazonaws.com/example
", "headers": { "Host": "object-lambda-111122223333
.s3-object-lambda.us-east-1
.amazonaws.com", "Accept-Encoding": "identity", "X-Amz-Content-SHA256": "e3b0c44298fc1example
" } }, "userIdentity": { "type": "AssumedRole", "principalId": "principalId
", "arn": "arn:aws:sts::111122223333
:assumed-role/Admin/example
", "accountId": "111122223333
", "accessKeyId": "accessKeyId
", "sessionContext": { "attributes": { "mfaAuthenticated": "false", "creationDate": "Wed Mar 10 23:41:52 UTC 2021" }, "sessionIssuer": { "type": "Role", "principalId": "principalId
", "arn": "arn:aws:iam::111122223333
:role/Admin", "accountId": "111122223333
", "userName": "Admin" } } }, "protocolVersion": "1.00" }
La funzione Lambda deve restituire un oggetto JSON contenente il codice di stato, il risultato XML dell'elenco o le informazioni sull'errore che verranno restituite da S3 Object Lambda.
S3 Object Lambda non elabora né convalida listResultXml
, ma lo inoltra al chiamante ListObjects
. Per listBucketResult
, S3 Object Lambda si aspetta che determinate proprietà siano di un tipo specifico e genererà eccezioni se non è in grado di analizzarle. listResultXml
elistBucketResult
non possono essere specificati contemporaneamente.
L'esempio seguente illustra come utilizzare l'URL prefirmato per richiamare Amazon S3 e utilizzare il risultato per compilare una risposta, incluso il controllo degli errori.
Il seguente esempio illustra la struttura dell'oggetto JSON della risposta Lambda per ListObjects
.
{ "statusCode": <number>; // Required "errorCode": <string>; "errorMessage": <string>; "listResultXml": <string>; // This can also be Error XML string in case S3 returned error response when calling the pre-signed URL "listBucketResult": { // listBucketResult can be provided instead of listResultXml, however they can not both be provided in the JSON response "name": <string>, // Required for 'listBucketResult' "prefix": <string>, "marker": <string>, "nextMarker": <string>, "maxKeys": <int>, // Required for 'listBucketResult' "delimiter": <string>, "encodingType": <string> "isTruncated": <boolean>, // Required for 'listBucketResult' "contents": [ { "key": <string>, // Required for 'content' "lastModified": <string>, "eTag": <string>, "checksumAlgorithm": <string>, // CRC32, CRC32C, SHA1, SHA256 "size": <int>, // Required for 'content' "owner": { "displayName": <string>, // Required for 'owner' "id": <string>, // Required for 'owner' }, "storageClass": <string> }, ... ], "commonPrefixes": [ { "prefix": <string> // Required for 'commonPrefix' }, ... ], } }
Utilizzo di richieste ListObjectsV2
in Lambda
Questa sezione presuppone che il punto di accesso Lambda per oggetti sia configurato per richiamare la funzione Lambda per ListObjectsV2
. Lambda riceverà il payload JSON con un nuovo oggetto denominato listObjectsV2Context
. listObjectsV2Context
contiene un'unica proprietà inputS3Url
, che è un URL prefirmato per il punto di accesso di supporto per ListObjectsV2
.
A differenza di GetObject
e HeadObject
, l'URL prefirmato includerà le seguenti proprietà, se specificate:
-
Tutti i parametri della query
-
requestPayer
(nell'intestazionex-amz-request-payer
) -
expectedBucketOwner
(nell'intestazionex-amz-expected-bucket-owner
)
Per i parametri URI della sintassi della richiesta, consulta ListObjectsV2
nella Documentazione di riferimento delle API di Amazon Simple Storage Service.
Il seguente esempio illustra il payload di input Lambda JSON per ListObjectsV2
.
{ "xAmzRequestId": "
requestId
", "**listObjectsV2Context**": { "**inputS3Url**": "https://my-s3-ap-111122223333
.s3-accesspoint.us-east-1
.amazonaws.com/?list-type=2&X-Amz-Security-Token=<snip>", }, "configuration": { "accessPointArn": "arn:aws:s3-object-lambda:us-east-1
:111122223333
:accesspoint/example-object-lambda-ap
", "supportingAccessPointArn": "arn:aws:s3:us-east-1
:111122223333
:accesspoint/example-ap
", "payload": "{}" }, "userRequest": { "url": "https://object-lambda-111122223333
.s3-object-lambda.us-east-1
.amazonaws.com/example
", "headers": { "Host": "object-lambda-111122223333
.s3-object-lambda.us-east-1
.amazonaws.com", "Accept-Encoding": "identity", "X-Amz-Content-SHA256": "e3b0c44298fc1example
" } }, "userIdentity": { "type": "AssumedRole", "principalId": "principalId
", "arn": "arn:aws:sts::111122223333
:assumed-role/Admin/example
", "accountId": "111122223333
", "accessKeyId": "accessKeyId
", "sessionContext": { "attributes": { "mfaAuthenticated": "false", "creationDate": "Wed Mar 10 23:41:52 UTC 2021" }, "sessionIssuer": { "type": "Role", "principalId": "principalId
", "arn": "arn:aws:iam::111122223333
:role/Admin", "accountId": "111122223333
", "userName": "Admin" } } }, "protocolVersion": "1.00" }
La funzione Lambda deve restituire un oggetto JSON contenente il codice di stato, il risultato XML dell'elenco o le informazioni sull'errore che verranno restituite da S3 Object Lambda.
S3 Object Lambda non elabora né convalida listResultXml
, ma lo inoltra al chiamante ListObjectsV2
. Per listBucketResult
, S3 Object Lambda si aspetta che determinate proprietà siano di un tipo specifico e genererà eccezioni se non è in grado di analizzarle. listResultXml
elistBucketResult
non possono essere specificati contemporaneamente.
L'esempio seguente illustra come utilizzare l'URL prefirmato per richiamare Amazon S3 e utilizzare il risultato per compilare una risposta, incluso il controllo degli errori.
Il seguente esempio illustra la struttura dell'oggetto JSON della risposta Lambda per ListObjectsV2
.
{ "statusCode": <number>; // Required "errorCode": <string>; "errorMessage": <string>; "listResultXml": <string>; // This can also be Error XML string in case S3 returned error response when calling the pre-signed URL "listBucketResult": { // listBucketResult can be provided instead of listResultXml, however they can not both be provided in the JSON response "name": <string>, // Required for 'listBucketResult' "prefix": <string>, "startAfter": <string>, "continuationToken": <string>, "nextContinuationToken": <string>, "keyCount": <int>, // Required for 'listBucketResult' "maxKeys": <int>, // Required for 'listBucketResult' "delimiter": <string>, "encodingType": <string> "isTruncated": <boolean>, // Required for 'listBucketResult' "contents": [ { "key": <string>, // Required for 'content' "lastModified": <string>, "eTag": <string>, "checksumAlgorithm": <string>, // CRC32, CRC32C, SHA1, SHA256 "size": <int>, // Required for 'content' "owner": { "displayName": <string>, // Required for 'owner' "id": <string>, // Required for 'owner' }, "storageClass": <string> }, ... ], "commonPrefixes": [ { "prefix": <string> // Required for 'commonPrefix' }, ... ], } }