# Tutorial: Usar uma função do Lambda para acessar um banco de dados Amazon RDS Neste tutorial, você usará uma função do Lambda para gravar dados em um banco de dados do [Amazon Relational Database Service](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Welcome.html) (Amazon RDS) por meio do RDS Proxy. Sua função do Lambda lê registros de uma fila do Amazon Simple Queue Service (Amazon SQS) e grava um novo item em uma tabela no banco de dados sempre que uma mensagem é adicionada. Neste exemplo, você usa o Console de gerenciamento da AWS para adicionar mensagens manualmente à sua fila. O diagrama a seguir mostrará os recursos da AWS que você usará para concluir o tutorial. ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_1.png) Com o Amazon RDS, você pode executar um banco de dados relacional gerenciado na nuvem usando produtos de banco de dados comuns, como Microsoft SQL Server, MariaDB, MySQL, Oracle Database e PostgresQL. Ao usar o Lambda para acessar seu banco de dados, você pode ler e gravar dados em resposta a eventos, como um novo cliente se registrando em seu site. Sua função, a instância de banco de dados e o proxy escalam automaticamente para atender a períodos de alta demanda. Para concluir este tutorial, realize as seguintes tarefas: 1. Inicie uma instância de banco de dados do RDS para MySQL e um proxy na VPC padrão de sua Conta da AWS. 1. Crie e teste uma função do Lambda que cria uma nova tabela em seu banco de dados e grava dados nela. 1. Crie uma fila do Amazon SQS e configure-a para invocar sua função do Lambda sempre que uma nova mensagem for adicionada. 1. Teste a configuração completa adicionando mensagens à fila por meio do Console de gerenciamento da AWS e monitorando os resultados com o CloudWatch Logs. Ao concluir essas etapas, você aprende a: + Como usar o Amazon RDS para criar uma instância de banco de dados e um proxy e conectar uma função do Lambda ao proxy. + Como usar o Lambda para realizar operações de criação e leitura em um banco de dados do Amazon RDS. + Como usar o Amazon SQS para invocar uma função do Lambda. Você pode concluir este tutorial usando o Console de gerenciamento da AWS ou a AWS Command Line Interface (AWS CLI). ## Pré-requisitos Antes de começar, conclua as etapas nas seguintes seções: + [Inscrever-se para uma Conta da AWS](CHAP_SettingUp.md#sign-up-for-aws) + [Criar um usuário com acesso administrativo](CHAP_SettingUp.md#create-an-admin) ## Criar uma instância de banco de dados do Amazon RDS ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_step1.png) Uma instância de banco de dados do Amazon RDS é um ambiente de banco de dados isolado em execução na Nuvem AWS. Uma instância pode conter um ou mais bancos de dados criados pelo usuário. A menos que você especifique o contrário, o Amazon RDS cria instâncias de banco de dados na VPC padrão incluída em sua Conta da AWS. Para receber mais informações sobre o Amazon VPC, consulte o [Guia do usuário do Amazon Virtual Private Cloud](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html). Neste tutorial, você cria uma nova instância na VPC padrão de sua Conta da AWS e cria um banco de dados com o nome `ExampleDB` nessa instância. Você pode criar o banco de dados e a respectiva instância usando o Console de gerenciamento da AWS ou a AWS CLI. **Como criar uma instância de banco de dados** 1. No console do Amazon RDS, selecione **Criar banco de dados**. 1. Deixe a opção **Criação padrão** selecionada e, em **Opções do mecanismo**, escolha **MySQL**. 1. Em **Modelos**, escolha **Nível gratuito** ou **Sandbox**. O **nível gratuito** aparece para contas do nível gratuito. **Sandbox** aparece para contas do plano pago. 1. Em **Configurações**, para o **identificador da instância de banco de dados**, digite **MySQLForLambda**. 1. Para definir seu nome de usuário e senha, faça o seguinte: 1. Em **Configurações de credenciais**, deixe o **Nome do usuário principal** definido como `admin`. 1. Para a **Senha mestra**, digite e confirme uma senha para acessar seu banco de dados. 1. Para especificar o nome do banco de dados, faça o seguinte: + Deixe todas as opções padrão restantes selecionadas e role para baixo até a seção **Configuração adicional**. + Expanda essa seção e insira **ExampleDB** como o **Nome do banco de dados inicial**. 1. Deixe todas as opções padrão restantes selecionadas e escolha **Criar banco de dados**. ## Criar a função do Lambda e o proxy ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_step2.png) É possível usar o console do RDS para criar uma função do Lambda e um proxy na mesma VPC do banco de dados. **nota** Você só pode criar esses recursos associados quando o banco de dados tiver concluído a criação e estiver no status **Disponível**. **Como criar uma função e um proxy associados** 1. Na página **Bancos de dados**, confira se o banco de dados está no status **Disponível**. Se estiver, vá para a próxima etapa. Caso contrário, espere até que o banco de dados esteja disponível. 1. Selecione o banco de dados e escolha **Configurar conexão do Lambda** em **Ações**. 1. Na página **Configurar conexão do Lambda**, selecione **Criar nova função**. Defina o **Nome da nova função do Lambda** como **LambdaFunctionWithRDS**. 1. Na seção **RDS Proxy**, selecione a opção **Conectar usando o RDS Proxy**. Selecione ainda **Criar proxy**. + Em **Credenciais do banco de dados**, selecione **Nome do usuário e senha do banco de dados**. + Em **Nome do usuário**, especifique `admin`. + Em **Senha**, digite a senha que você criou para a instância de banco de dados. 1. Selecione **Configurar** para concluir a criação da função do Lambda e do proxy. O assistente conclui a configuração e fornece um link para o console do Lambda para você examinar a nova função. Observe o endpoint do proxy antes de mudar para o console do Lambda. ## Criar um perfil de execução de função ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_step3.png) Antes de criar sua função do Lambda, você cria um perfil de execução para dar à sua função as permissões necessárias. Neste tutorial, o Lambda precisa de permissão para gerenciar a conexão de rede com a VPC que contém a instância de banco de dados e para pesquisar mensagens de uma fila do Amazon SQS. Para dar à sua função do Lambda as permissões necessárias, este tutorial usa políticas gerenciadas pelo IAM. Essas são políticas que concedem permissões para muitos casos de uso comuns e estão disponíveis na sua Conta da AWS. Para obter mais informações sobre políticas gerenciadas, consulte [Práticas recomendadas de política](security_iam_id-based-policy-examples.md#security_iam_service-with-iam-policy-best-practices). **Para criar o perfil de execução do Lambda** 1. Abra a página [Perfis](https://console.aws.amazon.com/iamv2/home#/roles) do console do IAM e escolha **Criar perfil**. 1. Em **Tipo de entidade confiável**, selecione **Serviço da AWS** e, em **Caso de uso**, escolha **Lambda**. 1. Escolha **Próximo**. 1. Para adicionar as políticas gerenciadas do IAM, faça o seguinte: 1. Usando a caixa de pesquisa de políticas, pesquise **AWSLambdaSQSQueueExecutionRole**. 1. Na lista de resultados, marque a caixa de seleção ao lado do perfil e escolha **Limpar filtros**. 1. Usando a caixa de pesquisa de políticas, pesquise **AWSLambdaVPCAccessExecutionRole**. 1. Na lista de resultados, marque a caixa de seleção ao lado do perfil e escolha **Avançar**. 1. Em **Nome do perfil**, digite **lambda-vpc-sqs-role** e escolha **Criar perfil**. Posteriormente no tutorial, você precisará do nome do recurso da Amazon (ARN) do perfil de execução que acabou de criar. **Para encontrar o ARN do perfil de execução** 1. Abra a página [Perfis](https://console.aws.amazon.com/iamv2/home#/roles) do console do IAM e escolha o perfil (`lambda-vpc-sqs-role`). 1. Copie o **ARN** exibido na seção **Resumo**. ## Criar o pacote de implantação do Lambda ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_step4.png) O exemplo de código Python a seguir usa o pacote [PyMySQL](https://pymysql.readthedocs.io/en/latest/) para abrir uma conexão com seu banco de dados. Na primeira vez que você invoca sua função, ela também cria uma nova tabela chamada `Customer`. A tabela usa o seguinte esquema, em que `CustID` é a chave primária: ``` Customer(CustID, Name) ``` A função também usa a PyMySQL para adicionar registros a essa tabela. A função adiciona registros usando os IDs de clientes e nomes especificados nas mensagens que você adicionará à sua fila do Amazon SQS. O código cria a conexão com seu banco de dados fora da função do manipulador. A criação da conexão no código de inicialização permite que a conexão seja reutilizada por invocações subsequentes de sua função e melhora o desempenho. Em um aplicativo de produção, você também pode usar a [simultaneidade provisionada](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html) para inicializar um número solicitado de conexões de banco de dados. Essas conexões estão disponíveis assim que sua função é invocada. ``` import sys import logging import pymysql import json import os # rds settings user_name = os.environ['USER_NAME'] password = os.environ['PASSWORD'] rds_proxy_host = os.environ['RDS_PROXY_HOST'] db_name = os.environ['DB_NAME'] logger = logging.getLogger() logger.setLevel(logging.INFO) # create the database connection outside of the handler to allow connections to be # re-used by subsequent function invocations. try: conn = pymysql.connect(host=rds_proxy_host, user=user_name, passwd=password, db=db_name, connect_timeout=5) except pymysql.MySQLError as e: logger.error("ERROR: Unexpected error: Could not connect to MySQL instance.") logger.error(e) sys.exit(1) logger.info("SUCCESS: Connection to RDS for MySQL instance succeeded") def lambda_handler(event, context): """ This function creates a new RDS database table and writes records to it """ message = event['Records'][0]['body'] data = json.loads(message) CustID = data['CustID'] Name = data['Name'] item_count = 0 sql_string = f"insert into Customer (CustID, Name) values(%s, %s)" with conn.cursor() as cur: cur.execute("create table if not exists Customer ( CustID int NOT NULL, Name varchar(255) NOT NULL, PRIMARY KEY (CustID))") cur.execute(sql_string, (CustID, Name)) conn.commit() cur.execute("select * from Customer") logger.info("The following items have been added to the database:") for row in cur: item_count += 1 logger.info(row) conn.commit() return "Added %d items to RDS for MySQL table" %(item_count) ``` **nota** Neste exemplo, suas credenciais de acesso ao banco de dados são armazenadas como variáveis ​​de ambiente. Em aplicações de produção, recomendamos que você use o [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) como uma opção mais segura. Observe que, se sua função do Lambda estiver em uma VPC, para se conectar ao Secrets Manager, será necessário criar um endpoint da VPC. Consulte [Como se conectar ao serviço Secrets Manager em uma nuvem privada virtual](https://aws.amazon.com/blogs/security/how-to-connect-to-aws-secrets-manager-service-within-a-virtual-private-cloud/) para saber mais. Para incluir a dependência da PyMySQL em seu código de função, crie um pacote de implantação .zip. Os seguintes comandos funcionam para Linux, macOS ou Unix: **Para criar um pacote de implantação .zip** 1. Salve o exemplo de código como um arquivo denominado `lambda_function.py`. 1. No mesmo diretório em que você criou seu arquivo `lambda_function.py`, crie um novo diretório chamado `package` e instale a biblioteca PyMySQL. ``` mkdir package pip install --target package pymysql ``` 1. Crie um arquivo zip contendo o código do seu aplicativo e a biblioteca PyMySQL. No Linux ou no macOS, execute os comandos da CLI a seguir. No Windows, use sua ferramenta de zip preferida para criar o arquivo `lambda_function.zip`. O arquivo de código-fonte `lambda_function.py` e as pastas que contêm as dependências devem ser instaladas na raiz do arquivo .zip. ``` cd package zip -r ../lambda_function.zip . cd .. zip lambda_function.zip lambda_function.py ``` Você também pode criar seu pacote de implantação usando um ambiente virtual Python. Consulte [Implementar funções do Lambda em Python com arquivos .zip](https://docs.aws.amazon.com/lambda/latest/dg/python-package.html#python-package-create-package-with-dependency). ## Atualizar a função do Lambda Com o pacote .zip que acabou de criar, você atualizará a função do Lambda usando o console do Lambda. Para permitir que a função acesse o banco de dados, você também precisa configurar variáveis ​​de ambiente com as credenciais de acesso. **Como atualizar a função do Lambda** 1. Abra a página [Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda e selecione sua função `LambdaFunctionWithRDS`. 1. Na guia **Configurações de tempo de execução**, selecione **Editar** para alterar o **Tempo de execução** da função para **Python** 3.10. 1. Altere o **Manipulador** para `lambda_function.lambda_handler`. 1. Na guia **Código**, selecione **Fazer upload de** e, depois, **arquivo .zip**. 1. Selecione o arquivo `lambda_function.zip` que você criou no estágio anterior e escolha **Salvar**. Agora configure a função com o perfil de execução que você criou anteriormente. Isso concede à função as permissões necessárias para acessar sua instância de banco de dados e pesquisar uma fila do Amazon SQS. **Como configurar o perfil de execução da função.** 1. Na página [Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda, selecione a guia **Configuração** e escolha **Permissões**. 1. No painel **Papel de execução**, selecione **Editar**. 1. Em **Função existente**, selecione a função de execução (`lambda-vpc-sqs-role`). 1. Escolha **Salvar**. **Como configurar as variáveis ​​de ambiente da função** 1. Na página [Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda, selecione a guia **Configuração** e, em seguida, escolha **Variáveis de ambiente**. 1. Escolha **Editar**. 1. Para adicionar as credenciais de acesso ao banco de dados, faça o seguinte: 1. Escolha **Adicionar variável de ambiente** e, em seguida, para **Chave**, insira **USER\$1NAME**, e para **Valor**, insira **admin**. 1. Escolha **Adicionar variável de ambiente** e, em seguida, para **Chave**, insira **DB\$1NAME**, e para **Valor**, insira **ExampleDB**. 1. Escolha **Adicionar variável de ambiente** e, depois, para **Chave**, insira **PASSWORD**, e para **Valor**, insira a senha escolhida ao criar seu banco de dados. 1. Selecione **Adicionar variável de ambiente**. Em **Chave**, insira **RDS\$1PROXY\$1HOST** e, em **Valor**, insira o endpoint do RDS Proxy que você anotou anteriormente. 1. Escolha **Salvar**. ## Teste sua função do Lambda no console ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_step5.png) Agora você pode usar o console do Lambda para testar sua função. Você cria um evento de teste que imita os dados que sua função receberá ao invocá-la usando o Amazon SQS na fase final do tutorial. Seu evento de teste contém um objeto JSON especificando um ID de cliente e um nome de cliente para adicionar à tabela `Customer` que sua função cria. **Para testar a função do Lambda** 1. Abra a página [Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda e escolha sua função. 1. Selecione a seção **Testar**. 1. Selecione **Criar novo evento** e insira **myTestEvent** como nome do evento. 1. Copie o código a seguir no **JSON do evento** e escolha **Salvar**. ``` { "Records": [ { "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d", "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...", "body": "{\n \"CustID\": 1021,\n \"Name\": \"Martha Rivera\"\n}", "attributes": { "ApproximateReceiveCount": "1", "SentTimestamp": "1545082649183", "SenderId": "AIDAIENQZJOLO23YVJ4VO", "ApproximateFirstReceiveTimestamp": "1545082649185" }, "messageAttributes": {}, "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3", "eventSource": "aws:sqs", "eventSourceARN": "arn:aws:sqs:us-west-2:123456789012:my-queue", "awsRegion": "us-west-2" } ] } ``` 1. Escolha **Testar**. Na guia **Resultados da execução**, você verá resultados semelhantes aos seguintes exibidos nos **Logs da função**: ``` [INFO] 2023-02-14T19:31:35.149Z bdd06682-00c7-4d6f-9abb-89f4bbb4a27f The following items have been added to the database: [INFO] 2023-02-14T19:31:35.149Z bdd06682-00c7-4d6f-9abb-89f4bbb4a27f (1021, 'Martha Rivera') ``` ## Criar uma fila do Amazon SQS ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_step6.png) Você testou com sucesso a integração da sua função do Lambda e da instância do banco de dados do Amazon RDS. Agora você cria a fila do Amazon SQS que usará para invocar sua função do Lambda na fase final do tutorial. **Para criar uma fila do Amazon SQS (console)** 1. Abra a página [Filas](https://console.aws.amazon.com/sqs/v2/home#/queues) do console do Amazon SQS e selecione **Criar fila**. 1. Deixe o **Tipo** como **Padrão** e insira **LambdaRDSQueue** como o nome da sua fila. 1. Mantenha todas as opções padrão selecionadas e escolha **Criar fila**. ## Crie um mapeamento da origem do evento para invocar sua função do Lambda ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_step7.png) Um [mapeamento da origem do evento](https://docs.aws.amazon.com/lambda/latest/dg/invocation-eventsourcemapping.html) é um recurso no Lambda que lê itens de um fluxo ou de uma fila e invoca uma função do Lambda. Ao configurar um mapeamento da origem do evento, você pode especificar um tamanho de lote para que os registros do seu fluxo ou da sua fila sejam agrupados em uma única carga útil. Neste exemplo, você define o tamanho do lote como 1 para que sua função do Lambda seja invocada toda vez que você enviar uma mensagem para sua fila. Você pode configurar o mapeamento da origem do evento usando a AWS CLI ou o console do Lambda. **Crie um mapeamento da origem do evento (console)** 1. Abra a página [Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda e escolha sua função (`LambdaFunctionWithRDS`). 1. Na seção **Visão geral da função**, selecione **Adicionar gatilho**. 1. Para a origem, selecione **Amazon SQS** e, depois, o nome da fila (`LambdaRDSQueue`). 1. Em **Tamanho do lote**, insira **1**. 1. Deixe todas as outras opções definidas com os valores padrão e escolha **Adicionar**. Agora você está pronto para testar sua configuração completa adicionando uma mensagem à sua fila do Amazon SQS. ## Teste e monitore sua configuração ![\[\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/TUT_Lambda_step8.png) Para testar sua configuração completa, adicione mensagens à sua fila do Amazon SQS usando o console. Em seguida, você usa o CloudWatch Logs para confirmar que sua função do Lambda está gravando registros em seu banco de dados conforme o esperado. **Para testar e monitorar sua configuração** 1. Abra a página [Filas](https://console.aws.amazon.com/sqs/v2/home#/queues) do console do Amazon SQS e selecione sua fila (`LambdaRDSQueue`). 1. Selecione **Enviar e receber mensagens** e cole o JSON a seguir no **Corpo da mensagem** na seção **Enviar mensagem**. ``` { "CustID": 1054, "Name": "Richard Roe" } ``` 1. Escolha **Send Message (Enviar mensagem)**. Enviar sua mensagem para a fila fará com que o Lambda invoque sua função por meio do mapeamento da origem do evento. Para confirmar que o Lambda invocou sua função conforme o esperado, use o CloudWatch Logs para verificar se a função gravou o nome e o ID do cliente na tabela do banco de dados: 1. Abra a página [Grupos de logs](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) do console do CloudWatch e selecione o grupo de logs para sua função (`/aws/lambda/LambdaFunctionWithRDS`). 1. No painel **Fluxos de logs**, selecione o fluxo de logs mais recente. Sua tabela deve conter dois registros de clientes, um de cada invocação de sua função. No fluxo de logs, você deverá ver mensagens semelhantes às seguintes: ``` [INFO] 2023-02-14T19:06:43.873Z 45368126-3eee-47f7-88ca-3086ae6d3a77 The following items have been added to the database: [INFO] 2023-02-14T19:06:43.873Z 45368126-3eee-47f7-88ca-3086ae6d3a77 (1021, 'Martha Rivera') [INFO] 2023-02-14T19:06:43.873Z 45368126-3eee-47f7-88ca-3086ae6d3a77 (1054, 'Richard Roe') ``` ## 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. **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. Escolha **Excluir**. **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. Clique em **Excluir função**. 1. Depois em **Sim, excluir**. **Para excluir a instância de banco de dados MySQL do** 1. Abrir o[Página Bancos de dados](https://console.aws.amazon.com//rds/home#databases:)do console do Amazon RDS. 1. Selecione o banco de dados que você criou. 1. Selecione **Ações**, **Excluir**. 1. Desmarque a caixa de seleção **Create final snapshot** (Criar snapshot final). 1. Digite **delete me** na caixa de texto. 1. Escolha **Excluir**. **Para excluir a fila do Amazon SQS** 1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon SQS em [https://console.aws.amazon.com/sqs/](https://console.aws.amazon.com/sqs/). 1. Selecione a fila que você criou. 1. Escolha **Excluir**. 1. Digite **delete** na caixa de texto. 1. Escolha **Excluir**.