Escrever funções do Lambda para pontos de acesso do S3 Object Lambda
Essa seção apresenta detalhes de como escrever funções do AWS Lambda para usar com pontos de acesso do Amazon S3 Object Lambda.
Para saber mais sobre procedimentos completos para algumas tarefas do S3 Object Lambda, consulte o seguinte:
-
Tutorial: Como transformar dados para sua aplicação com o S3 Object Lambda
-
Tutorial: Detectar e editar dados PII com o S3 Object Lambda e o Amazon Comprehend
-
Tutorial: Using S3 Object Lambda to dynamically watermark images as they are retrieved
(Tutorial: Como usar o S3 Object Lambda para colocar marca d’água em imagens de maneira dinâmica à medida que são recuperadas)
Tópicos
Trabalhar com solicitações GetObject
no Lambda
Esta seção pressupõe que seu ponto de acesso do Object Lambda está configurado para chamar a função do Lambda para GetObject
. O S3 Object Lambda inclui a operação de API do Amazon S3, WriteGetObjectResponse
, que permite que a função do Lambda apresente dados personalizados e cabeçalhos de resposta para o chamador de GetObject
.
WriteGetObjectResponse
oferece controle extensivo sobre código de status, cabeçalhos de resposta e corpo de resposta, com base nas suas necessidades de processamento. Você pode usar WriteGetObjectResponse
para responder com todo o objeto transformado, partes do objeto transformado ou outras respostas com base no contexto da sua aplicação. A seção a seguir mostra exemplos exclusivos do uso da operação da API WriteGetObjectResponse
.
-
Exemplo 1: Responder com código de status HTTP 403 (Proibido)
-
Exemplo 2:responda com uma imagem transformada
-
Exemplo 3: Transmitir conteúdo compactado
Exemplo 1: Responder com código de status HTTP 403 (Proibido)
Você pode usar WriteGetObjectResponse
para responder com o código de status HTTP 403 (Proibido) com base no conteúdo do objeto.
Exemplo 2:responda com uma imagem transformada
Ao executar uma transformação de imagem, talvez você ache que precisa de todos os bytes do objeto de origem antes de começar a processá-los. Nesse caso, a solicitação WriteGetObjectResponse
retorna todo o objeto para a aplicação solicitante em uma chamada.
Exemplo 3: Transmitir conteúdo compactado
Quando objetos são comprimidos, os dados compactados são produzidos de forma incremental. Consequentemente, você pode usar sua solicitação WriteGetObjectResponse
para retornar os dados compactados assim que eles estiverem prontos. Como mostrado neste exemplo, não é necessário saber o tamanho da transformação concluída.
nota
Embora o S3 Object Lambda permita enviar uma resposta completa ao autor da chamada por meio da solicitação WriteGetObjectResponse
, a quantidade real de tempo disponível pode ser menor. Por exemplo, o tempo limite da função do Lambda pode ser inferior a 60 segundos. Em outros casos, o autor da chamada pode ter tempos limites mais rigorosos.
Para que o autor da chamada original receba uma resposta diferente de código de status HTTP 500 (Erro interno do servidor), a chamada WriteGetObjectResponse
deve ser concluída. Se a função do Lambda retornar, excepcionalmente ou de outra forma, antes que a operação da API WriteGetObjectResponse
seja chamada, o autor da chamada original receberá uma resposta 500 (Erro interno do servidor). Exceções lançadas durante o tempo necessário para concluir a resposta resultam em respostas truncadas ao autor da chamada. Se a função do Lambda recebe uma resposta com código de status HTTP 200 (OK) da chamada da API WriteGetObjectResponse
, o autor da chamada original enviou a solicitação completa. A resposta da função do Lambda, independentemente de uma exceção ser lançada ou não, é ignorada pelo S3 Object Lambda.
Ao chamar a operação de API WriteGetObjectResponse
, o Amazon S3 exige a rota e o token de solicitação do contexto do evento. Para ter mais informações, consulte Formato e uso de contexto de evento.
Os parâmetros de token de roteamento e solicitação são necessários para conectar a resposta WriteGetObjectResult
com o autor da chamada original. Ainda que sempre seja apropriado repetir respostas 500 (Erro interno do servidor), como o token de solicitação é um token de uso único, as tentativas subsequentes de usá-lo podem resultar em respostas com código de status HTTP 400 (Solicitação inválida). Embora a chamada para WriteGetObjectResponse
com tokens de roteamento e solicitação não precise ser feita a partir da função do Lambda invocada, ela deve ser feita por uma identidade na mesma conta. A chamada também deverá ser concluída antes que a função do Lambda termine a execução.
Trabalhar com solicitações HeadObject
no Lambda
Esta seção pressupõe que seu ponto de acesso do Object Lambda está configurado para chamar a função do Lambda para HeadObject
. O Lambda receberá uma carga útil JSON que contém uma chave chamada headObjectContext
. Dentro do contexto, há uma única propriedade chamada inputS3Url
, que é um URL pré-assinado para o ponto de acesso de suporte para HeadObject
.
O URL pré-assinado incluirá as seguintes propriedades se elas forem especificadas:
-
versionId
(nos parâmetros de consulta) -
requestPayer
(no cabeçalho dex-amz-request-payer
) -
expectedBucketOwner
(no cabeçalho dex-amz-expected-bucket-owner
)
Outras propriedades não serão pré-assinadas e, portanto, não serão incluídas. As opções não assinadas enviadas como cabeçalhos podem ser adicionadas manualmente à solicitação ao chamar o URL pré-assinado encontrado nos cabeçalhos de userRequest
. As opções de criptografia do lado do servidor não são compatíveis com HeadObject
.
Para ver os parâmetros de URI da sintaxe da solicitação, consulte HeadObject
na Amazon Simple Storage Service API Reference (Referência da API do Amazon Simple Storage Service).
O exemplo a seguir mostra uma carga útil JSON de entrada do Lambda para 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" }
Sua função do Lambda deve retornar um objeto JSON que contém os cabeçalhos e os valores que serão retornados para a chamada de HeadObject
.
O exemplo a seguir mostra a estrutura do JSON de resposta do Lambda para 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> ... }; }
O exemplo a seguir mostra como usar o URL pré-assinado para preencher sua resposta modificando os valores do cabeçalho conforme necessário antes de retornar o JSON.
Trabalhar com solicitações ListObjects
no Lambda
Esta seção pressupõe que seu ponto de acesso do Object Lambda está configurado para chamar a função do Lambda para ListObjects
. O Lambda receberá a carga JSON com um novo objeto chamado listObjectsContext
. listObjectsContext
contém uma única propriedade, inputS3Url
, que é um URL pré-assinado para o ponto de acesso de suporte para ListObjects
.
Ao contrário de GetObject
e HeadObject
, o URL pré-assinado incluirá as seguintes propriedades se elas forem especificadas:
-
Todos os parâmetros de consulta
-
requestPayer
(no cabeçalho dex-amz-request-payer
) -
expectedBucketOwner
(no cabeçalho dex-amz-expected-bucket-owner
)
Para ver os parâmetros de URI da sintaxe da solicitação, consulte ListObjects
na Referência da API do Amazon Simple Storage Service.
Importante
Recomendamos que você use a versão mais recente, ListObjectsV2, ao desenvolver aplicações. Para compatibilidade com versões anteriores, o Amazon S3 continua a oferecer suporte a ListObjects
.
O exemplo a seguir mostra a carga útil JSON de entrada do Lambda para 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" }
Sua função do Lambda deve retornar um objeto JSON que contém o código de status, o resultado XML da lista ou as informações de erro que serão retornadas do S3 Object Lambda.
O S3 Object Lambda não processa nem valida listResultXml
. Em vez disso, o encaminha para o chamador de ListObjects
. Para listBucketResult
, o S3 Object Lambda espera que certas propriedades sejam de um tipo específico e lançará exceções se não puder analisá-las. listResultXml
e listBucketResult
não podem ser fornecidas ao mesmo tempo.
O exemplo a seguir demonstra como usar o URL pré-assinado para chamar o Amazon S3 e usar o resultado para preencher uma resposta, incluindo a verificação de erros.
O exemplo a seguir mostra a estrutura do JSON de resposta do Lambda para 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' }, ... ], } }
Trabalhar com solicitações ListObjectsV2
no Lambda
Esta seção pressupõe que seu ponto de acesso do Object Lambda está configurado para chamar a função do Lambda para ListObjectsV2
. O Lambda receberá a carga JSON com um novo objeto chamado listObjectsV2Context
. listObjectsV2Context
contém uma única propriedade, inputS3Url
, que é um URL pré-assinado para o ponto de acesso de suporte para ListObjectsV2
.
Ao contrário de GetObject
e HeadObject
, o URL pré-assinado incluirá as seguintes propriedades se elas forem especificadas:
-
Todos os parâmetros de consulta
-
requestPayer
(no cabeçalho dex-amz-request-payer
) -
expectedBucketOwner
(no cabeçalho dex-amz-expected-bucket-owner
)
Para ver os parâmetros de URI da sintaxe da solicitação, consulte ListObjectsV2
na Referência da API do Amazon Simple Storage Service.
O exemplo a seguir mostra a carga útil JSON de entrada do Lambda para 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" }
Sua função do Lambda deve retornar um objeto JSON que contém o código de status, o resultado XML da lista ou as informações de erro que serão retornadas do S3 Object Lambda.
O S3 Object Lambda não processa nem valida listResultXml
. Em vez disso, o encaminha para o chamador de ListObjectsV2
. Para listBucketResult
, o S3 Object Lambda espera que certas propriedades sejam de um tipo específico e lançará exceções se não puder analisá-las. listResultXml
e listBucketResult
não podem ser fornecidas ao mesmo tempo.
O exemplo a seguir demonstra como usar o URL pré-assinado para chamar o Amazon S3 e usar o resultado para preencher uma resposta, incluindo a verificação de erros.
O exemplo a seguir mostra a estrutura do JSON de resposta do Lambda para 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' }, ... ], } }