Création d'applications avec sam build Test et déploiement au niveau local Bonnes pratiques Options pour sam build Résolution des problèmes Exemples En savoir plus

Initiation à la construction avec AWS SAM

Utilisez l'interface AWS Serverless Application Model de ligne de commande (AWS SAM CLI) sam build pour préparer votre application sans serveur pour les étapes suivantes de votre flux de travail de développement, telles que les tests locaux ou le déploiement sur le AWS Cloud. Cette commande crée un répertoire .aws-sam qui structure votre application dans un format et un emplacement que sam local et sam deploy nécessitent.

Pour une introduction au AWS SAM CLI, voir Qu'est-ce que le AWS SAM CLI?.
Pour obtenir la liste des options de commande sam build, consultez sam build.
Pour un exemple d'utilisation de sam build dans le cadre d'un flux de travail de développement classique, consultez Étape 2 : créer votre application.

Note

L'utilisation de sam build nécessite que vous commenciez avec les composants de base d'une application sans serveur sur votre machine de développement. Cela inclut un AWS SAM modèle, un code de AWS Lambda fonction, ainsi que tous les fichiers et dépendances spécifiques au langage. Pour en savoir plus, consultez Créez votre application dans AWS SAM.

Création d'applications avec sam build

Avant de l'utilisersam build, pensez à configurer les éléments suivants :

Fonctions et couches Lambda : la commande sam build permet de créer des fonctions et des couches Lambda. Pour en savoir plus sur les couches Lambda, consultez Création de couches Lambda dans AWS SAM.
Exécution Lambda : l'exécution fournit un environnement spécifique au langage qui exécute votre fonction dans un environnement d'exécution lorsqu'elle est invoquée. Vous pouvez configurer des environnements d'exécution natifs et personnalisés.
1. Exécution native : créez vos fonctions Lambda dans une exécution Lambda prise en charge et créez vos fonctions pour utiliser une exécution Lambda native dans le AWS Cloud.
2. Runtime personnalisé : créez vos fonctions Lambda à l'aide de n'importe quel langage de programmation et créez votre environnement d'exécution à l'aide d'un processus personnalisé défini dans un makefile ou un constructeur tiers tel que esbuild. Pour en savoir plus, consultezCréation de fonctions Lambda avec des environnements d'exécution personnalisés dans AWS SAM.
Type de package Lambda : les fonctions Lambda peuvent être packagées dans les types de packages de déploiement Lambda suivants :
1. .zip file archive : contient le code de votre application et ses dépendances.
2. Image du conteneur : contient le système d'exploitation de base, l'exécution, les extensions Lambda, le code de votre application et ses dépendances.

Ces paramètres d'application peuvent être configurés lors de l'initialisation d'une application à l'aide de sam init.

Pour en savoir plus sur l'utilisation de sam init, consultez Créez votre application dans AWS SAM.
Pour en savoir plus sur la configuration de ces paramètres dans votre application, consultez Compilation par défaut avec AWS SAM.

Pour créer une application

cd à la racine de votre projet. Il s'agit du même emplacement que celui de votre AWS SAM modèle.
```
$ cd sam-app
```

Exécutez les commandes suivantes :


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

Note

Une option couramment utilisée est --use-container. Pour en savoir plus, consultez Création d'une fonction Lambda à l'intérieur d'un conteneur fourni.

Ce qui suit est un exemple de AWS SAM CLI sortie :


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

Le AWS SAM CLI crée un répertoire .aws-sam de construction. Voici un exemple :

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

En fonction de la configuration de votre application, le AWS SAM CLI effectue les opérations suivantes :

Elle télécharge, installe et organise les dépendances dans le répertoire .aws-sam/build.
Elle prépare votre code Lambda. Il peut s'agir de compiler votre code, de créer des fichiers binaires exécutables et de créer des images de conteneurs.
Elle copie les artefacts de création dans le répertoire .aws-sam. Le format varie en fonction du type du package de l'application.
1. Pour les types de packages .zip, les artefacts ne sont pas encore compressés afin de pouvoir être utilisés pour des tests locaux. Le AWS SAM CLI comprime votre application lors de son utilisationsam deploy.
2. Pour les types de packages d'images de conteneurs, une image de conteneur est créée localement et référencée dans le fichier .aws-sam/build.toml.
Copie le AWS SAM modèle .aws-sam dans le répertoire et le modifie avec de nouveaux chemins de fichiers si nécessaire.

Les principaux composants qui constituent vos artefacts de création dans le répertoire .aws-sam sont les suivants :

Le répertoire de création : contient vos fonctions et couches Lambda structurées indépendamment les unes des autres. La structure est donc unique pour chaque fonction ou couche du répertoire .aws-sam/build.
Le AWS SAM modèle : modifié avec des valeurs mises à jour en fonction des modifications apportées au cours du processus de création.
Le fichier build.toml : fichier de configuration qui contient les paramètres de construction utilisés par AWS SAM CLI.

Test et déploiement au niveau local

Lorsque vous effectuez des tests locaux avec sam local ou déployez avecsam deploy, AWS SAM CLI effectue les opérations suivantes :

Il vérifie d'abord si un .aws-sam répertoire existe et si un AWS SAM modèle se trouve dans ce répertoire. Si ces conditions sont remplies, AWS SAM CLI considère cela comme le répertoire racine de votre application.
Si ces conditions ne sont pas remplies, AWS SAM CLI considère l'emplacement d'origine de votre AWS SAM modèle comme le répertoire racine de votre application.

Lors du développement, si des modifications sont apportées à vos fichiers d'application originaux, exécutez sam build pour mettre à jour le répertoire .aws-sam avant de tester localement.

Bonnes pratiques

Ne modifiez aucun code dans le répertoire .aws-sam/build. Mettez plutôt à jour votre code source original dans le dossier de votre projet et exécutez sam build pour mettre à jour le répertoire .aws-sam/build.
Lorsque vous modifiez vos fichiers originaux, exécutez sam build pour mettre à jour le répertoire .aws-sam/build.
Vous voudrez peut-être AWS SAM CLI pour référencer le répertoire racine d'origine de votre projet plutôt que le .aws-sam répertoire, par exemple lors du développement et des tests avecsam local. Supprimez le .aws-sam répertoire ou le AWS SAM modèle dans le .aws-sam répertoire pour avoir AWS SAM CLI reconnaissez le répertoire de votre projet d'origine comme étant le répertoire racine du projet. Lorsque vous êtes prêt, exécutez à nouveau sam build pour créer le répertoire .aws-sam.
Lorsque vous exécutez sam build, le répertoire .aws-sam/build est remplacé à chaque fois. Le répertoire .aws-sam ne l'est pas. Si vous souhaitez stocker des fichiers, tels que des journaux, stockez-les dans .aws-sam pour éviter qu'ils ne soient remplacés.

Options pour sam build

Création d'une seule ressource

Fournissez l'ID logique de la ressource pour ne créer que cette ressource. Voici un exemple :


$ sam build HelloWorldFunction

Pour créer une ressource d'une application ou d'une pile imbriquée, fournissez l'identifiant logique de l'application ou de la pile avec l'identifiant logique de la ressource en utilisant le format <stack-logical-id>/<resource-logical-id> :


$ sam build MyNestedStack/MyFunction

Création d'une fonction Lambda à l'intérieur d'un conteneur fourni

L'option --use-container télécharge une image de conteneur et l'utilise pour créer vos fonctions Lambda. Le conteneur local est ensuite référencé dans votre fichier .aws-sam/build.toml.

Cette option nécessite Docker à installer. Pour obtenir des instructions, consultez Installation de Docker.

Voici un exemple de cette commande :


$ sam build --use-container

Vous pouvez spécifier l'image de conteneur à utiliser avec l'option --build-image. Voici un exemple :


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

Pour spécifier l'image du conteneur à utiliser pour une seule fonction, fournissez l'ID logique de la fonction. Voici un exemple :


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

Transmettre des variables d'environnement au conteneur de création

Utilisez --container-env-var pour transmettre les variables d'environnement au conteneur de création. Voici un exemple :


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

Pour transmettre des variables d'environnement à partir d'un fichier, utilisez l'option --container-env-var-file. Voici un exemple :


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

Exemple de fichier env.json :


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

Accélérez la création d'applications contenant plusieurs fonctions

Lorsque vous sam build exécutez une application dotée de plusieurs fonctions, AWS SAM CLI construit chaque fonction une par une. Pour accélérer le processus de création, utilisez l'option --parallel. Cela crée toutes les fonctions et couches en même temps.

Voici un exemple de cette commande :


$ sam build —-parallel

Accélérez les temps de création en créant votre projet dans le dossier source

Pour les systèmes d'exécution et les méthodes de création pris en charge, vous pouvez utiliser l'option --build-in-source permettant de créer votre projet directement dans le dossier source. Par défaut, le AWS SAM CLI se construit dans un répertoire temporaire, ce qui implique de copier le code source et les fichiers de projet. Avec--build-in-source, le AWS SAM CLI se construit directement dans votre dossier source, ce qui accélère le processus de génération en supprimant le besoin de copier des fichiers dans un répertoire temporaire.

Pour obtenir une liste des systèmes d’exécution ainsi que des méthodes de création pris en charge, consultez --build-in-source.

Résolution des problèmes

Pour résoudre le problème AWS SAM CLI, voir AWS SAM CLI Résolution des problèmes de la .

Exemples

Création d'une application utilisant une exécution native et un type de package .zip

Pour cet exemple, consultez Tutoriel : Déployer une application Hello World avec AWS SAM.

Création d'une application utilisant une exécution native et un type de package d'images

Tout d'abord, nous exécutons sam init pour initialiser une nouvelle application. Au cours du flux interactif, nous sélectionnons le type de package Image. Voici un exemple :


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

Le AWS SAM CLI initialise une application et crée le répertoire de projet suivant :

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

Ensuite, nous exécutons sam build pour créer notre application :


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

Création d'une application qui inclut un langage de programmation compilé

Dans cet exemple, nous créons une application qui contient une fonction Lambda à l'aide du Go temps d'exécution.

Tout d'abord, nous initialisons une nouvelle application en utilisant sam init et configurons notre application pour qu'elle utilise 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
        
...

Le AWS SAM CLI initialise l'application. Voici un exemple de la structure du répertoire de l'application :

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

Nous référençons le fichier README.md pour les exigences de cette application.

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

Ensuite, nous exécutons sam local invoke pour tester notre fonction. Cette commande comporte des erreurs car Go n'est pas installé sur notre machine locale :


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

Ensuite, nous exécutons sam build pour créer notre application. Nous rencontrons une erreur car Go n'est pas installé sur notre machine locale :


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

Bien que nous puissions configurer notre machine locale pour créer correctement notre fonction, nous utilisons plutôt l'option --use-container avec sam build. Le AWS SAM CLI télécharge une image de conteneur, construit notre fonction en utilisant GoModulesBuilder le natif et copie le binaire obtenu .aws-sam/build/HelloWorldFunction dans notre répertoire.


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

Voici un exemple du répertoire .aws-sam :

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

Ensuite, nous exécutons sam local invoke. Notre fonction est appelée avec succès :


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

En savoir plus

Pour en savoir plus sur l'utilisation de la commande sam build, reportez-vous à ce qui suit :

Apprentissage AWS SAM : sam build — Série « Learning AWS SAM » de Serverless Land sur YouTube.
Learning AWS SAM | sam build | E3 — Série « Learning AWS SAM » de Serverless Land sur YouTube.
AWS SAM build : comment il fournit des artefacts pour le déploiement (sessions avec SAM S2E8) — Sessions avec des séries sur AWS SAM YouTube.
AWS SAM versions personnalisées : comment utiliser les Makefiles pour personnaliser les versions dans SAM (S2E9) — Sessions avec des séries sur AWS SAM YouTube.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Créez votre application

Version par défaut