Este é o Guia do Desenvolvedor AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Neste tutorial, você usa o AWS Cloud Development Kit (AWS CDK) para criar um sistema simples sem servidor Hello World aplicativo que implementa um back-end básico de API que consiste no seguinte:
-
Amazon API Gateway REST API— Fornece um endpoint HTTP que é usado para invocar sua função por meio de um HTTP GET pedido.
-
AWS Lambda function — Função que retorna uma
Hello World!
mensagem quando invocada com o HTTP ponto final. -
Integrações e permissões — Detalhes de configuração e permissões para que seus recursos interajam entre si e realizem ações, como gravar registros na Amazon CloudWatch.
O diagrama a seguir mostra os componentes deste aplicação:

Neste tutorial, você criará e interagirá com a aplicação nas seguintes etapas:
-
Crie um AWS CDK projeto.
-
Defina uma função Lambda e a API REST do API Gateway usando construções L2 da Construct Library. AWS
-
Implante seu aplicativo no Nuvem AWS.
-
Interaja com seu aplicativo no Nuvem AWS.
-
Exclua a amostra da aplicação do Nuvem AWS.
Tópicos
Pré-requisitos
Antes de começar este tutorial, conclua as seguintes etapas:
-
Crie um Conta da AWS e tenha o AWS Command Line Interface (AWS CLI) instalado e configurado.
-
Instalar Node.js and npm.
-
Instalar o CDK Toolkit globalmente, usando
npm install -g aws-cdk
.
Para obter mais informações, consulte Começando com o AWS CDK.
Também recomendamos uma compreensão básica do seguinte:
-
O que é o AWS CDK?para uma introdução básica ao AWS CDK.
-
Aprenda os AWS CDK principais conceitos para uma visão geral dos principais conceitos do AWS CDK.
Etapa 1: criar um projeto CDK
Nesta etapa, você cria um novo projeto CDK usando o AWS CDK CLI comando cdk init
.
Para criar um projeto CDK
-
Em um diretório inicial de sua escolha, crie e navegue até um diretório de projeto chamado
cdk-hello-world
na sua máquina:$
mkdir cdk-hello-world && cd cdk-hello-world
-
Use o comando
cdk init
para criar um novo projeto na linguagem de programação de sua preferência:$
cdk init --language typescript
Instale AWS CDK bibliotecas:
$
npm install aws-cdk-lib constructs
O CDK CLI cria um projeto com a seguinte estrutura:
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
O CDK CLI cria automaticamente um aplicativo CDK que contém uma única pilha. A instância da aplicação CDK é criada a partir da classe App
. A seguir está uma parte do seu arquivo de aplicação CDK:
Localizado em 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', {
});
Etapa 2: Criar sua função do Lambda
Em seu projeto CDK, crie um diretório lambda
que inclua um novo arquivo hello.js
. Veja um exemplo a seguir:
Da raiz do seu projeto, execute o seguinte:
$
mkdir lambda && cd lambda
$
touch hello.js
Agora, o seguinte deve ser adicionado ao seu projeto CDK:
cdk-hello-world
└── lambda
└── hello.js
nota
Para manter este tutorial simples, usamos um JavaScript Função Lambda para todas as linguagens de programação CDK.
Defina a função do Lambda adicionando o arquivo recém-criado:
exports.handler = async (event) => {
return {
statusCode: 200,
headers: { "Content-Type": "text/plain" },
body: JSON.stringify({ message: "Hello, World!" }),
};
};
Etapa 3: definir seus constructos
Nesta etapa, você definirá seus recursos do Lambda e do API Gateway usando construções AWS CDK L2.
Abra o arquivo do projeto que define sua pilha de CDK. Você modificará esse arquivo para definir seus constructos. Veja a seguir um exemplo do arquivo de pilha inicial:
Localizado em 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
}
}
Nesse arquivo, o AWS CDK está fazendo o seguinte:
-
Sua instância de pilha do CDK é instanciada a partir da classe
Stack
. -
A classe base
Constructs
é importada e fornecida como escopo ou pai da sua instância de pilha.
Definir recursos da sua função do Lambda
Para definir seu recurso de função do Lambda, você importa e usa o constructo aws-lambda
L2 da Biblioteca de Constructos da AWS .
Modifique seu arquivo de pilha da seguinte forma:
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
});
}
}
Aqui, você cria um recurso de função do Lambda e define as propriedades a seguir:
-
runtime
— O ambiente em que a função é executada. Aqui, usamos Node.js version 20.x. -
code
— O caminho para o código de função em sua máquina local. -
handler
— O nome do arquivo específico que contém seu código de função.
Defina seu API Gateway REST API recurso
Para definir seu API Gateway REST API recurso, você importa e usa a construção aws-apigateway
L2 da Construct Library. AWS
Modifique seu arquivo de pilha da seguinte forma:
// ...
//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');
}
}
Aqui, você cria um API Gateway REST API recurso, junto com o seguinte:
-
Uma integração entre o REST API e sua função Lambda, permitindo que a API invoque sua função. Isso inclui a criação de um recurso de permissão do Lambda.
-
Um novo recurso ou caminho chamado
hello
que é adicionado à raiz do endpoint da API. Isso cria um novo endpoint que é adicionado/hello
à sua base URL. -
Um método GET para o recurso
hello
. Quando uma solicitação GET é enviada ao endpoint/hello
, você invoca a função do Lambda e retorna a resposta.
Etapa 4: preparar sua aplicação para a implantação
Nesta etapa, você prepara seu aplicativo para implantação criando, se necessário, e executando a validação básica com o AWS CDK CLI comando cdk synth
.
Se necessário, crie sua aplicação:
Da raiz do seu projeto, execute o seguinte:
$
npm run build
Execute cdk synth
para sintetizar um AWS CloudFormation modelo a partir do seu código CDK. Ao usar construções L2, muitos dos detalhes de configuração exigidos AWS CloudFormation para facilitar a interação entre sua função Lambda e REST API são provisionados para você pelo. AWS CDK
Da raiz do seu projeto, execute o seguinte:
$
cdk synth
nota
Se você receber um erro como o seguinte, verifique se você está no diretório cdk-hello-world
e tente novamente:
--app is required either in command-line, in cdk.json or in ~/.cdk.json
Se for bem-sucedido, o AWS CDK CLI produzirá o AWS CloudFormation modelo em YAML formato no prompt de comando. A JSON o modelo formatado também é salvo no cdk.out
diretório.
Veja a seguir um exemplo de saída do AWS CloudFormation modelo:
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.
Ao usar constructos L2, você define algumas propriedades para configurar seus recursos e usa métodos auxiliares para integrá-los. O AWS CDK configura a maioria dos AWS CloudFormation recursos e propriedades necessários para provisionar seu aplicativo.
Etapa 5: implantar a aplicação
Nesta etapa, você usa o AWS CDK CLI cdk deploy
comando para implantar seu aplicativo. Ele AWS CDK trabalha com o AWS CloudFormation serviço para provisionar seus recursos.
Importante
Você deve executar uma única inicialização do seu AWS ambiente antes da implantação. Para obter instruções, consulte Inicialize seu ambiente para uso com o AWS CDK.
Da raiz do seu projeto, execute o seguinte. Confirme as alterações, se solicitado:
$
cdk deploy
✨ Synthesis time: 2.44s ... Do you wish to deploy these changes (y/n)?y
Quando a implantação for concluída, o AWS CDK CLI exibirá o URL do seu endpoint. Copie esse URL para a próxima etapa. Veja um exemplo a seguir:
... ✅ 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
...
Etapa 6: Interagir com sua aplicação
Nesta etapa, você inicia uma solicitação GET para seu endpoint da API e recebe a resposta da sua função do Lambda.
Localize o URL do endpoint da etapa anterior e adicione o caminho /hello
. Em seguida, usando seu navegador ou a linha de comando, envie uma solicitação GET para seu endpoint. Veja um exemplo a seguir:
$
curl https://
{"message":"Hello World!"}%<api-id>
.execute-api.<region>
.amazonaws.com/prod/hello
Parabéns, você criou, implantou e interagiu com sucesso com sua aplicação usando o AWS CDK!
Etapa 7: Excluir sua aplicação
Nesta etapa, você usa o AWS CDK CLI para excluir seu aplicativo do Nuvem AWS.
Para excluir sua aplicação, execute cdk destroy
. Quando solicitado, confirme sua solicitação para excluir a aplicação:
$
cdk destroy
Are you sure you want to delete: CdkHelloWorldStack (y/n)?y
CdkHelloWorldStack: destroying... [1/1] ... ✅ CdkHelloWorldStack: destroyed
Solução de problemas
Erro: {“message”: “Erro interno do servidor”}%
Ao invocar a função do Lambda implantada, você recebe esse erro. Esse erro pode ocorrer por vários motivos.
Para solucionar problemas ainda mais
Use o AWS CLI para invocar sua função Lambda.
-
Modifique seu arquivo de pilha para capturar o valor de saída do nome da função do Lambda implantada. Veja um exemplo a seguir:
... 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 // ...
-
Implante a aplicação novamente. O AWS CDK CLI exibirá o valor do nome da função Lambda implantada:
$
cdk deploy
✨ Synthesis time: 0.29s ... ✅ CdkHelloWorldStack ✨ Deployment time: 20.36s Outputs: ... CdkHelloWorldStack.HelloWorldFunctionName = CdkHelloWorldStack-HelloWorldFunctionunique-identifier
... -
Use o AWS CLI para invocar sua função Lambda no e enviar Nuvem AWS a resposta para um arquivo de texto:
$
aws lambda invoke --function-name CdkHelloWorldStack-HelloWorldFunction
unique-identifier
output.txt -
Verifique
output.txt
para ver seus resultados.
- Possível causa: o recurso API Gateway está definido incorretamente em seu arquivo de pilha.
-
Se o
output.txt
mostrar uma resposta bem-sucedida da função do Lambda, o problema pode estar na forma como você definiu sua API REST do API Gateway. Ele AWS CLI invoca seu Lambda diretamente, não por meio de seu endpoint. Verifique seu código para garantir que ele corresponda a este tutorial. Em seguida, implante novamente. - Possível causa: o recurso Lambda está definido incorretamente em seu arquivo de pilha.
-
Se o
output.txt
retornar um erro, o problema pode estar na forma como você definiu sua função do Lambda. Verifique seu código para garantir que ele corresponda a este tutorial. Em seguida, implante novamente.