Exemple d'application de fonction vide pour AWS Lambda

L'exemple d'application de fonction vide est une application de démarrage qui montre des opérations courantes dans Lambda avec une fonction qui appelle l'API Lambda. Il montre l'utilisation de la journalisation, des variables d'environnement, du suivi AWS X-Ray, des couches, des tests unitaires et du kit AWS SDK. Explorez cette application pour en savoir plus sur la création de fonctions Lambda dans votre langage de programmation, ou utilisez-la comme point de départ pour vos propres projets.

Les variantes de cet exemple d'application sont disponibles dans les langues suivantes :

Variantes

• Node.js – blank-nodejs.

• Python – blank-python.

• Ruby – blank-ruby.

• Java – blank-java.

• Go – blank-go.

• C# – blank-csharp.

• PowerShell — PowerShell blanc.

Les exemples de cette rubrique mettent en évidence le code de la version Node.js, mais les détails sont généralement applicables à toutes les variantes.

Vous pouvez déployer l'exemple en quelques minutes avec l'AWS CLI et AWS CloudFormation. Suivez les instructions indiquées dans le fichier README pour le télécharger, le configurer et le déployer dans votre compte.

Architecture et code de gestionnaire

L'exemple d'application se compose d'un code de fonction, d'un modèle AWS CloudFormation et de ressources associées. Lorsque vous déployez l'exemple, vous utilisez les services AWS suivants :

• AWS Lambda— Exécute le code de fonction, envoie les CloudWatch journaux à Logs et envoie les données de suivi à X-Ray. La fonction appelle également l'API Lambda pour obtenir des détails sur les quotas et l'utilisation du compte dans la région actuelle.

• AWS X-Ray – Collecte des données de suivi, indexe les suivis pour la recherche et génère une cartographie du service.

• Amazon CloudWatch — Stocke les journaux et les statistiques.

• AWS Identity and Access Management(IAM) – Octroie l'autorisation.

• Amazon Simple Storage Service (Amazon S3) – Stocke le package de déploiement de la fonction pendant le déploiement.

• AWS CloudFormation – Crée des ressources d'application et déploie le code de la fonction.

Des frais standard s'appliquent pour chaque service. Pour plus d'informations, consultez Tarification AWS.

Le code de la fonction affiche un flux de travail de base pour le traitement d'un événement. Le gestionnaire prend un événement Amazon Simple Queue Service (Amazon SQS) en entrée et parcourt les enregistrements qu'il contient, en consignant le contenu de chaque message. Il enregistre le contenu de l'événement, l'objet de contexte et les variables d'environnement. Ensuite, il effectue un appel avec le kit SDK AWS et renvoie la réponse au runtime Lambda.

Exemple blank-nodejs/function/index.js – Code du gestionnaire

// Handler
exports.handler = async function(event, context) {
  event.Records.forEach(record => {
    console.log(record.body)
  })
  console.log('## ENVIRONMENT VARIABLES: ' + serialize(process.env))
  console.log('## CONTEXT: ' + serialize(context))
  console.log('## EVENT: ' + serialize(event))
  
  return getAccountSettings()
}

// Use SDK client
var getAccountSettings = function(){
  return lambda.getAccountSettings().promise()
}

var serialize = function(object) {
  return JSON.stringify(object, null, 2)
}

Les types d'entrée/sortie pour le gestionnaire et la prise en charge de la programmation asynchrone varient en fonction de l'exécution. Dans cet exemple, la méthode de gestionnaire est async, donc dans Node.js cela signifie qu'il doit retourner une promesse à l'exécution. Le runtime Lambda attend que la promesse soit résolue et renvoie la réponse à l'appelant. Si le code de fonction ou le client AWS SDK renvoie une erreur, l'exécution formate l'erreur dans un document JSON et le renvoie.

L'exemple d'application n'inclut pas de file d’attente Amazon SQS pour envoyer des événements, mais utilise un événement d'Amazon SQS (event.json) pour illustrer le traitement des événements. Pour ajouter une file d’attente Amazon SQS à votre application, consultez Utilisation de Lambda avec Amazon SQS.

Automatisation du déploiement avec AWS CloudFormation et l’AWS CLI

Les ressources de l'exemple d'application sont définies dans un modèle AWS CloudFormation et déployées avec le AWS CLI. Le projet comprend des scripts shell simples qui automatisent le processus de configuration, de déploiement, d'appel et de déchirement de l'application.

Le modèle d'application utilise un type de ressource AWS Serverless Application Model (AWS SAM) pour définir le modèle. AWS SAM simplifie la création de modèles pour les applications sans serveur en automatisant la définition des rôles d'exécution, des API et d'autres ressources.

Le modèle définit les ressources dans la pile d'applications. Cela inclut la fonction, son rôle d'exécution et une couche Lambda qui fournit les dépendances de bibliothèque de la fonction. La pile n'inclut pas le bucket AWS CLI utilisé lors du déploiement ni le groupe de CloudWatch journaux Logs.

Exemple blank-nodejs/template.yml – Ressources sans serveur

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description: An AWS Lambda application that calls the Lambda API.
Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs16.x
      CodeUri: function/.
      Description: Call the AWS Lambda API
      Timeout: 10
      # Function's execution role
      Policies:
        - AWSLambdaBasicExecutionRole
        - AWSLambda_ReadOnlyAccess
        - AWSXrayWriteOnlyAccess
      Tracing: Active
      Layers:
        - !Ref libs
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs16.x

Lorsque vous déployez l'application, AWS CloudFormation applique la transformation AWS SAM au modèle pour générer un modèle AWS CloudFormation avec des types standard tels que AWS::Lambda::Function et AWS::IAM::Role.

Exemple modèle traité

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "An AWS Lambda application that calls the Lambda API.",
  "Resources": {
    "function": {
      "Type": "AWS::Lambda::Function",
      "Properties": {
        "Layers": [
          {
            "Ref": "libs32xmpl61b2"
          }
        ],
        "TracingConfig": {
          "Mode": "Active"
        },
        "Code": {
          "S3Bucket": "lambda-artifacts-6b000xmpl1e9bf2a",
          "S3Key": "3d3axmpl473d249d039d2d7a37512db3"
        },
        "Description": "Call the AWS Lambda API",
        "Tags": [
          {
            "Value": "SAM",
            "Key": "lambda:createdBy"
          }
        ],

Dans cet exemple, la propriété Code spécifie un objet dans un compartiment Amazon S3. Ceci correspond au chemin local de la propriété CodeUri dans le modèle de projet :

      CodeUri: function/.

Pour charger les fichiers de projet vers Amazon S3, le script de déploiement utilise des commandes de l'AWS CLI. La commande cloudformation package prétraite le modèle, charge les artefacts et remplace les chemins locaux par des emplacements d'objet Amazon S3. La commande cloudformation deploy déploie le modèle traité avec un jeu de modifications AWS CloudFormation.

Exemple blank-nodejs/3-deploy.sh – Conditionner en package et déployer

#!/bin/bash
set -eo pipefail
ARTIFACT_BUCKET=$(cat bucket-name.txt)
aws cloudformation package --template-file template.yml --s3-bucket $ARTIFACT_BUCKET --output-template-file out.yml
aws cloudformation deploy --template-file out.yml --stack-name blank-nodejs --capabilities CAPABILITY_NAMED_IAM

La première fois que vous exécutez ce script, il crée une pile AWS CloudFormation nommée blank-nodejs. Si vous apportez des modifications au code de fonction ou au modèle, vous pouvez l'exécuter à nouveau pour mettre à jour la pile.

Le script de nettoyage (blank-nodejs/5-cleanup.sh) supprime la pile et supprime éventuellement le compartiment de déploiement et les journaux de fonctions.

Instrumentation avec le AWS X-Ray

L'exemple de fonction est configuré pour le suivi avec AWS X-Ray. Lorsque le mode de suivi est activé, Lambda enregistre des informations de durée pour un sous-ensemble d'appels et les envoie à X-Ray. X-Ray traite les données pour générer une cartographie du service présentant un nœud client et deux nœuds de service.

Le premier nœud de service (AWS::Lambda) représente le service Lambda qui valide la demande d'appel et l'envoie à la fonction. Le deuxième nœud, AWS::Lambda::Function, représente la fonction elle-même.

Pour enregistrer des détails supplémentaires, l'exemple de fonction utilise le kit SDK X-Ray. Avec les modifications minimales apportées au code de fonction, le kit SDK X-Ray enregistre les détails sur les appels effectués avec le kit SDK AWS vers les services AWS.

Exemple blank-nodejs/function/index.js – Instrumentation

const AWSXRay = require('aws-xray-sdk-core')
const AWS = AWSXRay.captureAWS(require('aws-sdk'))

// Create client outside of handler to reuse
const lambda = new AWS.Lambda()

L'instrumentation du client AWS SDK ajoute un nœud supplémentaire à la carte de service et plus de détails dans les suivis. Dans cet exemple, la carte de service affiche l'exemple de fonction appelant l'API Lambda pour obtenir des détails sur le stockage et l'utilisation simultanée dans la région actuelle.

Le suivi affiche les détails de synchronisation de l'invocation, avec des sous-segments pour l'initialisation de la fonction, l'invocation et la surcharge. Le sous-segment d'appel comporte un sous-segment pour l'appel AWS SDK à l'opération d'API GetAccountSettings.

Vous pouvez inclure le kit SDK X-Ray et d'autres bibliothèques dans le package de déploiement de votre fonction, ou les déployer séparément dans une couche Lambda. Pour Node.js, Ruby et Python, le runtime Lambda inclut le kit SDK AWS dans l'environnement d'exécution.

Gestion des dépendances avec des couches

Vous pouvez installer des bibliothèques localement et les inclure dans le package de déploiement que vous chargez sur Lambda, mais cela présente ses inconvénients. Des tailles de fichier plus grandes entraînent une augmentation des temps de déploiement et peuvent vous empêcher de tester les modifications apportées à votre code de fonction dans la console Lambda. Pour conserver un package de déploiement de petite taille et éviter le chargement de dépendances qui n'ont pas changé, l'exemple d'application crée une couche Lambda et l'associe à la fonction.

Exemple blank-nodejs/template.yml – Couche de dépendances

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs16.x
      CodeUri: function/.
      Description: Call the AWS Lambda API
      Timeout: 10
      # Function's execution role
      Policies:
        - AWSLambdaBasicExecutionRole
        - AWSLambda_ReadOnlyAccess
        - AWSXrayWriteOnlyAccess
      Tracing: Active
      Layers:
        - !Ref libs
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs16.x

Le script 2-build-layer.sh installe les dépendances de la fonction avec npm, et les place dans un dossier avec la structure requise par le runtime Lambda.

Exemple 2-build-layer.sh – Préparation de la couche

#!/bin/bash
set -eo pipefail
mkdir -p lib/nodejs
rm -rf node_modules lib/nodejs/node_modules
npm install --production
mv node_modules lib/nodejs/

La première fois que vous déployez l'exemple d'application, AWS CLI crée un package pour la couche distinct de celui du code de fonction et déploie les deux. Pour les déploiements ultérieurs, l'archive de couches n'est téléchargée que si le contenu du dossier lib a changé.