# Streaming de resposta para funções do Lambda As funções do Lambda podem transmitir nativamente cargas úteis de resposta de volta aos clientes por meio de [URLs de funções do Lambda](urls-configuration.md) ou usando a API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) (por meio do SDK da AWS ou de chamadas diretas de API). Sua função do Lambda também pode transmitir cargas úteis de resposta por meio da [integração de proxy do Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/response-transfer-mode-lambda.html), que usa a API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) para invocar sua função. O streaming de respostas pode beneficiar aplicações sensíveis à latência ao melhorar a performance do tempo até o primeiro byte (TTFB). Isso ocorre porque é possível enviar respostas parciais de volta ao cliente assim que elas se tornarem disponíveis. Além disso, as funções de streaming de resposta podem retornar cargas úteis de até 200 MB, em comparação com o máximo de 6 MB para respostas armazenadas em buffer. O streaming de uma resposta também significa que sua função não precisa caber em toda a resposta na memória. Para respostas muito grandes, isso pode reduzir a quantidade de memória que você precisa configurar para sua função. **nota** O streaming de respostas do Lambda ainda não está disponível em todas as Regiões da AWS. Consulte os [Recursos da AWS por região](https://builder.aws.com/build/capabilities) do Builder Center para obter a disponibilidade de recursos por região. A velocidade com que o Lambda faz o streaming das suas respostas depende do tamanho da resposta. A taxa de streaming dos primeiros 6 MB da resposta da sua função é ilimitada. Para respostas maiores que 6 MB, o restante da resposta está sujeito a um limite de largura de banda. Para obter mais informações sobre largura de banda de streaming, consulte [Limites de largura de banda para streaming de resposta](#config-rs-bandwidth-cap). As respostas de streaming têm custos e as respostas transmitidas não são interrompidas quando a conexão do cliente de chamada é quebrada. Os clientes serão cobrados pela duração total da função, portanto, devem ter cuidado ao configurar tempos limite de função longos. O Lambda oferece suporte ao streaming de respostas em runtimes gerenciados por Node.js. Em outras linguagens, incluindo o Python, é possível [usar um runtime personalizado com uma integração personalizada da API de runtime](runtimes-custom.md#runtimes-custom-response-streaming) para transmitir respostas ou usar o [Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter). **nota** Ao testar sua função por meio do console do Lambda, você sempre verá as respostas como armazenadas em buffer. **Topics** + [Limites de largura de banda para streaming de resposta](#config-rs-bandwidth-cap) + [Compatibilidade da VPC com streaming de resposta](#config-rs-vpc-compatibility) + [Escrever funções do Lambda habilitadas para streaming de resposta](config-rs-write-functions.md) + [Invocação de uma função habilitada para streaming de resposta usando URLs de função do Lambda](config-rs-invoke-furls.md) + [Tutorial: criação de um função do Lambda de streaming de resposta com um URL da função](response-streaming-tutorial.md) ## Limites de largura de banda para streaming de resposta Os primeiros 6 MB da carga útil de resposta da sua função têm largura de banda ilimitada. Após essa intermitência inicial, o Lambda faz o streaming da sua resposta a uma taxa máxima de 2 MBps. Se as respostas da sua função nunca excederem 6 MB, esse limite de largura de banda nunca será aplicado. **nota** Os limites de largura de banda se aplicam somente à carga útil da resposta da sua função e não ao acesso à rede por sua função. A taxa de largura de banda ilimitada varia de acordo com diversos fatores, incluindo a velocidade de processamento da sua função. Normalmente, você pode esperar uma taxa superior a 2 MBps para os primeiros 6 MB da resposta da sua função. Se sua função estiver fazendo o streaming de uma resposta para um destino fora da AWS, a taxa de streaming também dependerá da velocidade da conexão externa com a Internet. ## Compatibilidade da VPC com streaming de resposta Ao usar funções do Lambda em um ambiente de VPC, há considerações importantes sobre o streaming de resposta: + Os URLs das funções do Lambda não são compatíveis com streaming de resposta em um ambiente de VPC. + É possível usar streaming de resposta em uma VPC invocando a função do Lambda por meio do SDK da AWS usando a API `InvokeWithResponseStream`. Isso requer a configuração dos endpoints da VPC apropriados para o Lambda. + Para ambientes de VPC, você precisará criar um endpoint da VPC de interface para o Lambda de modo a permitir a comunicação entre os recursos da VPC e o serviço Lambda. Uma arquitetura típica para streaming de resposta em uma VPC pode incluir: ``` Client in VPC -> Interface VPC endpoint for Lambda -> Lambda function -> Response streaming back through the same path ``` # Escrever funções do Lambda habilitadas para streaming de resposta Escrever o manipulador para funções de streaming de resposta é diferente dos padrões típicos do manipulador. Ao escrever funções de streaming, certifique-se de fazer o seguinte: + Envolva sua função com o decorador `awslambda.streamifyResponse()`. O objeto global `awslambda` é fornecido pelo ambiente de execução Node.js do Lambda. + Encerre a stream adequadamente para garantir que todo o processamento de dados seja concluído. ## Configuração de uma função de manipulador para o streaming de respostas Para indicar ao runtime que o Lambda deve fazer o streaming das respostas da sua função, é necessário encapsular sua função com o decorador `streamifyResponse()`. Isso faz com que o runtime use o caminho lógico adequado para o streaming de respostas e habilita a função a fazer o streaming das respostas. O decorador `streamifyResponse()` aceita uma função que aceita os seguintes parâmetros: + `event`: fornece informações sobre o evento de invocação do URL da função, como o método HTTP, os parâmetros da consulta e o corpo da solicitação. + `responseStream`: fornece um stream gravável. + `context`: fornece métodos e propriedades com informações sobre a invocação, a função e o ambiente de execução. O objeto `responseStream` é um [`writableStream` de Node.js](https://nodesource.com/blog/understanding-streams-in-nodejs/). Como em qualquer stream desse tipo, use o método `pipeline()`. **nota** O objeto global `awslambda` é fornecido automaticamente pelo tempo de execução Node.js do Lambda e nenhuma importação é necessária. **Example manipulador habilitado para streaming de resposta** ``` import { pipeline } from 'node:stream/promises'; import { Readable } from 'node:stream'; export const echo = awslambda.streamifyResponse(async (event, responseStream, _context) => { // As an example, convert event to a readable stream. const requestStream = Readable.from(Buffer.from(JSON.stringify(event))); await pipeline(requestStream, responseStream); }); ``` Embora `responseStream` ofereça o método `write()` para gravar no stream, recomendamos que você use [https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-callback](https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-callback) sempre que possível. O uso de `pipeline()` garante que o stream gravável não seja sobrecarregado por um stream legível mais rápido. ## Encerramento do stream Certifique-se de encerrar o stream corretamente antes que o manipulador retorne. O método `pipeline()` lida com isso automaticamente. Para outros casos de uso, chame o método `responseStream.end()` para encerrar corretamente um stream. Esse método sinaliza que nenhum outro dado deve ser gravado no stream. Esse método não é necessário se você gravar no stream com `pipeline()` ou `pipe()`. A partir do Node.js 24, o Lambda não espera mais que as promessas não resolvidas sejam concluídas após o retorno do manipulador ou o término do fluxo de respostas. Se a sua função depender de operações assíncronas adicionais, como cronômetros ou buscas, será necessário o `await` delas no seu manipulador. **Example Exemplo de encerramento de um stream com pipeline()** ``` import { pipeline } from 'node:stream/promises'; export const handler = awslambda.streamifyResponse(async (event, responseStream, _context) => { await pipeline(requestStream, responseStream); }); ``` **Example Exemplo de encerramento de um stream sem pipeline()** ``` export const handler = awslambda.streamifyResponse(async (event, responseStream, _context) => { responseStream.write("Hello "); responseStream.write("world "); responseStream.write("from "); responseStream.write("Lambda!"); responseStream.end(); }); ``` # Invocação de uma função habilitada para streaming de resposta usando URLs de função do Lambda **nota** Sua função do Lambda agora pode transmitir carga útil de resposta por meio da integração de proxy do [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/response-transfer-mode-lambda.html). É possível invocar funções habilitadas para streaming de resposta alterando o modo de invocação do URL da função. O modo de invocação determina qual operação de API o Lambda usa para invocar sua função. Os modos de invocação disponíveis são: + `BUFFERED`: esta é a opção padrão. O Lambda invoca sua função usando a operação `Invoke` da API. Os resultados da invocação estarão disponíveis quando a carga estiver concluída. O tamanho máximo da carga é de 6 GB. + `RESPONSE_STREAM`: permite que sua função faça o streaming dos resultados da carga assim que eles se tornem disponíveis. O Lambda invoca sua função usando a operação `InvokeWithResponseStream` da API. O tamanho máximo da carga útil de resposta é de 200 MB. Você ainda pode invocar sua função sem streaming de resposta chamando diretamente a operação `Invoke` da API. No entanto, o Lambda faz o streaming de todas as cargas de resposta para invocações que passam pela URL da função até que você altere o modo de invocação para `BUFFERED`. ------ #### [ Console ] **Para definir o modo de invocação de um URL da função (console)** 1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda. 1. Escolha o nome da função para a qual você deseja definir o modo de invocação. 1. Escolha a guia **Configuration** (Configuração) e depois **Function URL** (URL de função). 1. Escolha **Editar** e, em seguida, escolha **Configurações adicionais**. 1. Em **Modo de invocação**, escolha o modo de invocação desejado. 1. Escolha **Salvar**. ------ #### [ AWS CLI ] **Para definir o modo de invocação da URL de uma função (AWS CLI)** ``` aws lambda update-function-url-config \ --function-name my-function \ --invoke-mode RESPONSE_STREAM ``` ------ #### [ CloudFormation ] **Para definir o modo de invocação da URL de uma função (CloudFormation)** ``` MyFunctionUrl: Type: AWS::Lambda::Url Properties: AuthType: AWS_IAM InvokeMode: RESPONSE_STREAM ``` ------ Para obter mais informações sobre a configuração de URLs de função, consulte [URLs de função do Lambda](urls-configuration.md). # Tutorial: criação de um função do Lambda de streaming de resposta com um URL da função Neste tutorial, você criará uma função do Lambda definida como um arquivo .zip com um endpoint público do URL da função que retorna um fluxo de resposta. Para obter mais informações sobre a configuração de URLs de função, consulte [URLs de função](urls-configuration.md). ## Pré-requisitos Este tutorial presume que você tenha algum conhecimento de operações básicas do Lambda e do console do Lambda. Caso ainda não tenha feito isso, siga as instruções em [Criar uma função do Lambda com o console](getting-started.md#getting-started-create-function) para criar sua primeira função do Lambda. Para concluir as etapas apresentadas a seguir, é necessário ter a [versão 2 da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). Os comandos e a saída esperada são mostrados em blocos separados: ``` aws --version ``` A seguinte saída deverá ser mostrada: ``` aws-cli/2.13.27 Python/3.11.6 Linux/4.14.328-248.540.amzn2.x86_64 exe/x86_64.amzn.2 ``` Para comandos longos, um caractere de escape (`\`) é usado para dividir um comando em várias linhas. No Linux e no macOS, use seu gerenciador preferido de pacotes e de shell. **nota** No Windows, alguns comandos da CLI do Bash que você costuma usar com o Lambda (como `zip`) não são compatíveis com os terminais integrados do sistema operacional. Para obter uma versão do Ubuntu com o Bash integrada no Windows, [instale o Subsistema do Windows para Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Os exemplos de comandos da CLI neste guia usam a formatação Linux. Os comandos que incluem documentos JSON em linha deverão ser reformatados se você estiver usando a CLI do Windows. ## Criar uma função de execução Crie a [função de execução](lambda-intro-execution-role.md) que dá à sua função do Lambda permissão para acessar recursos da AWS. **Para criar uma função de execução** 1. Abra a [página Roles](https://console.aws.amazon.com/iam/home#/roles) (Funções) no console do AWS Identity and Access Management (IAM). 1. Selecione **Criar perfil**. 1. Crie uma função com as seguintes propriedades: + **Tipo de entidade confiável**: **serviço da AWS** + **Caso de uso**: **Lambda** + **Permissões**: **AWSLambdaBasicExecutionRole** + **Role name (Nome da função** – **response-streaming-role** A política **AWSLambdaBasicExecutionRole** tem as permissões de que a função necessita para gravar logs no Amazon CloudWatch Logs. Após criar o perfil, anote seu nome do recurso da Amazon (ARN). Você precisará dele na próxima etapa. ## Crie uma função de streaming de respostas (AWS CLI) Crie uma função do Lambda de streaming resposta com um endpoint de URL da função usando a AWS Command Line Interface (AWS CLI). **Para criar uma função que possa fazer o streaming de respostas** 1. Copie o exemplo de código a seguir em um arquivo com o nome `index.js`. Essa função transmite três respostas, separadas por 1 segundo. ``` exports.handler = awslambda.streamifyResponse( async (event, responseStream, _context) => { // Metadata is a JSON serializable JS object. Its shape is not defined here. const metadata = { statusCode: 200, headers: { "Content-Type": "application/json", "CustomHeader": "outerspace" } }; // Assign to the responseStream parameter to prevent accidental reuse of the non-wrapped stream. responseStream = awslambda.HttpResponseStream.from(responseStream, metadata); responseStream.write("Streaming with Helper \n"); await new Promise(r => setTimeout(r, 1000)); responseStream.write("Hello 0 \n"); await new Promise(r => setTimeout(r, 1000)); responseStream.write("Hello 1 \n"); await new Promise(r => setTimeout(r, 1000)); responseStream.write("Hello 2 \n"); await new Promise(r => setTimeout(r, 1000)); responseStream.end(); await responseStream.finished(); } ); ``` 1. Crie um pacote de implantação. ``` zip function.zip index.js ``` 1. Crie uma função do Lambda com o comando `create-function`. Substitua o valor de `--role` pelo ARN do perfil da etapa anterior. Esse comando define o tempo limite da função para 10 segundos, o que permite que a função transmita três respostas. ``` aws lambda create-function \ --function-name my-streaming-function \ --runtime nodejs24.x \ --zip-file fileb://function.zip \ --handler index.handler \ --timeout 10 \ --role arn:aws:iam::123456789012:role/response-streaming-role ``` **Para criar um URL da função** 1. Adicione uma política baseada em recursos à sua função concedendo as permissões `lambda:InvokeFunctionUrl` e `lambda:InvokeFunction`. Cada instrução deve ser adicionada em um comando individual. Substitua o valor de `--principal` pela sua ID da Conta da AWS. ``` aws lambda add-permission \ --function-name my-streaming-function \ --action lambda:InvokeFunctionUrl \ --statement-id UrlPolicyInvokeURL \ --principal 123456789012 \ --function-url-auth-type AWS_IAM ``` ``` aws lambda add-permission \ --function-name my-streaming-function \ --action lambda:InvokeFunction \ --statement-id UrlPolicyInvokeFunction \ --principal 123456789012 ``` 1. Crie um endpoint de URL para a função com o comando `create-function-url-config`. ``` aws lambda create-function-url-config \ --function-name my-streaming-function \ --auth-type AWS_IAM \ --invoke-mode RESPONSE_STREAM ``` **nota** Se você receber um erro sobre `--invoke-mode`, talvez seja necessário atualizar para uma [versão mais recente do AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). ## Testar o endpoint de URL de função Teste sua integração invocando sua função. É possível abrir o URL da sua função em um navegador, ou usar o curl. ``` curl --request GET "https://abcdefghijklm7nop7qrs740abcd.lambda-url.us-east-1.on.aws/" --user "AKIAIOSFODNN7EXAMPLE" --aws-sigv4 "aws:amz:us-east-1:lambda" --no-buffer ``` A URL da nossa função usa o tipo de autenticação `IAM_AUTH`. Isso significa que você precisa assinar solicitações com sua [chave de acesso e chave secreta da AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). No comando anterior, substitua `AKIAIOSFODNN7EXAMPLE` pela ID da chave de acesso da AWS. Insira sua chave secreta da AWS, quando solicitada. Se você não tiver sua chave secreta da AWS, é possível [usar credenciais da AWS temporárias](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html) em vez disso. Você obterá uma resposta parecida com esta: ``` Streaming with Helper Hello 0 Hello 1 Hello 2 ``` ## Limpe os recursos Agora você pode excluir os recursos criados para este tutorial, a menos que queira mantê-los. Excluindo os recursos da AWS que você não está mais usando, você evita cobranças desnecessárias em sua Conta da AWS. **Para excluir a função de execução** 1. Abra a página [Roles](https://console.aws.amazon.com/iam/home#/roles) (Funções) no console do IAM. 1. Selecione a função de execução que você criou. 1. Escolha **Excluir**. 1. Insira o nome do perfil no campo de entrada de texto e escolha **Delete** (Excluir). **Como excluir a função do Lambda** 1. Abra a página [Functions](https://console.aws.amazon.com/lambda/home#/functions) (Funções) no console do Lambda. 1. Selecione a função que você criou. 1. Selecione **Ações**, **Excluir**. 1. Digite **confirm** no campo de entrada de texto e escolha **Delete** (Excluir).