Tutorial: Implantar um aplicativo Hello World - AWS Serverless Application Model

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Tutorial: Implantar um aplicativo Hello World

Neste guia, você faz download, compila e implanta um aplicativo Hello World de exemplo usandoAWS SAM. Em seguida, você testa o aplicativo noAWSCloud e, opcionalmente, teste-a localmente em seu host de desenvolvimento.

Este aplicativo implementa um back-end básico da API. Ele consiste em um endpoint do Amazon API Gateway e umAWS Lambdafunção. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda é invocada. Esta função retorna umhello worldmensagem.

O diagrama a seguir mostra os componentes deste aplicativo:


      Um diagrama de uma função do Lambda que é invocada quando você envia uma solicitação GET ao endpoint do API Gateway.

Quando você inicializa seu aplicativo de amostra, você tem a opção de escolher um tipo de pacote de implantação do Lambda, ouZipouImage. Para obter mais informações sobre tipos de pacotes, consultePacotes de implantação do LambdanoAWS LambdaGuia do desenvolvedor.

Veja a seguir uma visualização dos comandos executados para criar o aplicativo Hello World. Para obter mais informações sobre cada um desses comandos, consulte as seções posteriores neste tutorial.

#Step 1 - Download a sample application sam init #Step 2 - Build your application cd sam-app sam build #Step 3 - Deploy your application sam deploy --guided

Pré-requisitos

Este guia pressupõem-se que você concluiu as etapas do sistema operacional emComo instalar a CLI do AWS SAM, incluindo:

  1. Como criar umAWSconta.

  2. Configurar oAWS Identity and Access ManagementPermissões (IAM).

  3. Instalando o Docker. Observações: O Docker é um pré-requisito apenas para testar seu aplicativo localmente.

  4. Instalando o Homebrew. Observações: O Homebrew é um pré-requisito apenas para Linux e macOS.

  5. Instalar oAWS SAMInterface de linha de comando (CLI) do. Observações: Verifique se você tem a versão 1.13.0 ou posterior. Verifique a versão executando osam --versioncomando.

Etapa 1: Faça o download de uma amostraAWS SAMaplicativo

Comando a ser executado:

sam init

Siga as instruções na tela. Para este tutorial, recomendamos que você escolhaAWS Quick Start Templates, oZiptipo de pacote, o tempo de execução de sua escolha e oHello World Example.

Exemplos de resultado:

   
 -----------------------
 Generating application:
 -----------------------
 Name: sam-app
 Runtime: python3.7
 Dependency Manager: pip
 Application Template: hello-world
 Output Directory: .

 Next steps can be found in the README file at ./sam-app/README.md
        

O queAWS SAMEstá fazendo:

Este comando cria um diretório com o nome fornecido como o nome do projeto. O conteúdo do diretório do projeto é semelhante ao seguinte:

 
 sam-app/
   ├── README.md
   ├── events/
   │   └── event.json
   ├── hello_world/
   │   ├── __init__.py
   │   ├── app.py            #Contains your AWS Lambda handler logic.
   │   └── requirements.txt  #Contains any Python dependencies the application requires, used for sam build
   ├── template.yaml         #Contains the AWS SAM template defining your application's AWS resources.
   └── tests/
       └── unit/
           ├── __init__.py
           └── test_handler.py
        
nota

Esse conteúdo do diretório do projeto é criado quando você escolhe um dos tempos de execução do Python e oHello World Example.

Existem três arquivos especialmente importantes:

  • template.yaml: contém oAWS SAMModelo que define o do aplicativoAWSrecursos da AWS.

  • hello_world/app.py: Contém sua lógica de manipulador Lambda real.

  • hello_world/requirements.txt: Contém todas as dependências do Python que o aplicativo requer e é usado parasam build.

Etapa 2: Crie seu aplicativo

Comando a ser executado:

Primeiro, mude para o diretório do projeto, onde otemplate.yamlarquivo para o aplicativo de amostra está localizado. (Por padrão, esse diretório é?sam-app.) Em seguida, execute este comando:

sam build

Exemplos de resultado:

  
 Build Succeeded

 Built Artifacts  : .aws-sam/build
 Built Template   : .aws-sam/build/template.yaml

 Commands you can use next
 =========================
 [*] Invoke Function: sam local invoke
 [*] Deploy: sam deploy --guided
       

O queAWS SAMEstá fazendo:

OAWS SAMA CLI do vem com abstrações para vários tempos de execução do Lambda para criar as dependências e copia o código-fonte em pastas de preparação para que tudo esteja pronto para ser empacotado e implantado. Osam buildO comando compila quaisquer dependências que o aplicativo tem e copia o código-fonte do aplicativo para pastas em.aws-sam/buildpara ser compactado e carregado para o Lambda.

É possível ver a seguinte árvore de nível superior em.aws-sam:

 
 .aws-sam/
   └── build/
       ├── HelloWorldFunction/
       └── template.yaml
            

HelloWorldFunctioné um diretório que contém oapp.pyarquivo, bem como dependências de terceiros que seu aplicativo usa.

Etapa 3: Implante o aplicativo noAWSNuvem

Comando a ser executado:

sam deploy --guided

Siga as instruções na tela. Para aceitar as opções padrão fornecidas na experiência interativa, responda comEnter.

nota

Para o promptHelloWorldFunction may not have authorization defined, Is this okay? [y/N],AWS SAMestá informando que o aplicativo de exemplo configura uma API do API Gateway sem autorização. Ao implantar o aplicativo de exemplo,AWS SAMcria um URL disponível publicamente.

Você pode confirmar esta notificação respondendo “Y” ao prompt. Para obter informações sobre como configurar a autorização, consulteControlar o acesso às APIs do API Gateway.

Exemplos de resultado:

 
    Deploying with following values
    ===============================
    Stack name                 : sam-app
    Region                     : us-east-1
    Confirm changeset          : False
    Deployment s3 bucket       : sam-bucket
    Capabilities               : ["CAPABILITY_IAM"]
    Parameter overrides        : {}

 Initiating deployment
 =====================

 Waiting for changeset to be created..

 CloudFormation stack changeset
 ---------------------------------------------------------------------------------------------------------------------------------------------------
 Operation                                         LogicalResourceId                                 ResourceType
 ---------------------------------------------------------------------------------------------------------------------------------------------------
 + Add                                             HelloWorldFunctionHelloWorldPermissionProd        AWS::Lambda::Permission
 + Add                                             ServerlessRestApiDeployment47fc2d5f9d             AWS::ApiGateway::Deployment
 + Add                                             ServerlessRestApiProdStage                        AWS::ApiGateway::Stage
 + Add                                             ServerlessRestApi                                 AWS::ApiGateway::RestApi
 * Modify                                          HelloWorldFunctionRole                            AWS::IAM::Role
 * Modify                                          HelloWorldFunction                                AWS::Lambda::Function
 ---------------------------------------------------------------------------------------------------------------------------------------------------

 2019-11-21 14:33:24 - Waiting for stack create/update to complete

 CloudFormation events from changeset
 -------------------------------------------------------------------------------------------------------------------------------------------------
 ResourceStatus                       ResourceType                         LogicalResourceId                    ResourceStatusReason
 -------------------------------------------------------------------------------------------------------------------------------------------------
 UPDATE_IN_PROGRESS                   AWS::IAM::Role                       HelloWorldFunctionRole               -
 UPDATE_COMPLETE                      AWS::IAM::Role                       HelloWorldFunctionRole               -
 UPDATE_IN_PROGRESS                   AWS::Lambda::Function                HelloWorldFunction                   -
 UPDATE_COMPLETE                      AWS::Lambda::Function                HelloWorldFunction                   -
 CREATE_IN_PROGRESS                   AWS::ApiGateway::RestApi             ServerlessRestApi                    -
 CREATE_COMPLETE                      AWS::ApiGateway::RestApi             ServerlessRestApi                    -
 CREATE_IN_PROGRESS                   AWS::ApiGateway::RestApi             ServerlessRestApi                    Resource creation Initiated
 CREATE_IN_PROGRESS                   AWS::ApiGateway::Deployment          ServerlessRestApiDeployment47fc2d5   Resource creation Initiated
                                                                          f9d
 CREATE_IN_PROGRESS                   AWS::Lambda::Permission              HelloWorldFunctionHelloWorldPermis   Resource creation Initiated
                                                                          sionProd
 CREATE_IN_PROGRESS                   AWS::Lambda::Permission              HelloWorldFunctionHelloWorldPermis   -
                                                                          sionProd
 CREATE_IN_PROGRESS                   AWS::ApiGateway::Deployment          ServerlessRestApiDeployment47fc2d5   -
                                                                          f9d
CREATE_COMPLETE                      AWS::ApiGateway::Deployment          ServerlessRestApiDeployment47fc2d5   -
                                                                          f9d
 CREATE_IN_PROGRESS                   AWS::ApiGateway::Stage               ServerlessRestApiProdStage           -
 CREATE_IN_PROGRESS                   AWS::ApiGateway::Stage               ServerlessRestApiProdStage           Resource creation Initiated
 CREATE_COMPLETE                      AWS::ApiGateway::Stage               ServerlessRestApiProdStage           -
 CREATE_COMPLETE                      AWS::Lambda::Permission              HelloWorldFunctionHelloWorldPermis   -
                                                                          sionProd
 UPDATE_COMPLETE_CLEANUP_IN_PROGRES   AWS::CloudFormation::Stack           sam-app                              -
 S
 UPDATE_COMPLETE                      AWS::CloudFormation::Stack           sam-app                              -
 -------------------------------------------------------------------------------------------------------------------------------------------------

 Stack sam-app outputs:
 ---------------------------------------------------------------------------------------------------------------------------------------------------
 OutputKey-Description                                                     OutputValue
 ---------------------------------------------------------------------------------------------------------------------------------------------------
 HelloWorldFunctionIamRole - Implicit IAM Role created for Hello World     arn:aws:iam::123456789012:role/sam-app-
 function                                                                  HelloWorldFunctionRole-104VTJ0TST7M0
 HelloWorldApi - API Gateway endpoint URL for Prod stage for Hello World   https://0ks2zue0zh.execute-api.us-east-1.amazonaws.com/Prod/hello/
 function
 HelloWorldFunction - Hello World Lambda Function ARN                      arn:aws:lambda:us-east-1:123456789012:function:sam-app-
                                                                          HelloWorldFunction-1TY92MJX0BXU5
 ---------------------------------------------------------------------------------------------------------------------------------------------------

 Successfully created/updated stack - sam-app in us-east-1
        

O queAWS SAMEstá fazendo:

Este comando implanta o aplicativo noAWSCloud. É preciso os artefatos de implantação que você cria com osam buildComande, empacota e os carrega em um bucket do Amazon Simple Storage Service (Amazon S3)AWS SAMA CLI cria e implanta o aplicativo usandoAWS CloudFormation. Na saída dosam deployComando, você pode ver as alterações que estão sendo feitas noAWS CloudFormationpilha.

Se o aplicativo criou um endpoint HTTP, as saídas quesam deploygera também mostra a URL do endpoint para o aplicativo de teste. Você pode usarcurlpara enviar uma solicitação para o aplicativo usando esse URL de endpoint. Por exemplo:

curl https://<restapiid>.execute-api.us-east-1.amazonaws.com/Prod/hello/

Depois de implantar o aplicativo com êxito, você verá um resultado semelhante ao seguinte:

 
 {"message": "hello world"}
        

Se você vir{"message": "hello world"}depois de executar ocurlcomando, você implantou com êxito seu aplicativo sem servidor paraAWS, e você está chamando sua função do Lambda ao vivo. Caso contrário, consulte oSolução de problemasNo final deste tutorial.

Etapa 4: (Opcional) Teste o aplicativo localmente

Quando você está desenvolvendo seu aplicativo, talvez seja útil testar localmente. OAWS SAMA CLI fornece osam localpara executar o aplicativo usando contêineres Docker que simulam o ambiente de execução do Lambda. Existem duas opções para fazer isso:

  • Hospede sua API localmente

  • Invoque a função do Lambda diretamente

Esta etapa descreve as duas opções.

Hospede sua API localmente

Comando a ser executado:

sam local start-api

Exemplos de resultado:

 
 2019-07-12 15:27:58 Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
 2019-07-12 15:27:58 You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. You only need to restart SAM CLI if you update your AWS SAM template
 2019-07-12 15:27:58  * Running on http://127.0.0.1:3000/ (Press CTRL+C to quit)

 Fetching lambci/lambda:python3.7 Docker container image......................................................................................................................................................................................
 2019-07-12 15:28:56 Mounting /<working-development-path>/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated inside runtime container
 START RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Version: $LATEST
 END RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72
 REPORT RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72  Duration: 4.42 ms       Billed Duration: 100 ms Memory Size: 128 MB     Max Memory Used: 22 MB
 2019-07-12 15:28:58 No Content-Type given. Defaulting to 'application/json'.
 2019-07-12 15:28:58 127.0.0.1 - - [12/Jul/2019 15:28:58] "GET /hello HTTP/1.1" 200 -
            

Pode demorar um pouco para que a imagem do Docker seja carregada. Depois de carregar, você pode usarcurlpara enviar uma solicitação para o aplicativo que está sendo executado em seu host local:

curl http://127.0.0.1:3000/hello

Exemplos de resultado:

 
 2019-07-12 15:29:57 Invoking app.lambda_handler (python3.7)
 2019-07-12 15:29:57 Found credentials in shared credentials file: ~/.aws/credentials

 Fetching lambci/lambda:python3.7 Docker container image......
 2019-07-12 15:29:58 Mounting /<working-development-path>/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated inside runtime container
 START RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Version: $LATEST
 END RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72
 REPORT RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72  Duration: 7.92 ms       Billed Duration: 100 ms Memory Size: 128 MB     Max Memory Used: 22 MB
 {"statusCode":200,"body":"{\"message\": \"hello world\"}"}
            

O queAWS SAMEstá fazendo:

Ostart-apiinicia um endpoint local que replica o endpoint da API REST. Ele baixa um contêiner de execução no qual você pode executar sua função localmente. O resultado final é a mesma saída que você viu quando chamou sua função noAWSCloud.

Invoque a função do Lambda diretamente

Comando a ser executado:

sam local invoke "HelloWorldFunction" -e events/event.json

Exemplos de resultado:

 
 2019-07-01 14:08:42 Found credentials in shared credentials file: ~/.aws/credentials
 2019-07-01 14:08:42 Invoking app.lambda_handler (python3.7)

 Fetching lambci/lambda:python3.7 Docker container image...............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
 2019-07-01 14:09:39 Mounting /<working-development-path>/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated inside runtime container
 START RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72 Version: $LATEST
 END RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72
 REPORT RequestId: 52fdfc07-2182-154f-163f-5f0f9a621d72    Duration: 3.51 ms    Billed Duration: 100 ms    Memory Size: 128 MB    Max Memory Used: 22 MB    
 {"statusCode":200,"body":"{\"message\": \"hello world\"}"}
            

O queAWS SAMEstá fazendo:

Oinvokeinvoca diretamente suas funções do Lambda e pode passar cargas úteis de eventos de entrada que você fornece. Com esse comando, você passa a carga útil do evento no arquivoevent.jsonque o aplicativo de exemplo fornece.

Seu aplicativo inicializado vem com um padrãoaws-proxyevento do API Gateway. Um número de valores são pré-preenchidos para você. Neste caso, oHelloWorldFunctionnão se importa com os valores específicos, portanto, uma solicitação stubbed está OK. Você pode especificar vários valores para substituir a solicitação para simular o que você esperaria de uma solicitação real. Veja a seguir um exemplo de geração de seu próprio evento de entrada e comparar a saída com o padrãoevent.jsonobjeto:

sam local generate-event apigateway aws-proxy --body "" --path "hello" --method GET > api-event.json diff api-event.json events/event.json

Exemplos de resultado:

 
 <   "body": "",
 ---
 >   "body": "{\"message\": \"hello world\"}",
 4,6c4,6
 <   "path": "/hello",
 <   "httpMethod": "GET",
 <   "isBase64Encoded": true,
 ---
 >   "path": "/path/to/resource",
 >   "httpMethod": "POST",
 >   "isBase64Encoded": false,
 11c11
 <     "proxy": "/hello"
 ---
 >     "proxy": "/path/to/resource"
 56c56
 <     "path": "/prod/hello",
 ---
 >     "path": "/prod/path/to/resource",
 58c58
 <     "httpMethod": "GET",
 ---
 >     "httpMethod": "POST",
            

Solução de problemas

AWS SAMErro da CLI: “Restrições de segurança não satisfeitas”

Ao executarsam deploy --guided, você é solicitado com a perguntaHelloWorldFunction may not have authorization defined, Is this okay? [y/N]. Se você responder a esse prompt comN(a resposta padrão), você verá o seguinte erro:

 
Error: Security Constraints Not Satisfied
            

O prompt está informando que o aplicativo que você está prestes a implantar pode ter uma API do Amazon API Gateway configurada sem autorização. RespondendoNpara este prompt, você está dizendo que isso não está OK.

Para corrigir isso, você tem as seguintes opções:

  • Configure seu aplicativo com autorização. Para obter informações sobre como configurar a autorização, consulteControlar o acesso às APIs do API Gateway.

  • Responda a esta pergunta comYpara indicar que você está OK com a implantação de um aplicativo que tenha uma API do API Gateway configurada sem autorização.

AWS SAMErro da CLI: “não existe essa opção: —app-template”

Ao executar sam init, você verá o seguinte erro:

 
Error: no such option: --app-template
            

Isso significa que você está usando uma versão mais antiga da CLI do AWS SAM que não é compatível com o parâmetro --app-template. Para corrigir isso, é possível atualizar a versão da CLI do AWS SAM para 0.33.0 ou posterior ou omitir o parâmetro --app-template do comando sam init.

AWS SAMErro da CLI: “no such option: —guided” (não existe essa opção:

Ao executar sam deploy, você verá o seguinte erro:

 
Error: no such option: --guided
            

Isso significa que você está usando uma versão mais antiga da CLI do AWS SAM que não é compatível com o parâmetro --guided. Para corrigir isso, é possível atualizar a versão da CLI do AWS SAM para 0.33.0 ou posterior ou omitir o parâmetro --guided do comando sam deploy.

AWS SAMErro da CLI: “Failed to create managed resources: Não é possível localizar credenciais”

Ao executar sam deploy, você verá o seguinte erro:

 
Error: Failed to create managed resources: Unable to locate credentials
            

Isso significa que você não configurouAWScredenciais para habilitar oAWS SAMCLI para fazerAWSchamadas de serviço. Para corrigir isso, você deve configurarAWSCredenciais da . Para obter mais informações, consulte Configurar oAWScredenciais.

AWS SAMErro da CLI: “Em execuçãoAWSProjetos SAM exigem localmente o Docker. Você o instalou?”

Ao executar sam local start-api, você verá o seguinte erro:

 
Error: Running AWS SAM projects locally requires Docker. Have you got it installed?
            

Isso significa que você não tem o Docker instalado corretamente. O Docker é necessário para testar o aplicativo localmente. Para corrigir isso, siga as instruções para instalar o Docker para seu host de desenvolvimento. AcesseComo instalar a CLI do AWS SAM, escolha a plataforma apropriada e siga as instruções na seção intituladaInstalar o Docker.

Erro de Curl: “Token de autenticação ausente”

Ao tentar invocar o endpoint do API Gateway, você receberá o seguinte erro:

 
 {"message":"Missing Authentication Token"}
            

Isso significa que você tentou enviar uma solicitação para o domínio correto, mas o URI não é reconhecível. Para corrigir isso, verifique o URL completo e atualize ocurlCommand com o URL correto.

Erro de curvatura: “curl: (6) Não foi possível resolver:...”

Ao tentar invocar o endpoint do API Gateway, você receberá o seguinte erro:

 
 curl: (6) Could not resolve: endpointdomain (Domain name not found)
            

Isso significa que você tentou enviar uma solicitação para um domínio inválido. Isso pode acontecer se o aplicativo sem servidor falhar ao implantar com sucesso ou se você tiver um erro de digitação em seucurlcomando. Verifique se o aplicativo foi implantado com sucesso usando oAWS CloudFormationconsole ou oAWS CLIe verifique se o seucurlCommand está correto.

Limpar

Se você não precisar mais doAWSRecursos criados durante a execução deste tutorial, você pode removê-los excluindo oAWS CloudFormationpilha que você implantou.

Como excluir oAWS CloudFormationpilha usando oAWS Management Console, siga estas etapas:

  1. Faça login no AWS Management Console e abra o console AWS CloudFormation em https://console.aws.amazon.com/cloudformation.

  2. No painel de navegação à esquerda, selecioneStacks (Pilhas).

  3. Na lista de pilhas, escolhasam-app(ou o nome da pilha criada).

  4. Escolha Delete (Excluir).

Quando concluído, o status da pilha é alterado paraDELETE_COMPLETE.

Como alternativa, você pode excluir oAWS CloudFormationpilha executando o seguinteAWS CLIComando da :

aws cloudformation delete-stack --stack-name sam-app --region region

Verifique a pilha excluída

Para ambos os métodos de exclusão doAWS CloudFormationstack, você pode verificar se ele foi excluído indo para oAWS CloudFormationconsole. No painel de navegação à esquerda, escolhaPilhase, em seguida, na lista suspensa ao lado da caixa de pesquisa, escolhaDeleted (Excluído). Você verá o nome da pilha na lista de pilhas excluídas.

Conclusão

Neste tutorial, você fez o seguinte:

  1. Criou, construiu e implantou um aplicativo sem servidor paraAWSusandoAWS SAM.

  2. Testado o aplicativo localmenteAWS SAMCLI e Docker.

  3. Excluiu oAWSRecursos que você não precisa mais.

Próximas etapas

Agora você está pronto para começar a criar seus próprios aplicativos usando oAWS SAMCLI.

Para ajudá-lo a começar, você pode baixar qualquer um dos aplicativos de exemplo doAWS Serverless Application RepositoryExemplosrepositório no GitHub.