Compilazione predefinita con AWS SAM

Per creare la tua applicazione serverless, usa il sam build comando. Questo comando raccoglie anche gli elementi di compilazione delle dipendenze dell'applicazione e li colloca nel formato e nella posizione corretti per le fasi successive, come il test, la creazione di pacchetti e la distribuzione a livello locale.

È possibile specificare le dipendenze dell'applicazione in un file manifest, ad esempio requirements.txt (Python) package.json o (Node.js), oppure utilizzando Layers la proprietà di una risorsa funzione. La Layers proprietà contiene un elenco di risorse di AWS Lambda livello da cui dipende la funzione Lambda.

Il formato degli elementi di compilazione dell'applicazione dipende dalla proprietà di ciascuna funzione. PackageType Le opzioni per questa proprietà sono:

• Zip— Un archivio di file.zip, che contiene il codice dell'applicazione e le sue dipendenze. Se impacchettate il codice come archivio di file.zip, dovete specificare un runtime Lambda per la funzione.

• Image— Un'immagine del contenitore, che include il sistema operativo di base, il runtime e le estensioni, oltre al codice dell'applicazione e alle sue dipendenze.

Per ulteriori informazioni sui tipi di pacchetti Lambda, consulta Pacchetti di distribuzione Lambda nella Developer Guide.AWS Lambda

Creazione di un archivio di file.zip

Per creare un'applicazione serverless come archivio di file.zip, dichiarate PackageType: Zip di utilizzare la funzione serverless.

AWS SAM crea l'applicazione per l'architettura specificata. Se non si specifica un'architettura, AWS SAM utilizza x86_64 per impostazione predefinita.

Se la tua funzione Lambda dipende da pacchetti con programmi compilati nativamente, usa il flag. --use-container Questo flag compila localmente le tue funzioni in un contenitore che si comporta come un ambiente Lambda, quindi sono nel formato giusto quando le distribuisci sul Cloud. AWS

Quando utilizzi l'--use-containeropzione, per impostazione predefinita AWS SAM estrae l'immagine del contenitore da Amazon ECR Public. Se desideri estrarre un'immagine del contenitore da un altro repository o per una versione specifica della AWS SAM CLI, puoi utilizzare l'--build-imageopzione e fornire l'URI di un'immagine contenitore alternativa. Di seguito sono riportati due comandi di esempio per la creazione di applicazioni che utilizzano immagini di contenitori da una versione specifica della AWS SAM CLI:

# Build a Node.js 20 application using a container image for a specific version of AWS SAM CLI (1.136.0)
sam build --use-container --build-image public.ecr.aws/sam/build-nodejs22.x:1.136.0

# Build a function resource using the Python 3.13 container image from a specific version of AWS SAM CLI (1.136.0)(
sam build --use-container --build-image Function1=public.ecr.aws/sam/build-python3.13:1.136.0 

Per ulteriori esempi di creazione di un'applicazione di archiviazione di file con estensione zip, consultate la sezione Esempi più avanti in questo argomento.

Creazione di un'immagine di contenitore

Per creare un'applicazione serverless come immagine contenitore, dichiarate di utilizzare PackageType: Image la funzione serverless. È inoltre necessario dichiarare l'attributo Metadata resource con le seguenti voci:

Dockerfile

Il nome del Dockerfile associato alla funzione Lambda.

DockerContext

La posizione del Dockerfile.

DockerTag

(Facoltativo) Un tag da applicare all'immagine costruita.

DockerBuildArgs

Crea argomenti per la compilazione.

Importante

AWS SAMCLINon oscura né offusca le informazioni che includi negli argomenti. DockerBuildArgs Si consiglia vivamente di non utilizzare questa sezione per archiviare informazioni riservate, ad esempio password o segreti.

Di seguito è riportato un esempio Metadata di sezione relativa agli attributi delle risorse:

    Metadata:
      Dockerfile: Dockerfile
      DockerContext: ./hello_world
      DockerTag: v1

Per scaricare un'applicazione di esempio configurata con il tipo di Image pacchetto, consultaTutorial: Implementa un'applicazione Hello World con AWS SAM. Quando viene richiesto il tipo di pacchetto da installare, sceglieteImage.

Nota

Se specifichi un'immagine di base multiarchitettura nel tuo Dockerfile, AWS SAM crea l'immagine del contenitore per l'architettura della tua macchina host. Per creare per un'architettura diversa, specifica un'immagine di base che utilizzi l'architettura di destinazione specifica.

File variabile di ambiente del contenitore

Per fornire un file JSON che contenga variabili di ambiente per il contenitore di compilazione, usa l'--container-env-var-fileargomento con il sam build comando. Puoi fornire una singola variabile di ambiente che si applica a tutte le risorse serverless o variabili di ambiente diverse per ogni risorsa.

Formato

Il formato per il passaggio delle variabili di ambiente a un contenitore di build dipende dal numero di variabili di ambiente fornite per le risorse.

Per fornire un'unica variabile di ambiente per tutte le risorse, specifica un Parameters oggetto come il seguente:

{
  "Parameters": {
    "GITHUB_TOKEN": "TOKEN_GLOBAL"
  }
}

Per fornire variabili di ambiente diverse per ogni risorsa, specificate gli oggetti per ogni risorsa come segue:

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

Salvate le variabili di ambiente come file, ad esempio denominatoenv.json. Il comando seguente utilizza questo file per passare le variabili di ambiente al contenitore di compilazione:

sam build --use-container --container-env-var-file env.json

Priorità

• Le variabili di ambiente fornite per risorse specifiche hanno la precedenza sulla singola variabile di ambiente per tutte le risorse.

• Le variabili di ambiente fornite nella riga di comando hanno la precedenza sulle variabili di ambiente in un file.

Accelera i tempi di compilazione creando il progetto nella cartella dei sorgenti

Per i runtime e i metodi di compilazione supportati, puoi utilizzare l'--build-in-sourceopzione per creare il tuo progetto direttamente nella cartella di origine. Per impostazione predefinita, AWS SAM CLI le build si trovano in una directory temporanea, che prevede la copia del codice sorgente e dei file di progetto. Con--build-in-source, AWS SAM CLI le build vengono create direttamente nella cartella di origine, il che accelera 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

Esempi

Esempio 1: archivio di file.zip

I seguenti sam build comandi creano un archivio di file.zip:

# Build all functions and layers, and their dependencies
sam build

# Run the build process inside a Docker container that functions like a Lambda environment
sam build --use-container

# Build a Node.js 20 application using a container image for a specific version of AWS SAM CLI (1.136.0)
sam build --use-container --build-image public.ecr.aws/sam/build-nodejs22.x:1.136.0

# Build a function resource using the Python 3.13 container image from a specific version of AWS SAM CLI (1.136.0)(
sam build --use-container --build-image Function1=public.ecr.aws/sam/build-python3.13:1.136.0

# Build and run your functions locally
sam build && sam local invoke

# For more options
sam build --help

Esempio 2: immagine del contenitore

Il seguente AWS SAM modello viene creato come immagine del contenitore:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      PackageType: Image
      ImageConfig:
        Command: ["app.lambda_handler"]
    Metadata:
      Dockerfile: Dockerfile
      DockerContext: ./hello_world
      DockerTag: v1

Di seguito è riportato un esempio di Dockerfile:

FROM public.ecr.aws/lambda/python:3.12

COPY app.py requirements.txt ./

RUN python3.12 -m pip install -r requirements.txt

# Overwrite the command by providing a different command directly in the template.
CMD ["app.lambda_handler"]

Esempio 3: npm ci

Per le applicazioni Node.js, è possibile utilizzare npm ci invece di npm install installare le dipendenze. Per utilizzarlonpm ci, specifica UseNpmCi: True sotto BuildProperties nell'attributo Metadata resource della funzione Lambda. Per essere utilizzatanpm ci, l'applicazione deve avere un npm-shrinkwrap.json file package-lock.json or presente nella funzione CodeUri for your Lambda.

L'esempio seguente utilizza npm ci per installare le dipendenze durante l'esecuzione: sam build

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: hello-world/
      Handler: app.handler
      Runtime: nodejs20.x
      Architectures:
        - x86_64
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /hello
            Method: get
    Metadata:
      BuildProperties:
        UseNpmCi: True

Pacchetti principali in Python

Per le applicazioni Python, puoi preservare la struttura del pacchetto durante il processo di compilazione per abilitare le importazioni assolute. Per preservare la struttura del pacchetto, specifica parent_python_packages sotto BuildProperties nell'attributo Metadata resource della funzione Lambda.

L'esempio seguente conserva la struttura del app pacchetto durante l'esecuzione: sam build

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: hello-world/
      Handler: app.main.handler
      Runtime: python3.12
      Architectures:
        - x86_64
    Metadata:
      BuildProperties:
        parent_python_packages: app

Con questa configurazione, il codice può utilizzare importazioni assolute come from app.utils import logger invece di importazioni relative comefrom .utils import logger.

Costruire funzioni al di fuori di AWS SAM

Per impostazione predefinita, quando si eseguesam build, AWS SAM crea tutte le risorse funzionali. Altre opzioni includono:

• Costruisci tutte le risorse funzionali all'esterno di AWS SAM: se crei tutte le tue risorse funzionali manualmente o tramite un altro strumento, non sam build è necessario. Puoi saltare sam build e passare alla fase successiva del processo, ad esempio l'esecuzione di test locali o la distribuzione dell'applicazione.

• Crea alcune risorse funzionali all'esterno AWS SAM: se desideri AWS SAM creare alcune delle tue risorse funzionali con altre risorse funzionali integrate all'esterno AWS SAM, puoi specificarlo nel tuo AWS SAM modello.

Crea alcune risorse funzionali al di fuori di AWS SAM

Per fare in modo che una funzione venga AWS SAM ignorata durante l'utilizzosam build, configura quanto segue nel AWS SAM modello:

1. Aggiungi la proprietà SkipBuild: True dei metadati alla tua funzione.

2. Specificate il percorso delle risorse funzionali integrate.

Ecco un esempio, con TestFunction configurato per essere ignorato. Le sue risorse integrate si trovano inbuilt-resources/TestFunction.zip.

TestFunction:
  Type: AWS::Serverless::Function
  Properties:
    CodeUri: built-resources/TestFunction.zip
    Handler: TimeHandler::handleRequest
    Runtime: java11
  Metadata:
    SkipBuild: True

Ora, quando corrisam build, AWS SAM farà quanto segue:

1. AWS SAM salterà le funzioni configurate conSkipBuild: True.

2. AWS SAM creerà tutte le altre risorse funzionali e le memorizzerà nella directory di .aws-sam compilazione.

3. Per le funzioni ignorate, il relativo modello nella directory di .aws-sam compilazione verrà automaticamente aggiornato per fare riferimento al percorso specificato delle risorse delle funzioni create.

   Ecco un esempio del modello memorizzato nella cache per TestFunction nella directory di .aws-sam compilazione:

   TestFunction:
     Type: AWS::Serverless::Function
     Properties:
       CodeUri: ../../built-resources/TestFunction.zip
       Handler: TimeHandler::handleRequest
       Runtime: java11
     Metadata:
       SkipBuild: True