View a markdown version of this page

Introduzione alla costruzione con AWS SAM - AWS Serverless Application Model

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Introduzione alla costruzione con AWS SAM

Usa il AWS Serverless Application Model Interfaccia a riga di comando (AWS SAM CLI) sam build comando per preparare l'applicazione serverless per le fasi successive del flusso di lavoro di sviluppo, ad esempio il test locale o la distribuzione su Cloud AWS. Questo comando crea un .aws-sam directory che struttura l'applicazione in un formato e in una posizione che sam local e sam deploy richiedere.

Importante

sam build esegue i target Makefile, gli script del gestore di pacchetti e altri strumenti di compilazione definiti da un progetto. Prima di creare un progetto di cui non sei l'autore, esaminane i file di compilazione e le dipendenze.

Nota

Usando sam build richiede di iniziare con i componenti di base di un'applicazione serverless sul computer di sviluppo. Ciò include un AWS SAM modello, AWS Lambda Codice della funzione di evento ed eventuali file e dipendenze specifici della lingua. Per ulteriori informazioni, consulta Crea la tua candidatura in AWS SAM.

Creazione di applicazioni con sam build

Prima dell'uso sam build, considera la possibilità di configurare quanto segue:

  1. Funzioni e livelli Lambda — Il sam build il comando può creare funzioni e livelli Lambda. Per saperne di più sui livelli Lambda, vedi Creazione di livelli Lambda in AWS SAM.

    Può anche creare funzioni Web Lambda (AWS::Serverless::WebFunction) con codice locale. Per ulteriori informazioni, consulta Creazione e distribuzione di Lambda Web Functions.

  2. Runtime Lambda — Il runtime fornisce un ambiente specifico della lingua che esegue la funzione in un ambiente di esecuzione quando viene richiamata. È possibile configurare runtime nativi e personalizzati.

    1. Runtime nativo — Crea le tue funzioni Lambda in un runtime Lambda supportato e crea le tue funzioni per utilizzare un runtime Lambda nativo nel Cloud AWS.

    2. Runtime personalizzato — Crea le tue funzioni Lambda utilizzando qualsiasi linguaggio di programmazione e crea il tuo runtime utilizzando un processo personalizzato definito in un makefile o un generatore di terze parti come esbuild. Per ulteriori informazioni, consulta Creazione di funzioni di eventi Lambda con runtime personalizzati in AWS SAM.

  3. Tipo di pacchetto Lambda — Le funzioni Lambda possono essere impacchettate nei seguenti tipi di pacchetti di distribuzione Lambda:

    1. archivio di file.zip — Contiene il codice dell'applicazione e le relative dipendenze.

    2. Immagine del contenitore — Contiene il sistema operativo di base, il runtime, le estensioni Lambda, il codice dell'applicazione e le relative dipendenze.

Queste impostazioni dell'applicazione possono essere configurate quando si inizializza un'applicazione utilizzando sam init.

Per creare un'applicazione
  1. cd alla radice del tuo progetto. Questa è la stessa posizione della tua AWS SAM modello.

    $ cd sam-app
  2. Esegui il seguente codice:

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

    Un'opzione comunemente usata è --use-container. Per ulteriori informazioni, consulta Creazione di una Lambda Event Function all'interno di un contenitore fornito.

    Di seguito è riportato un esempio di AWS SAM CLI uscita:

    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
  3. Il AWS SAM CLI crea un .aws-sam crea una cartella. Di seguito è riportato un esempio:

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

A seconda di come è configurata l'applicazione, AWS SAM CLI esegue le seguenti operazioni:

  1. Scarica, installa e organizza le dipendenze in .aws-sam/build directory.

  2. Prepara il tuo codice Lambda. Ciò può includere la compilazione del codice, la creazione di file binari eseguibili e la creazione di immagini di contenitori.

  3. Le copie creano artefatti su .aws-sam cartella. Il formato varierà in base al tipo di pacchetto dell'applicazione.

    1. Per i tipi di pacchetto .zip, gli artefatti non sono ancora compressi in modo da poter essere utilizzati per i test locali. Il AWS SAM CLI comprime l'applicazione durante l'uso sam deploy.

    2. Per i tipi di pacchetto di immagini contenitore, un'immagine del contenitore viene creata localmente e referenziata nel .aws-sam/build.toml file.

  4. Copia il AWS SAM il modello viene trasferito al .aws-sam directory e la modifica con nuovi percorsi di file quando necessario.

Di seguito sono riportati i componenti principali che costituiscono gli artefatti di compilazione in .aws-sam cartella:

  • La cartella di compilazione — Contiene le funzioni e i livelli Lambda strutturati indipendentemente l'uno dall'altro. Ciò si traduce in una struttura unica per ogni funzione o livello di .aws-sam/build cartella.

  • Il AWS SAM modello — Modificato con valori aggiornati in base alle modifiche apportate durante il processo di compilazione.

  • Il file build.toml — Un file di configurazione che contiene le impostazioni di compilazione utilizzate da AWS SAM CLI.

Test e implementazione locali

Quando si eseguono test locali con sam local o distribuzione con sam deploy, il AWS SAM CLI esegue le seguenti operazioni:

  1. Per prima cosa controlla se un .aws-sam esiste una directory e se AWS SAM il modello si trova all'interno di quella directory. Se queste condizioni sono soddisfatte, il AWS SAM CLI considera questa come la directory principale dell'applicazione.

  2. Se queste condizioni non sono soddisfatte, il AWS SAM CLI considera la posizione originale del tuo AWS SAM template come directory principale dell'applicazione.

Durante lo sviluppo, se vengono apportate modifiche ai file dell'applicazione originale, esegui sam build per aggiornare il .aws-sam directory prima del test a livello locale.

Best practice

  • Non modificare alcun codice in .aws-sam/build rubrica. Aggiorna invece il codice sorgente originale nella cartella del progetto ed esegui sam build per aggiornare il .aws-sam/build elenco.

  • Quando modifichi i file originali, esegui sam build per aggiornare il .aws-sam/build elenco.

  • Potresti volere il AWS SAM CLI per fare riferimento alla directory principale originale del progetto anziché a .aws-sam directory, ad esempio durante lo sviluppo e il test con sam local. Eliminare il .aws-sam directory o AWS SAM modello nel .aws-sam directory per avere il AWS SAM CLI riconosci la cartella del tuo progetto originale come directory principale del progetto. Quando sei pronto, esegui sam build di nuovo per creare il .aws-sam cartella.

  • Quando corri sam build, il .aws-sam/build la directory viene sovrascritta ogni volta. La .aws-sam la directory no. Se si desidera archiviare file, ad esempio i registri, memorizzarli in .aws-sam per evitare che vengano sovrascritti.

Opzioni per sam build

Creazione di un'unica risorsa

Fornisci l'ID logico della risorsa per creare solo quella risorsa. Di seguito è riportato un esempio:

$ sam build HelloWorldFunction

Per creare una risorsa di un'applicazione o di uno stack annidato, fornisci l'ID logico dell'applicazione o dello stack insieme all'ID logico della risorsa utilizzando il formato <stack-logical-id>/<resource-logical-id> :

$ sam build MyNestedStack/MyFunction

Creazione di una Lambda Event Function all'interno di un contenitore fornito

Il --use-container l'opzione scarica un'immagine del contenitore e la utilizza per creare le tue funzioni Lambda. Il contenitore locale viene quindi referenziato nel tuo .aws-sam/build.toml file.

Questa opzione richiede Docker da installare. Per istruzioni, consulta l’argomento Installazione di Docker.

Di seguito è riportato un esempio di questo comando:

$ sam build --use-container

È possibile specificare l'immagine del contenitore da utilizzare con --build-image opzione. Di seguito è riportato un esempio:

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

Per specificare l'immagine del contenitore da utilizzare per una singola funzione, fornisci l'ID logico della funzione. Di seguito è riportato un esempio:

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

Creazione di immagini di contenitori con BuildKit

Quando si creano funzioni Lambda con Image tipo di pacchetto, puoi usare BuildKit come motore di compilazione passando il --use-buildkit opzione. BuildKit offre migliori prestazioni di compilazione, una migliore memorizzazione nella cache e un output di compilazione migliorato rispetto alla versione precedente Docker motore di compilazione.

Questa opzione richiede che sia installato il Docker o Finch CLIs installato e nel tuo PATH.

Puoi combinare --use-buildkit con altre opzioni di costruzione. Di seguito è riportato un esempio:

$ sam build --use-buildkit --parallel
Nota

La --use-buildkit il flag è solo per le build di immagini dei contenitori. Non avrà alcun effetto sulle funzioni zip create con --use-container.

Passa le variabili di ambiente al contenitore di compilazione

Usa il --container-env-var per passare variabili di ambiente al contenitore di compilazione. Di seguito è riportato un esempio:

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

Per passare variabili di ambiente da un file, usa --container-env-var-file opzione. Di seguito è riportato un esempio:

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

Esempio di env.json file:

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

Velocizza la creazione di applicazioni che contengono più funzioni

Quando corri sam build in un'applicazione con più funzioni, AWS SAM CLI costruisce ogni funzione una alla volta. Per velocizzare il processo di compilazione, usa --parallel opzione. Questo crea tutte le funzioni e i livelli contemporaneamente.

Di seguito è riportato un esempio di questo comando:

$ sam build —-parallel

Velocizza i tempi di compilazione compilando il progetto nella cartella sorgente

Per i runtime e i metodi di compilazione supportati, è possibile utilizzare --build-in-source opzione per creare il progetto direttamente nella cartella sorgente. Per impostazione predefinita, AWS SAM CLI viene creato in una directory temporanea, che comporta la copia del codice sorgente e dei file di progetto. Con --build-in-source, il AWS SAM CLI viene compilato direttamente nella cartella sorgente, il che velocizza il processo di compilazione eliminando la necessità di copiare i file in una directory temporanea.

Per un elenco dei runtime e dei metodi di compilazione supportati, consulta --build-in-source.

Risoluzione dei problemi

Per risolvere i problemi di AWS SAM CLI, vedi AWS SAM CLI risoluzione dei problemi.

Esempi

Creazione di un'applicazione che utilizza un runtime nativo e un tipo di pacchetto .zip

Per questo esempio, vedi Tutorial: Implementa un'applicazione Hello World con AWS SAM.

Creazione di un'applicazione che utilizza un runtime nativo e un tipo di pacchetto di immagini

Per prima cosa, corriamo sam init per inizializzare una nuova applicazione. Durante il flusso interattivo, selezioniamo Image tipo di pacchetto. Di seguito è riportato un esempio:

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

Il AWS SAM CLI inizializza un'applicazione e crea la seguente directory di progetto:

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

Successivamente, eseguiamo sam build per creare la nostra applicazione:

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

Creare un'applicazione che includa un linguaggio di programmazione compilato

In questo esempio, creiamo un'applicazione che contiene una funzione Lambda utilizzando Go runtime.

Innanzitutto, inizializziamo una nuova applicazione usando sam init e configuriamo la nostra applicazione da utilizzare 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 ...

Il AWS SAM CLI inizializza l'applicazione. Di seguito è riportato un esempio della struttura della directory dell'applicazione:

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

Facciamo riferimento al README.md file per i requisiti di questa applicazione.

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

Successivamente, corriamo sam local invoke per testare la nostra funzione. Questo comando ha un errore poiché Go non è installato sul nostro computer 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"}%

Successivamente, corriamo sam build per creare la nostra applicazione. Abbiamo riscontrato un errore da allora Go non è installato sul nostro computer 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

Sebbene possiamo configurare il nostro computer locale per creare correttamente la nostra funzione, utilizziamo invece --use-container opzione con sam build. Il AWS SAM CLI scarica un'immagine del contenitore, crea la nostra funzione usando il nativo GoModulesBuildere copia il file binario risultante nel nostro .aws-sam/build/HelloWorldFunction cartella.

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

Di seguito è riportato un esempio di .aws-sam elenco:

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

Successivamente, corriamo sam local invoke. La nostra funzione è stata richiamata con successo:

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

Ulteriori informazioni

Per saperne di più sull'uso di sam build comando, vedi quanto segue: