Construindo aplicativos com Sam Build Teste e implantação locais Práticas recomendadas Opções para sam build Solução de problemas Exemplos Saiba mais

Introdução à construção com o sam build comando

Use o AWS Serverless Application Model comando Command Line Interface (AWS SAMCLI) sam build para preparar seu aplicativo sem servidor para as etapas subsequentes do fluxo de trabalho de desenvolvimento, como testes locais ou implantação no. Nuvem AWS Esse comando cria um diretório .aws-sam que estrutura seu aplicativo em um formato e localização que o sam local e o sam deploy exigem.

Para obter uma introdução ao AWS SAMCLI, consulteO que é o AWS SAMCLI?.
Para obter uma lista de opções de comando sam build, consulte sam build.
Para obter um exemplo de uso do sam build durante um fluxo de trabalho de desenvolvimento típico, consulte Etapa 2: crie seu aplicativo.

nota

O uso de sam build exige que você comece com os componentes básicos de um aplicativo com tecnologia sem servidor em sua máquina de desenvolvimento. Isso inclui um AWS SAM modelo, código de AWS Lambda função e quaisquer arquivos e dependências específicos do idioma. Para saber mais, consulte Crie seu aplicativo com o sam init comando.

Construindo aplicativos com Sam Build

Antes de usarsam build, considere configurar o seguinte:

Funções e camadas do Lambda — O sam build comando pode construir funções e camadas do Lambda. Para saber mais sobre as camadas do Lambda, consulte Construindo camadas Lambda.
Tempo de execução do Lambda – O tempo de execução fornece um ambiente específico de linguagem que executa sua função no ambiente de execução quando invocado. Você pode configurar runtimes nativos e personalizados.
1. Tempo de execução nativo — Crie suas funções do Lambda em um tempo de execução do Lambda compatível e construa suas funções para usar um tempo de execução do Lambda nativo no Nuvem AWS.
2. Tempo de execução personalizado — Crie suas funções do Lambda usando qualquer linguagem de programação e construa seu tempo de execução usando um processo personalizado definido em um construtor makefile ou em um criador terceirizado, como esbuild. Para saber mais, consulte Criação de funções Lambda com tempos de execução personalizados.
Tipo de pacote Lambda — As funções do Lambda podem ser empacotadas nos seguintes tipos de pacotes de implantação do Lambda:
1. arquivo .zip – Contém o código do seu aplicativo e suas dependências.
2. Imagem de contêiner – Contém o sistema operacional de base, o tempo de execução, as extensões do Lambda, o código do seu aplicativo e suas dependências.

Essas configurações do aplicativo podem ser definidas ao inicializar um aplicativo usando o sam init.

Para saber mais sobre o uso do sam init, consulte Crie seu aplicativo com o sam init comando.
Para saber mais sobre como definir essas configurações em seu aplicativo, consulte Compilação padrão com AWS SAM.

Para construir um aplicativo

cd até a raiz do seu projeto. Esse é o mesmo local do seu AWS SAM modelo.
```
$ cd sam-app
```

Execute o seguinte:


sam-app $ sam build <arguments> <options>

nota

Uma opção comumente usada é o --use-container. Para saber mais, consulte Construindo uma função do Lambda dentro de um contêiner fornecido.

A seguir, veja um exemplo de saída do AWS SAM CLI:


sam-app $ sam build
Starting Build use cache
Manifest file is changed (new hash: 3298f1304...d4d421) or dependency folder (.aws-sam/deps/4d3dfad6-a267-47a6-a6cd-e07d6fae318c) is missing for (HelloWorldFunction), downloading dependencies and copying/building source
Building codeuri: /Users/.../sam-app/hello_world runtime: python3.12 metadata: {} architecture: x86_64 functions: HelloWorldFunction
Running PythonPipBuilder:CleanUp
Running PythonPipBuilder:ResolveDependencies
Running PythonPipBuilder:CopySource
Running PythonPipBuilder:CopySource

Build Succeeded

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

Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided

O AWS SAMCLI cria um diretório de compilação .aws-sam. Veja um exemplo a seguir:

.aws-sam
├── build
│   ├── HelloWorldFunction
│   │   ├── __init__.py
│   │   ├── app.py
│   │   └── requirements.txt
│   └── template.yaml
└── build.toml

Dependendo de como seu aplicativo está configurado, o AWS SAMCLI faz o seguinte:

Faz o download, instala e organiza as dependências no diretório .aws-sam/build.
Prepara seu código Lambda. Isso pode incluir compilar seu código, criar binários executáveis e criar imagens de contêiner.
Copia artefatos de construção para o diretório .aws-sam. O formato variará de acordo com o tipo de pacote do aplicativo.
1. Para tipos de pacotes.zip, os artefatos ainda não foram compactados para que possam ser usados para testes locais. O AWS SAMCLI fecha seu aplicativo ao usar o sam deploy.
2. Para tipos de pacote de imagem de contêiner, uma imagem de contêiner é criada localmente e referenciada no arquivo .aws-sam/build.toml.
Copia o AWS SAM modelo para o .aws-sam diretório e o modifica com novos caminhos de arquivo quando necessário.

A seguir estão os principais componentes que compõem seus artefatos de construção no diretório .aws-sam:

O diretório de construção — contém suas funções e camadas do Lambda estruturadas independentemente umas das outras. Isso resulta em uma estrutura exclusiva para cada função ou camada no diretório .aws-sam/build.
O AWS SAM modelo — Modificado com valores atualizados com base nas alterações durante o processo de criação.
O arquivo build.toml — Um arquivo de configuração que contém as configurações de compilação usadas pelo. AWS SAMCLI

Teste e implantação locais

Ao realizar testes locais com o sam local ou implantar com o sam deploy, o AWS SAMCLI faz o seguinte:

Primeiro, ele verifica se existe um .aws-sam diretório e se um AWS SAM modelo está localizado dentro desse diretório. Se essas condições forem atendidas, o AWS SAMCLI considerará como o diretório raiz do seu aplicativo.
Se essas condições não forem atendidas, o AWS SAMCLI considera o local original do seu AWS SAM modelo como o diretório raiz do seu aplicativo.

Ao desenvolver, se forem feitas alterações nos arquivos originais do aplicativo, execute sam build para atualizar o diretório .aws-sam antes de testar localmente.

Práticas recomendadas

Não edite nenhum código no diretório .aws-sam/build. Em vez disso, atualize o código-fonte original na pasta do projeto e execute sam build para atualizar o diretório .aws-sam/build.
Ao modificar seus arquivos originais, execute sam build para atualizar o diretório .aws-sam/build.
Talvez você queira que o AWS SAMCLI referencie o diretório raiz original do seu projeto em vez do diretório .aws-sam, como ao desenvolver e testar com o sam local. Exclua o .aws-sam diretório ou o AWS SAM modelo no .aws-sam diretório para que ele AWS SAMCLI reconheça o diretório original do projeto como o diretório raiz do projeto. Quando estiver pronto, execute sam build novamente para criar o diretório .aws-sam.
Quando você executa o sam build, o diretório .aws-sam/build é sobrescrito a cada vez. O diretório .aws-sam não. Se você quiser armazenar arquivos, como registros, armazene-os no .aws-sam para evitar que sejam sobrescritos.

Opções para sam build

Criar um único recurso

Forneça a ID lógica do recurso para criar somente esse recurso. Veja um exemplo a seguir:


$ sam build HelloWorldFunction

Para criar um recurso de uma pilha ou aplicativo aninhado, forneça o ID lógico do aplicativo ou da pilha junto com o ID lógico do recurso usando o formato <stack-logical-id>/<resource-logical-id>:


$ sam build MyNestedStack/MyFunction

Construindo uma função do Lambda dentro de um contêiner fornecido

A opção --use-container baixa uma imagem de contêiner e a usa para criar suas funções do Lambda. O contêiner local é então referenciado em seu arquivo .aws-sam/build.toml.

Esta opção requer Docker instalação. Para obter instruções, consulte Instalação do Docker.

A seguir está um exemplo deste comando:


$ sam build --use-container

Você pode especificar a imagem do contêiner a ser usada com a opção --build-image. Veja um exemplo a seguir:


$ sam build --use-container --build-image amazon/aws-sam-cli-build-image-nodejs20.x

Para especificar a imagem do contêiner a ser usada para uma única função, forneça o ID lógico da função. Veja um exemplo a seguir:


$ sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.12

Passe variáveis de ambiente para o contêiner de build

Use o --container-env-var para passar variáveis de ambiente para o contêiner de build. Veja um exemplo a seguir:


$ sam build --use-container --container-env-var Function1.GITHUB_TOKEN=<token1> --container-env-var GLOBAL_ENV_VAR=<global-token>

Para passar variáveis de ambiente de um arquivo, use a opção --container-env-var-file. Veja um exemplo a seguir:


$ sam build --use-container --container-env-var-file <env.json>

Exemplo do arquivo env.json:


{
  "MyFunction1": {
    "GITHUB_TOKEN": "TOKEN1"
  },
  "MyFunction2": {
    "GITHUB_TOKEN": "TOKEN2"
  }
}

Acelere a criação de aplicativos que contêm várias funções

Quando você executa sam build em um aplicativo com várias funções, o AWS SAMCLI cria uma função de cada vez. Para acelerar o processo de criação, use a opção --parallel. Isso cria todas as suas funções e camadas ao mesmo tempo.

A seguir está um exemplo deste comando:


$ sam build —-parallel

Acelere os tempos de compilação criando seu projeto na pasta de origem.

Para runtimes e métodos de compilação compatíveis, você pode usar a opção --build-in-source de criar seu projeto diretamente na pasta de origem. Por padrão, eles AWS SAM CLI são compilados em um diretório temporário, o que envolve a cópia do código-fonte e dos arquivos do projeto. Com--build-in-source, AWS SAM CLI as compilações diretamente na sua pasta de origem, o que acelera o processo de compilação ao eliminar a necessidade de copiar arquivos para um diretório temporário.

Para ver uma lista de runtimes compatíveis, consulte --build-in-source.

Solução de problemas

Para solucionar o problema do AWS SAMCLI, consulteAWS SAM CLI solução de problemas.

Exemplos

Criação de um aplicativo que usa um tempo de execução nativo e um tipo de pacote.zip

Para este exemplo, consulte Tutorial: Implantar um aplicativo Hello World.

Criação de um aplicativo que usa um tempo de execução nativo e um tipo de pacote de imagem

Primeiro, executamos sam init para inicializar um novo aplicativo. Durante o fluxo interativo, selecionamos o tipo de pacote Image. Veja um exemplo a seguir:


$ sam init
...
Which template source would you like to use?
        1 - AWS Quick Start Templates
        2 - Custom Template Location
Choice: 1

Choose an AWS Quick Start application template
        1 - Hello World Example
        2 - Multi-step workflow
        3 - Serverless API
        4 - Scheduled task
        5 - Standalone function
        6 - Data processing
        7 - Hello World Example With Powertools
        8 - Infrastructure event management
        9 - Serverless Connector Hello World Example
        10 - Multi-step workflow with Connectors
        11 - Lambda EFS example
        12 - DynamoDB Example
        13 - Machine Learning
Template: 1

Use the most popular runtime and package type? (Python and zip) [y/N]: ENTER

Which runtime would you like to use?
        ...
        10 - java8
        11 - nodejs20.x
        12 - nodejs18.x
        13 - nodejs16.x
        ...
Runtime: 12

What package type would you like to use?
        1 - Zip
        2 - Image
Package type: 2

Based on your selections, the only dependency manager available is npm.
We will proceed copying the template using npm.

Would you like to enable X-Ray tracing on the function(s) in your application?  [y/N]: ENTER

Would you like to enable monitoring using CloudWatch Application Insights?
For more info, please view https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: ENTER

Project name [sam-app]: ENTER

Cloning from https://github.com/aws/aws-sam-cli-app-templates (process may take a moment)

    -----------------------
    Generating application:
    -----------------------
    Name: sam-app
    Base Image: amazon/nodejs18.x-base
    Architectures: x86_64
    Dependency Manager: npm
    Output Directory: .
    Configuration file: sam-app/samconfig.toml

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

O AWS SAMCLI inicializa um aplicativo e cria o seguinte diretório de projeto:

sam-app
├── README.md
├── events
│   └── event.json
├── hello-world
│   ├── Dockerfile
│   ├── app.mjs
│   ├── package.json
│   └── tests
│       └── unit
│           └── test-handler.mjs
├── samconfig.toml
└── template.yaml

Em seguida, executamos sam build para criar nosso aplicativo:


sam-app $ sam build
Building codeuri: /Users/.../build-demo/sam-app runtime: None metadata: {'DockerTag': 'nodejs18.x-v1', 'DockerContext': '/Users/.../build-demo/sam-app/hello-world', 'Dockerfile': 'Dockerfile'} architecture: arm64 functions: HelloWorldFunction
Building image for HelloWorldFunction function
Setting DockerBuildArgs: {} for HelloWorldFunction function
Step 1/4 : FROM public.ecr.aws/lambda/nodejs:18
 ---> f5b68038c080
Step 2/4 : COPY app.mjs package*.json ./
 ---> Using cache
 ---> 834e565aae80
Step 3/4 : RUN npm install
 ---> Using cache
 ---> 31c2209dd7b5
Step 4/4 : CMD ["app.lambdaHandler"]
 ---> Using cache
 ---> 2ce2a438e89d
Successfully built 2ce2a438e89d
Successfully tagged helloworldfunction:nodejs18.x-v1

Build Succeeded

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

Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided

Como construir um aplicativo que inclua uma linguagem de programação compilada

Neste exemplo, criamos um aplicativo que contém uma função do Lambda usando o tempo de execução Go.

Primeiro, inicializamos um novo aplicativo usando sam init e configuramos nosso aplicativo para usar Go:


$ sam init

...

Which template source would you like to use?
        1 - AWS Quick Start Templates
        2 - Custom Template Location
Choice: 1

Choose an AWS Quick Start application template
        1 - Hello World Example
        2 - Multi-step workflow
        3 - Serverless API
        ...
Template: 1

Use the most popular runtime and package type? (Python and zip) [y/N]: ENTER

Which runtime would you like to use?
        ...
        4 - dotnetcore3.1
        5 - go1.x
        6 - go (provided.al2)
        ...
Runtime: 5

What package type would you like to use?
        1 - Zip
        2 - Image
Package type: 1

Based on your selections, the only dependency manager available is mod.
We will proceed copying the template using mod.

Would you like to enable X-Ray tracing on the function(s) in your application?  [y/N]: ENTER

Would you like to enable monitoring using CloudWatch Application Insights?
For more info, please view https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: ENTER

Project name [sam-app]: ENTER

Cloning from https://github.com/aws/aws-sam-cli-app-templates (process may take a moment)

    -----------------------
    Generating application:
    -----------------------
    Name: sam-app
    Runtime: go1.x
    Architectures: x86_64
    Dependency Manager: mod
    Application Template: hello-world
    Output Directory: .
    Configuration file: sam-app/samconfig.toml
    
    Next steps can be found in the README file at sam-app-go/README.md
        
...

O AWS SAMCLI inicializa o aplicativo. A seguir está um exemplo da estrutura de diretórios do aplicativo:

sam-app
├── Makefile
├── README.md
├── events
│   └── event.json
├── hello-world
│   ├── go.mod
│   ├── go.sum
│   ├── main.go
│   └── main_test.go
├── samconfig.toml
└── template.yaml

Nós referenciamos o arquivo README.md para os requisitos desse aplicativo.

...
## Requirements
* AWS CLI already configured with Administrator permission
* [Docker installed](https://www.docker.com/community-edition)
* [Golang](https://golang.org)
* SAM CLI - [Install the SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
...

Em seguida, executamos sam local invoke para testar nossa função. Esse comando comete um erro, pois Go não está instalado em nossa máquina local:


sam-app $ sam local invoke
Invoking hello-world (go1.x)
Local image was not found.
Removing rapid images for repo public.ecr.aws/sam/emulation-go1.x
Building image.................................................................................................................................................................................................................................................
Using local image: public.ecr.aws/lambda/go:1-rapid-x86_64.

Mounting /Users/.../Playground/build/sam-app/hello-world as /var/task:ro,delegated inside runtime container
START RequestId: c6c5eddf-042b-4e1e-ba66-745f7c86dd31 Version: $LATEST
fork/exec /var/task/hello-world: no such file or directory: PathError
null
END RequestId: c6c5eddf-042b-4e1e-ba66-745f7c86dd31
REPORT RequestId: c6c5eddf-042b-4e1e-ba66-745f7c86dd31  Init Duration: 0.88 ms  Duration: 175.75 ms Billed Duration: 176 ms Memory Size: 128 MB     Max Memory Used: 128 MB
{"errorMessage":"fork/exec /var/task/hello-world: no such file or directory","errorType":"PathError"}%

A seguir sam build, executamos para construir nosso aplicativo. Encontramos um erro porque Go não está instalado em sua máquina local:


sam-app $ sam build
Starting Build use cache
Cache is invalid, running build and copying resources for following functions (HelloWorldFunction)
Building codeuri: /Users/.../Playground/build/sam-app/hello-world runtime: go1.x metadata: {} architecture: x86_64 functions: HelloWorldFunction

Build Failed
Error: GoModulesBuilder:Resolver - Path resolution for runtime: go1.x of binary: go was not successful

Embora pudéssemos configurar nossa máquina local para criar adequadamente nossa função, usamos a opção --use-container com sam build. Ele AWS SAMCLI baixa uma imagem de contêiner, cria nossa função usando o nativo GoModulesBuilder e copia o binário resultante em nosso .aws-sam/build/HelloWorldFunction diretório.


sam-app $ sam build --use-container
Starting Build use cache
Starting Build inside a container
Cache is invalid, running build and copying resources for following functions (HelloWorldFunction)
Building codeuri: /Users/.../build/sam-app/hello-world runtime: go1.x metadata: {} architecture: x86_64 functions: HelloWorldFunction

Fetching public.ecr.aws/sam/build-go1.x:latest-x86_64 Docker container image.....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
Mounting /Users/.../build/sam-app/hello-world as /tmp/samcli/source:ro,delegated inside runtime container
Running GoModulesBuilder:Build

Build Succeeded

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

Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided

A seguir está um exemplo do diretório .aws-sam:

.aws-sam
├── build
│   ├── HelloWorldFunction
│   │   └── hello-world
│   └── template.yaml
├── build.toml
├── cache
│   └── c860d011-4147-4010-addb-2eaa289f4d95
│       └── hello-world
└── deps

Em seguida, executamos sam local invoke. Nossa função foi invocada com sucesso:


sam-app $ sam local invoke
Invoking hello-world (go1.x)
Local image is up-to-date
Using local image: public.ecr.aws/lambda/go:1-rapid-x86_64.

Mounting /Users/.../Playground/build/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated inside runtime container
START RequestId: cfc8ffa8-29f2-49d4-b461-45e8c7c80479 Version: $LATEST
END RequestId: cfc8ffa8-29f2-49d4-b461-45e8c7c80479
REPORT RequestId: cfc8ffa8-29f2-49d4-b461-45e8c7c80479  Init Duration: 1.20 ms  Duration: 1782.46 ms        Billed Duration: 1783 ms        Memory Size: 128 MB     Max Memory Used: 128 MB
{"statusCode":200,"headers":null,"multiValueHeaders":null,"body":"Hello, 72.21.198.67\n"}%

Saiba mais

Para obter mais informações sobre como usar o comandosam build, consulte:

Learning AWS SAM: sam build — Série Serverless Land “Learning AWS SAM” sobre. YouTube
Learning AWS SAM | sam build | E3 — Série “Learning AWS SAM” da Serverless Land sobre. YouTube
AWS SAM build: como ele fornece artefatos para implantação (sessões com SAM S2E8) — Sessões com séries ativadas. AWS SAM YouTube
AWS SAM compilações personalizadas: Como usar Makefiles para personalizar compilações no SAM (S2E9) — Sessões com séries ativadas. AWS SAM YouTube

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Crie seu aplicativo

Compilação padrão com AWS SAM