Ceci est le guide du AWS CDK développeur de la version 2. L'ancien CDK v1 est entré en maintenance le 1er juin 2022 et a pris fin le 1er juin 2023.
Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Dans ce didacticiel, vous utiliserez le AWS Cloud Development Kit (AWS CDK) pour créer un système sans serveur simple Hello World application qui implémente un backend d'API de base composé des éléments suivants :
-
Amazon API Gateway REST API— Fournit un point de terminaison HTTP qui est utilisé pour appeler votre fonction via un HTTP GET demande.
-
AWS Lambda function — Fonction qui renvoie un
Hello World!
message lorsqu'elle est invoquée avec HTTP point de terminaison. -
Intégrations et autorisations : détails de configuration et autorisations permettant à vos ressources d'interagir entre elles et d'effectuer des actions, telles que la rédaction de journaux sur Amazon CloudWatch.
Le diagramme suivant montre les composants de cette application :

Dans le cadre de ce didacticiel, vous allez créer et interagir avec votre application en suivant les étapes suivantes :
-
Créez un AWS CDK projet.
-
Définissez une fonction Lambda et une API REST API Gateway à l'aide des constructions L2 de la bibliothèque Construct. AWS
-
Déployez votre application sur le AWS Cloud.
-
Interagissez avec votre application dans le AWS Cloud.
-
Supprimer l'exemple d'application du AWS Cloud.
Rubriques
Prérequis
Avant de commencer ce didacticiel, exécutez les tâches suivantes :
-
Créez un Compte AWS et faites installer et configurer le AWS Command Line Interface (AWS CLI).
-
Installation Node.js and npm.
-
Installez le kit d'outils CDK globalement, en utilisant
npm install -g aws-cdk
.
Pour de plus amples informations, veuillez consulter Commencer à utiliser le AWS CDK.
Nous recommandons également une compréhension de base des éléments suivants :
-
Qu'est-ce que c'est AWS CDK ?pour une introduction de base au AWS CDK.
-
Apprenez les concepts AWS CDK de basepour un aperçu des concepts fondamentaux du AWS CDK.
Étape 1 : Création d'un projet CDK
Au cours de cette étape, vous allez créer un nouveau projet CDK à l'aide du AWS CDK CLI cdk init
commande.
Pour créer un projet CDK
-
À partir du répertoire de départ de votre choix, créez et naviguez vers un répertoire de projet nommé
cdk-hello-world
sur votre machine :$
mkdir cdk-hello-world && cd cdk-hello-world
-
Utilisez la
cdk init
commande pour créer un nouveau projet dans votre langage de programmation préféré :$
cdk init --language typescript
Installez AWS CDK les bibliothèques :
$
npm install aws-cdk-lib constructs
Le CDK CLI crée un projet avec la structure suivante :
cdk-hello-world ├── .git ├── .gitignore ├── .npmignore ├── README.md ├── bin │ └── cdk-hello-world.ts ├── cdk.json ├── jest.config.js ├── lib │ └── cdk-hello-world-stack.ts ├── node_modules ├── package-lock.json ├── package.json ├── test │ └── cdk-hello-world.test.ts └── tsconfig.json
Le CDK CLI crée automatiquement une application CDK contenant une seule pile. L'instance de l'application CDK est créée à partir de la App
classe. Voici une partie de votre fichier de candidature CDK :
Situé dans bin/cdk-hello-world.ts
:
#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { CdkHelloWorldStack } from '../lib/cdk-hello-world-stack';
const app = new cdk.App();
new CdkHelloWorldStack(app, 'CdkHelloWorldStack', {
});
Étape 2 : Création de votre fonction Lambda
Dans votre projet CDK, créez un lambda
répertoire qui inclut un nouveau hello.js
fichier. Voici un exemple :
À partir de la racine de votre projet, exécutez ce qui suit :
$
mkdir lambda && cd lambda
$
touch hello.js
Les éléments suivants devraient maintenant être ajoutés à votre projet CDK :
cdk-hello-world
└── lambda
└── hello.js
Note
Pour simplifier ce didacticiel, nous utilisons un JavaScript Fonction Lambda pour tous les langages de programmation CDK.
Définissez votre fonction Lambda en ajoutant ce qui suit au fichier nouvellement créé :
exports.handler = async (event) => {
return {
statusCode: 200,
headers: { "Content-Type": "text/plain" },
body: JSON.stringify({ message: "Hello, World!" }),
};
};
Étape 3 : Définissez vos constructions
Au cours de cette étape, vous allez définir vos ressources Lambda et API Gateway à l'aide de constructions AWS CDK L2.
Ouvrez le fichier de projet qui définit votre pile de CDK. Vous allez modifier ce fichier pour définir vos constructions. Voici un exemple de votre fichier de pile de départ :
Situé dans lib/cdk-hello-world-stack.ts
:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
export class CdkHelloWorldStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Your constructs will go here
}
}
Dans ce fichier, AWS CDK il effectue les opérations suivantes :
-
Votre instance de stack CDK est instanciée à partir de la classe.
Stack
-
La classe
Constructs
de base est importée et fournie en tant que portée ou parent de votre instance de stack.
Définissez votre ressource de fonction Lambda
Pour définir votre ressource de fonction Lambda, vous devez importer et utiliser la construction aws-lambda
L2 depuis la AWS bibliothèque de constructions.
Modifiez votre fichier de pile comme suit :
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
// Import Lambda L2 construct
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkHelloWorldStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define the Lambda function resource
const helloWorldFunction = new lambda.Function(this, 'HelloWorldFunction', {
runtime: lambda.Runtime.NODEJS_20_X, // Choose any supported Node.js runtime
code: lambda.Code.fromAsset('lambda'), // Points to the lambda directory
handler: 'hello.handler', // Points to the 'hello' file in the lambda directory
});
}
}
Ici, vous créez une ressource de fonction Lambda et définissez les propriétés suivantes :
-
runtime
— L'environnement dans lequel la fonction s'exécute. Ici, nous utilisons Node.js version 20.x. -
code
— Le chemin d'accès au code de fonction sur votre machine locale. -
handler
— Le nom du fichier spécifique qui contient votre code de fonction.
Définissez votre API Gateway REST API ressource
Pour définir votre API Gateway REST API ressource, vous importez et utilisez la construction aws-apigateway
L2 depuis la bibliothèque de AWS constructions.
Modifiez votre fichier de pile comme suit :
// ...
//Import API Gateway L2 construct
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
export class CdkHelloWorldStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// ...
// Define the API Gateway resource
const api = new apigateway.LambdaRestApi(this, 'HelloWorldApi', {
handler: helloWorldFunction,
proxy: false,
});
// Define the '/hello' resource with a GET method
const helloResource = api.root.addResource('hello');
helloResource.addMethod('GET');
}
}
Ici, vous créez une API Gateway REST API ressource, ainsi que les éléments suivants :
-
Une intégration entre REST API et votre fonction Lambda, permettant à l'API d'appeler votre fonction. Cela inclut la création d'une ressource d'autorisation Lambda.
-
Nouveau nom
hello
de ressource ou de chemin ajouté à la racine du point de terminaison de l'API. Cela crée un nouveau point de terminaison qui/hello
s'ajoute à votre base URL. -
Méthode GET pour la
hello
ressource. Lorsqu'une requête GET est envoyée au point de/hello
terminaison, la fonction Lambda est invoquée et sa réponse est renvoyée.
Étape 4 : préparer votre application pour le déploiement
Au cours de cette étape, vous préparez votre application pour le déploiement en créant, si nécessaire, et en effectuant une validation de base à l'aide du AWS CDK CLI cdk synth
commande.
Si nécessaire, créez votre application :
À partir de la racine de votre projet, exécutez ce qui suit :
$
npm run build
Exécutez cdk synth
pour synthétiser un AWS CloudFormation modèle à partir de votre code CDK. En utilisant des constructions L2, de nombreux détails de configuration sont nécessaires AWS CloudFormation pour faciliter l'interaction entre votre fonction Lambda et REST API sont fournis pour vous par le AWS CDK.
À partir de la racine de votre projet, exécutez ce qui suit :
$
cdk synth
Note
Si le message d'erreur suivant s'affiche, vérifiez que vous êtes bien dans le cdk-hello-world
répertoire et réessayez :
--app is required either in command-line, in cdk.json or in ~/.cdk.json
En cas de succès, le AWS CDK CLI affichera le AWS CloudFormation modèle dans YAML format à l'invite de commande. A JSON le modèle formaté est également enregistré dans le cdk.out
répertoire.
Voici un exemple de sortie du AWS CloudFormation modèle :
Resources:
HelloWorldFunctionServiceRoleunique-identifier
:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Statement:
- Action: sts:AssumeRole
Effect: Allow
Principal:
Service: lambda.amazonaws.com
Version: "2012-10-17"
ManagedPolicyArns:
- Fn::Join:
- ""
- - "arn:"
- Ref: AWS::Partition
- :iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldFunction/ServiceRole/Resource
HelloWorldFunctionunique-identifier
:
Type: AWS::Lambda::Function
Properties:
Code:
S3Bucket:
Fn::Sub: cdk-unique-identifier
-assets-${AWS::AccountId}-${AWS::Region}
S3Key: unique-identifier
.zip
Handler: hello.handler
Role:
Fn::GetAtt:
- HelloWorldFunctionServiceRoleunique-identifier
- Arn
Runtime: nodejs20.x
DependsOn:
- HelloWorldFunctionServiceRoleunique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldFunction/Resource
aws:asset:path: asset.unique-identifier
aws:asset:is-bundled: false
aws:asset:property: Code
HelloWorldApiunique-identifier
:
Type: AWS::ApiGateway::RestApi
Properties:
Name: HelloWorldApi
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Resource
HelloWorldApiDeploymentunique-identifier
:
Type: AWS::ApiGateway::Deployment
Properties:
Description: Automatically created by the RestApi construct
RestApiId:
Ref: HelloWorldApiunique-identifier
DependsOn:
- HelloWorldApihelloGETunique-identifier
- HelloWorldApihellounique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Deployment/Resource
HelloWorldApiDeploymentStageprod012345ABC
:
Type: AWS::ApiGateway::Stage
Properties:
DeploymentId:
Ref: HelloWorldApiDeploymentunique-identifier
RestApiId:
Ref: HelloWorldApiunique-identifier
StageName: prod
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/DeploymentStage.prod/Resource
HelloWorldApihellounique-identifier
:
Type: AWS::ApiGateway::Resource
Properties:
ParentId:
Fn::GetAtt:
- HelloWorldApiunique-identifier
- RootResourceId
PathPart: hello
RestApiId:
Ref: HelloWorldApiunique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Default/hello/Resource
HelloWorldApihelloGETApiPermissionCdkHelloWorldStackHelloWorldApiunique-identifier
:
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName:
Fn::GetAtt:
- HelloWorldFunctionunique-identifier
- Arn
Principal: apigateway.amazonaws.com
SourceArn:
Fn::Join:
- ""
- - "arn:"
- Ref: AWS::Partition
- ":execute-api:"
- Ref: AWS::Region
- ":"
- Ref: AWS::AccountId
- ":"
- Ref: HelloWorldApi9E278160
- /
- Ref: HelloWorldApiDeploymentStageprodunique-identifier
- /GET/hello
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Default/hello/GET/ApiPermission.CdkHelloWorldStackHelloWorldApiunique-identifier
.GET..hello
HelloWorldApihelloGETApiPermissionTestCdkHelloWorldStackHelloWorldApiunique-identifier
:
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName:
Fn::GetAtt:
- HelloWorldFunctionunique-identifier
- Arn
Principal: apigateway.amazonaws.com
SourceArn:
Fn::Join:
- ""
- - "arn:"
- Ref: AWS::Partition
- ":execute-api:"
- Ref: AWS::Region
- ":"
- Ref: AWS::AccountId
- ":"
- Ref: HelloWorldApiunique-identifier
- /test-invoke-stage/GET/hello
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Default/hello/GET/ApiPermission.Test.CdkHelloWorldStackHelloWorldApiunique-identifier
.GET..hello
HelloWorldApihelloGETunique-identifier
:
Type: AWS::ApiGateway::Method
Properties:
AuthorizationType: NONE
HttpMethod: GET
Integration:
IntegrationHttpMethod: POST
Type: AWS_PROXY
Uri:
Fn::Join:
- ""
- - "arn:"
- Ref: AWS::Partition
- ":apigateway:"
- Ref: AWS::Region
- :lambda:path/2015-03-31/functions/
- Fn::GetAtt:
- HelloWorldFunctionunique-identifier
- Arn
- /invocations
ResourceId:
Ref: HelloWorldApihellounique-identifier
RestApiId:
Ref: HelloWorldApiunique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/HelloWorldApi/Default/hello/GET/Resource
CDKMetadata:
Type: AWS::CDK::Metadata
Properties:
Analytics: v2:deflate64:unique-identifier
Metadata:
aws:cdk:path: CdkHelloWorldStack/CDKMetadata/Default
Condition: CDKMetadataAvailable
Outputs:
HelloWorldApiEndpointunique-identifier
:
Value:
Fn::Join:
- ""
- - https://
- Ref: HelloWorldApiunique-identifier
- .execute-api.
- Ref: AWS::Region
- "."
- Ref: AWS::URLSuffix
- /
- Ref: HelloWorldApiDeploymentStageprodunique-identifier
- /
Conditions:
CDKMetadataAvailable:
Fn::Or:
- Fn::Or:
- Fn::Equals:
- Ref: AWS::Region
- af-south-1
- Fn::Equals:
- Ref: AWS::Region
- ap-east-1
- Fn::Equals:
- Ref: AWS::Region
- ap-northeast-1
- Fn::Equals:
- Ref: AWS::Region
- ap-northeast-2
- Fn::Equals:
- Ref: AWS::Region
- ap-south-1
- Fn::Equals:
- Ref: AWS::Region
- ap-southeast-1
- Fn::Equals:
- Ref: AWS::Region
- ap-southeast-2
- Fn::Equals:
- Ref: AWS::Region
- ca-central-1
- Fn::Equals:
- Ref: AWS::Region
- cn-north-1
- Fn::Equals:
- Ref: AWS::Region
- cn-northwest-1
- Fn::Or:
- Fn::Equals:
- Ref: AWS::Region
- eu-central-1
- Fn::Equals:
- Ref: AWS::Region
- eu-north-1
- Fn::Equals:
- Ref: AWS::Region
- eu-south-1
- Fn::Equals:
- Ref: AWS::Region
- eu-west-1
- Fn::Equals:
- Ref: AWS::Region
- eu-west-2
- Fn::Equals:
- Ref: AWS::Region
- eu-west-3
- Fn::Equals:
- Ref: AWS::Region
- il-central-1
- Fn::Equals:
- Ref: AWS::Region
- me-central-1
- Fn::Equals:
- Ref: AWS::Region
- me-south-1
- Fn::Equals:
- Ref: AWS::Region
- sa-east-1
- Fn::Or:
- Fn::Equals:
- Ref: AWS::Region
- us-east-1
- Fn::Equals:
- Ref: AWS::Region
- us-east-2
- Fn::Equals:
- Ref: AWS::Region
- us-west-1
- Fn::Equals:
- Ref: AWS::Region
- us-west-2
Parameters:
BootstrapVersion:
Type: AWS::SSM::Parameter::Value<String>
Default: /cdk-bootstrap/hnb659fds/version
Description: Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]
Rules:
CheckBootstrapVersion:
Assertions:
- Assert:
Fn::Not:
- Fn::Contains:
- - "1"
- "2"
- "3"
- "4"
- "5"
- Ref: BootstrapVersion
AssertDescription: CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI.
En utilisant des constructions L2, vous définissez quelques propriétés pour configurer vos ressources et utilisez des méthodes d'assistance pour les intégrer ensemble. Il AWS CDK configure la majorité de vos AWS CloudFormation ressources et propriétés nécessaires au provisionnement de votre application.
Étape 5 : déployer votre application
Au cours de cette étape, vous utilisez AWS CDK CLI cdk deploy
commande pour déployer votre application. Il AWS CDK travaille avec le AWS CloudFormation service pour fournir vos ressources.
Important
Vous devez effectuer un démarrage unique de votre AWS environnement avant le déploiement. Pour obtenir des instructions, veuillez consulter Démarrez votre environnement pour l'utiliser avec AWS CDK.
À partir de la racine de votre projet, exécutez ce qui suit. Confirmez les modifications si vous y êtes invité :
$
cdk deploy
✨ Synthesis time: 2.44s ... Do you wish to deploy these changes (y/n)?y
Une fois le déploiement terminé, AWS CDK CLI affichera l'URL de votre point de terminaison. Copiez cette URL pour l'étape suivante. Voici un exemple :
... ✅ HelloWorldStack ✨ Deployment time: 45.37s Outputs: HelloWorldStack.HelloWorldApiEndpoint
unique-identifier
= https://<api-id>
.execute-api.<region>
.amazonaws.com/prod/ Stack ARN: arn:aws:cloudformation:region
:account-id
:stack/HelloWorldStack/unique-identifier
...
Étape 6 : Interagissez avec votre application
Au cours de cette étape, vous lancez une requête GET à destination de votre point de terminaison d'API et recevez la réponse de votre fonction Lambda.
Localisez l'URL de votre point de terminaison à l'étape précédente et ajoutez le /hello
chemin. Ensuite, à l'aide de votre navigateur ou de votre invite de commande, envoyez une requête GET à votre terminal. Voici un exemple :
$
curl https://
{"message":"Hello World!"}%<api-id>
.execute-api.<region>
.amazonaws.com/prod/hello
Félicitations, vous avez créé, déployé et interagi avec succès avec votre application à l'aide du AWS CDK !
Étape 7 : Supprimer votre application
Au cours de cette étape, vous utilisez AWS CDK CLI pour supprimer votre candidature du AWS Cloud.
Pour supprimer votre application, exécutezcdk destroy
. Lorsque vous y êtes invité, confirmez votre demande de suppression de l'application :
$
cdk destroy
Are you sure you want to delete: CdkHelloWorldStack (y/n)?y
CdkHelloWorldStack: destroying... [1/1] ... ✅ CdkHelloWorldStack: destroyed
Résolution des problèmes
Erreur : {« message » : « Erreur interne du serveur »} %
Lorsque vous appelez la fonction Lambda déployée, vous recevez cette erreur. Cette erreur peut se produire pour plusieurs raisons.
Pour résoudre d'autres problèmes
Utilisez le AWS CLI pour appeler votre fonction Lambda.
-
Modifiez votre fichier de pile pour capturer la valeur de sortie du nom de votre fonction Lambda déployée. Voici un exemple :
... class CdkHelloWorldStack extends Stack { constructor(scope, id, props) { super(scope, id, props); // Define the Lambda function resource // ... new CfnOutput(this, 'HelloWorldFunctionName', { value: helloWorldFunction.functionName, description: 'JavaScript Lambda function' }); // Define the API Gateway resource // ...
-
Déployez à nouveau votre application. Le AWS CDK CLI affichera la valeur du nom de votre fonction Lambda déployée :
$
cdk deploy
✨ Synthesis time: 0.29s ... ✅ CdkHelloWorldStack ✨ Deployment time: 20.36s Outputs: ... CdkHelloWorldStack.HelloWorldFunctionName = CdkHelloWorldStack-HelloWorldFunctionunique-identifier
... -
Utilisez le AWS CLI pour appeler votre fonction Lambda dans le AWS Cloud et afficher la réponse dans un fichier texte :
$
aws lambda invoke --function-name CdkHelloWorldStack-HelloWorldFunction
unique-identifier
output.txt -
Vérifiez
output.txt
vos résultats.
- Cause possible : la ressource API Gateway n'est pas définie correctement dans votre fichier de pile.
-
Si
output.txt
la réponse de la fonction Lambda est réussie, le problème vient peut-être de la façon dont vous avez défini votre API REST API Gateway. AWS CLI Invoque votre Lambda directement, et non via votre point de terminaison. Vérifiez votre code pour vous assurer qu'il correspond à ce didacticiel. Ensuite, déployez à nouveau. - Cause possible : la ressource Lambda n'est pas définie correctement dans votre fichier de pile.
-
S'il
output.txt
renvoie une erreur, le problème peut être lié à la façon dont vous avez défini votre fonction Lambda. Vérifiez votre code pour vous assurer qu'il correspond à ce didacticiel. Déployez ensuite à nouveau.