Creación de aplicaciones con la misma compilación Prueba e implementación locales Prácticas recomendadas Opciones para la compilación de Sam Resolución de problemas Ejemplos Más información

Introducción a la construcción con AWS SAM

Utiliza el comando sam build de la interfaz de la línea de comandos de AWS Serverless Application Model (CLI de AWS SAM) para preparar la aplicación sin servidor para los siguientes pasos del flujo de trabajo de desarrollo, como las testeo local o la implementación en. Nube de AWS Este comando crea un directorio .aws-sam que estructura la aplicación en el formato y la ubicación que necesite sam local sam deploy .

Para obtener una introducción a la CLI de AWS SAM, consulta ¿Qué es la AWS SAM CLI?.
Para ver una lista de opciones de comandos sam build, consulta sam build.
Para ver un ejemplo de uso de sam build durante un flujo de trabajo de desarrollo típico, consulta Paso 2: crear tu propia aplicación.

nota

El uso de sam build requiere que comience con los componentes básicos de una aplicación sin servidor en su máquina de desarrollo. Esto incluye una plantilla de AWS SAM, un código de función de AWS Lambda y cualquier archivo y dependencia específicos del idioma. Para obtener más información, consulta Creación de una aplicación AWS SAM.

Temas

Creación de aplicaciones con la misma compilación
Prueba e implementación locales
Prácticas recomendadas
Opciones para la compilación de Sam
Resolución de problemas
Ejemplos
Más información

Creación de aplicaciones con la misma compilación

Antes de usar sam build, considere y configure lo siguiente:

Funciones y capas Lambda: el comandosam build puede crear funciones y capas Lambda. Para obtener más información sobre el uso de las capas de Lambda, consulta Creación de capas Lambda en AWS SAM.
Tiempo de ejecución de Lambda: el tiempo de ejecución proporciona un entorno específico del lenguaje que ejecuta su función en un entorno de ejecución cuando se invoca. Puede configurar tiempos de ejecución nativos y personalizados.
1. Tiempo de ejecución nativo: cree sus funciones de Lambda en un tiempo de ejecución de Lambda compatible y cree sus funciones para utilizar un tiempo de ejecución de Lambda nativo en Nube de AWS
2. Tiempo de ejecución personalizado: cree sus funciones de Lambda con cualquier lenguaje de programación y cree su tiempo de ejecución mediante un proceso personalizado definido en un generador makefile o de terceros, como esbuild Para obtener más información, consulta Creación de funciones Lambda con tiempos de ejecución personalizados en AWS SAM.
Tipo de paquete Lambda: las funciones de Lambda se pueden empaquetar en los siguientes tipos de paquetes de implementación de Lambda:
1. Un archivo de archivo .zip, que incluye el código de la aplicación y sus dependencias.
2. Imagen del contenedor: contiene el sistema operativo base, el tiempo de ejecución, las extensiones de Lambda, el código de tu aplicación y sus dependencias.

Estos ajustes de la aplicación se pueden configurar al inicializar una aplicación mediante sam init

Para obtener más información acerca del uso de sam init, consulta Creación de una aplicación AWS SAM.
Para obtener más información sobre cómo configurar estos ajustes en la aplicación, consulta Compilación predeterminada con AWS SAM.

Para compilar una aplicación

cd a la raíz de su proyecto. Es la misma ubicación que la plantilla de AWS SAM.
```
$ cd sam-app
```

Ejecute lo siguiente:


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

nota

Una opción que se usa con frecuencia es --use-container. Para obtener más información, consulta Creación de una función de Lambda dentro de un contenedor proporcionado.

A continuación, se muestra un ejemplo de resultados de la CLI de AWS SAM.


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

La CLI de AWS SAM crea un directorio de compilación .aws-sam. A continuación, se muestra un ejemplo:

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

Según cómo esté configurada la aplicación, la CLI de AWS SAM hace lo siguiente:

Descarga, instala y organiza las dependencias en el directorio .aws-sam/build.
Prepara el código Lambda. Esto puede incluir la compilación del código, la creación de binarios ejecutables y la creación de imágenes de contenedores.
Copia los artefactos de construcción en el directorio .aws-sam. El formato variará en función del tipo de paquete de la aplicación.
1. En el caso de los tipos de paquetes.zip, los artefactos aún no están comprimidos, por lo que se pueden utilizar en testeo local. La CLI de AWS SAM comprime la aplicación cuando se usa sam deploy
2. Para los tipos de paquetes de imágenes de contenedores, se crea una imagen de contenedor localmente y se hace referencia a ella en el archivo .aws-sam/build.toml.
Copia la plantilla de AWS SAM en el directorio .aws-sam y la modifica con nuevas rutas de archivo cuando es necesario.

Los componentes principales que componen los artefactos de compilación del directorio .aws-sam son los siguientes:

El directorio de compilación: contiene las funciones y capas de Lambda estructuradas de forma independiente. Esto da como resultado una estructura única para cada función o capa del directorio .aws-sam/build.
La plantilla de AWS SAM: se modificó con valores actualizados en función de los cambios ocurridos durante el proceso de creación.
El archivo build.toml: un archivo de configuración que contiene los ajustes de compilación utilizados por la CLI de AWS SAM.

Prueba e implementación locales

Al realizar testeo local con sam local o realizar una implementación consam deploy, la CLI de AWS SAM hace lo siguiente:

Primero comprueba si existe un directorio .aws-sam y si hay una plantilla de AWS SAM ubicada dentro de ese directorio. Si se cumplen estas condiciones, la CLI de AWS SAM considera el directorio raíz de la aplicación.
Si no se cumplen estas condiciones, la CLI de AWS SAM considera la ubicación original de la plantilla de AWS SAM como el directorio raíz de la aplicación.

Durante el desarrollo, si se realizan cambios en los archivos originales de la aplicación, ejecuta sam build para actualizar el directorio .aws-sam antes de realizar testeo local.

Prácticas recomendadas

No edite ningún código del directorio .aws-sam/build. En su lugar, actualice el código fuente original en la carpeta del proyecto y ejecuta sam build para actualizar el directorio .aws-sam/build.
Cuando modifique los archivos originales, ejecuta sam build para actualizar el directorio .aws-sam/build.
Es posible que desee que la CLI de AWS SAM haga referencia al directorio raíz original del proyecto en lugar de al directorio .aws-sam, por ejemplo, al desarrollar y probar con sam local. Elimine el directorio .aws-sam o la plantilla de AWS SAM del directorio .aws-sam para que la CLI de AWS SAM reconozca el directorio original del proyecto como el directorio raíz del proyecto. Cuando esté listo, ejecuta nuevamente sam build para crear el directorio .aws-sam.
Cuando se ejecuta sam build, el .aws-sam/build directorio se sobrescribe cada vez. El directorio .aws-sam no lo hace. Si desea almacenar archivos como registros, guárdalos en .aws-sam para evitar que se sobrescriban.

Opciones para la compilación de Sam

Creación de un solo recurso

Proporciona el identificador lógico del recurso para crear solo ese recurso. A continuación, se muestra un ejemplo:


$ sam build HelloWorldFunction

Para crear un recurso a partir de una aplicación o pila anidada, proporciona el identificador lógico de la aplicación o pila junto con el identificador lógico del recurso con el siguiente formato <stack-logical-id>/<resource-logical-id>:


$ sam build MyNestedStack/MyFunction

Creación de una función de Lambda dentro de un contenedor proporcionado

La opción --use-container descarga una imagen de contenedor y la usa para crear las funciones de Lambda. A continuación, se hace referencia al contenedor local en el archivo .aws-sam/build.toml.

Esto requiere que Docker esté instalado. Para obtener instrucciones, consulta Instalar Docker.

A continuación, se muestra un ejemplo del comando:


$ sam build --use-container

Puedes especificar la imagen del contenedor que se usará con la opción --build-image. A continuación, se muestra un ejemplo:


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

Para especificar la imagen del contenedor que se usará para una sola función, proporciona el ID lógico de la función. A continuación, se muestra un ejemplo:


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

Transfiera la variables de entorno al contenedor de compilaciones.

Utiliza --container-env-var para transferir las variables de entorno al contenedor de compilaciones. A continuación, se muestra un ejemplo:


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

Para transferir variables de entorno de un archivo, utiliza la opción --container-env-var-file. A continuación, se muestra un ejemplo:


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

Ejemplo del archivo env.json:


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

Acelere la creación de aplicaciones que contienen múltiples funciones

Cuando se ejecuta sam build en una aplicación con varias funciones, la CLI de AWS SAM crea cada función de una en una. Para acelerar el proceso de compilación, utiliza la opción --parallel. De esta forma, se crean todas las funciones y capas al mismo tiempo.

A continuación, se muestra un ejemplo del comando:


$ sam build —-parallel

Acelere los tiempos de compilación al compilar el proyecto en la carpeta de origen

Para consultar los tiempos de ejecución y los métodos de compilación compatibles, puede usar la opción de --build-in-source para compilar el proyecto directamente en la carpeta de origen. De forma predeterminada, AWS SAM CLI compila en un directorio temporal, lo que implica copiar el código fuente y los archivos del proyecto. Con --build-in-source, AWS SAM CLI compila directamente en la carpeta de origen, lo que acelera el proceso de compilación al eliminar la necesidad de copiar archivos en un directorio temporal.

Para obtener una lista de los tiempos de ejecución y métodos de compilación compatibles, consulta --build-in-source.

Resolución de problemas

Para solucionar problemas de la CLI de AWS SAM, consulta Solución de problemas para AWS SAM CLI.

Ejemplos

Creación de una aplicación que utiliza un tiempo de ejecución nativo y un tipo de paquete .zip

Para este ejemplo, consulta Tutorial: Implemente una aplicación Hello World con AWS SAM.

Crear una aplicación que utiliza un tiempo de ejecución y un tipo de paquete de imágenes nativas

Primero, ejecuta sam init para inicializar una nueva aplicación. Durante el flujo interactivo, seleccione el tipo de paquete Image. A continuación, se muestra un ejemplo:


$ 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
    
...

La CLI de AWS SAM inicializa una aplicación y crea el siguiente directorio de proyectos:

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

A continuación, ejecuta sam build para crear e implementar nuestra aplicación:


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

Crear una aplicación que incluya un lenguaje de programación compilado

En este ejemplo, creamos una aplicación que contiene una función de Lambda utilizando el tiempo de ejecución Go.

En primer lugar, inicializamos una nueva aplicación utilizando sam init y configuramos nuestra aplicación para que utiliza 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
        
...

La CLI de AWS SAM inicializa la aplicación. A continuación, se muestra la estructura de directorios que utilizamos para esta aplicación de ejemplo:

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

Hacemos referencia al archivo README.md para conocer los requisitos de esta aplicación.

...
## 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)
...

A continuación, ejecutamos sam local invoke para probar la función. Este comando genera errores, ya que Go no está instalado en nuestra 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 continuación, ejecuta sam build para crear e implementar la aplicación. Nos encontramos con un error, ya que Go no está instalado en nuestra 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

Si bien podríamos configurar nuestra máquina local para que construya correctamente nuestra función, en su lugar utilizamos la opción --use-container con sam build. La CLI de AWS SAM descarga una imagen de contenedor, crea nuestra función usando el GoModulesBuilder nativo y copia el binario resultante en nuestro directorio .aws-sam/build/HelloWorldFunction.


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 continuación, se muestra un ejemplo del archivo .aws-sam.

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

A continuación, ejecutamos sam local invoke. Nuestra función se invocó correctamente:


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"}%

Más información

Para obtener más información sobre el uso del comando sam build, consulta los enlaces siguientes:

AprendizajeAWS SAM: sam build, serie «Aprendizaje sobre AWS SAM« de Serverless Land. YouTube
Aprendizaje AWS SAM | sam build | E3: serie «Aprendizaje de AWS SAM« de Serverless Land en adelante. YouTube
AWS SAMbuild: cómo proporciona artefactos para su implementación (Sesiones con SAM S2E8) — Sesiones con serie sobre AWS SAM YouTube
AWS SAMcompilaciones personalizadas: cómo usar archivos Make para personalizar compilaciones en SAM (S2E9) — Sesiones con series AWS SAM en YouTube.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Para crear tu aplicación

Compilación predeterminada