這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護,並於 2023 年 6 月 1 日結束支援。
本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
在本教學課程中,您會使用 AWS Cloud Development Kit (AWS CDK) 建立簡單的無伺服器Hello World應用程式,以實作基本 API 後端,其中包含下列項目:
-
Amazon API Gateway REST API – 提供 HTTP 端點,用於透過 HTTP GET請求叫用您的函數。
-
AWS Lambda 函數 – 使用HTTP端點叫用時傳回
Hello World!
訊息的函數。 -
整合和許可 – 資源彼此互動並執行動作的組態詳細資訊和許可,例如將日誌寫入 Amazon CloudWatch。
下圖顯示此應用程式的組件:

在本教學課程中,您將依照下列步驟建立應用程式並與其互動:
-
建立 AWS CDK 專案。
-
使用 建構程式庫中的 L2 建構模組來定義 Lambda AWS 函數和 API Gateway REST API。
-
將您的應用程式部署到 AWS 雲端。
-
在 中與您的應用程式互動 AWS 雲端。
-
從 刪除範例應用程式 AWS 雲端。
主題
先決條件
開始本教學課程之前,請完成下列動作:
-
建立 AWS 帳戶 並安裝並設定 AWS Command Line Interface (AWS CLI)。
-
安裝 Node.js和 npm。
-
使用 全域安裝 CDK Toolkit
npm install -g aws-cdk
。
如需詳細資訊,請參閱入門 AWS CDK。
我們也建議對以下內容有基本的了解:
-
什麼是 AWS CDK? 以取得 的基本簡介 AWS CDK。
-
了解 AWS CDK 核心概念 以取得 核心概念的概觀 AWS CDK。
步驟 1:建立 CDK 專案
在此步驟中,您會使用 cdk init
命令建立新的 CDK AWS CDK CLI專案。
建立 CDK 專案
-
從您選擇的起始目錄中,建立並導覽至您電腦上名為
cdk-hello-world
的專案目錄:$
mkdir cdk-hello-world && cd cdk-hello-world
-
使用
cdk init
命令,以您偏好的程式設計語言建立新的專案:$
cdk init --language typescript
安裝 AWS CDK 程式庫:
$
npm install aws-cdk-lib constructs
CDK 會使用下列結構CLI建立專案:
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
CDK CLI會自動建立包含單一堆疊的 CDK 應用程式。CDK 應用程式執行個體是從 App
類別建立的。以下是 CDK 應用程式檔案的一部分:
位於 : 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', {
});
步驟 2:建立 Lambda 函數
在 CDK 專案中,建立包含新hello.js
檔案的lambda
目錄。以下是範例:
從專案的根目錄執行下列動作:
$
mkdir lambda && cd lambda
$
touch hello.js
現在應該將下列項目新增至您的 CDK 專案:
cdk-hello-world
└── lambda
└── hello.js
注意
為了讓本教學課程保持簡單,我們針對所有 CDK 程式設計語言使用 JavaScript Lambda 函數。
將以下內容新增至新建立的檔案,以定義您的 Lambda 函數:
exports.handler = async (event) => {
return {
statusCode: 200,
headers: { "Content-Type": "text/plain" },
body: JSON.stringify({ message: "Hello, World!" }),
};
};
步驟 3:定義您的建構
在此步驟中,您將使用 L AWS CDK L2 建構模組定義 Lambda 和 API Gateway 資源。
開啟定義 CDK 堆疊的專案檔案。您將修改此檔案來定義您的建構。以下是啟動堆疊檔案的範例:
位於 : 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
}
}
在此檔案中, AWS CDK 正在執行下列動作:
-
您的 CDK 堆疊執行個體會從
Stack
類別執行個體化。 -
Constructs
基本類別會匯入並提供為堆疊執行個體的範圍或父系。
定義您的 Lambda 函數資源
若要定義 Lambda 函數資源,您可以從 AWS 建構程式庫匯入並使用 aws-lambda
L2 建構。
修改堆疊檔案,如下所示:
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
});
}
}
在這裡,您可以建立 Lambda 函數資源並定義下列屬性:
-
runtime
– 函數執行所在的環境。在這裡,我們使用Node.js版本 20.x。 -
code
– 本機電腦上函數程式碼的路徑。 -
handler
– 包含函數程式碼的特定檔案名稱。
定義您的 API Gateway REST API 資源
若要定義 API Gateway REST API 資源,您可以從 AWS 建構程式庫匯入並使用 aws-apigateway
L2 建構。
修改堆疊檔案,如下所示:
// ...
//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');
}
}
在這裡,您可以建立 API Gateway REST API 資源,以及下列項目:
-
REST API 與 Lambda 函數之間的整合,允許 API 叫用您的函數。這包括建立 Lambda 許可資源。
-
名為 的新資源或路徑
hello
,會新增至 API 端點的根目錄。這會建立新的端點,/hello
以新增至您的基礎 URL。 -
hello
資源的 GET 方法。當 GET 請求傳送至/hello
端點時,會叫用 Lambda 函數並傳回其回應。
步驟 4:準備您的應用程式以進行部署
在此步驟中,您可以視需要建置應用程式以部署,並使用 AWS CDK CLIcdk synth
命令執行基本驗證。
如有必要,請建置您的應用程式:
從專案的根目錄執行下列動作:
$
npm run build
執行 cdk synth
以從您的 CDK 程式碼合成 AWS CloudFormation 範本。透過使用 L2 建構, 所需的許多組態詳細資訊 AWS CloudFormation ,以促進 Lambda 函數與 為您REST API佈建的互動 AWS CDK。
從專案的根目錄,執行下列動作:
$
cdk synth
注意
如果您收到類似以下的錯誤,請確認您位於 cdk-hello-world
目錄中,然後再試一次:
--app is required either in command-line, in cdk.json or in ~/.cdk.json
如果成功, AWS CDK CLI會在命令提示字元以 YAML 格式輸出 AWS CloudFormation 範本。JSON 格式化範本也會儲存在 cdk.out
目錄中。
以下是 AWS CloudFormation 範本的範例輸出:
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.
透過使用 L2 建構,您可以定義幾個屬性來設定資源,並使用協助程式方法來整合資源。會 AWS CDK 設定佈建應用程式所需的大部分 AWS CloudFormation 資源和屬性。
步驟 5:部署應用程式
在此步驟中 AWS CDK CLI,您會使用 cdk deploy
命令來部署您的應用程式。 AWS CDK 可搭配 AWS CloudFormation 服務來佈建您的 資源。
重要
在部署 AWS 之前,您必須執行環境的一次性引導。如需說明,請參閱引導您的環境以搭配 使用 AWS CDK。
從專案的根目錄,執行下列動作。出現提示時確認變更:
$
cdk deploy
✨ Synthesis time: 2.44s ... Do you wish to deploy these changes (y/n)?y
部署完成時, AWS CDK CLI會輸出您的端點 URL。複製此 URL 以進行下一個步驟。以下是範例:
... ✅ 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
...
步驟 6:與您的應用程式互動
在此步驟中,您會對 API 端點啟動 GET 請求,並接收 Lambda 函數回應。
從上一個步驟找到您的端點 URL,並新增/hello
路徑。然後,使用您的瀏覽器或命令提示,將 GET 請求傳送至您的端點。以下是範例:
$
curl https://
{"message":"Hello World!"}%<api-id>
.execute-api.<region>
.amazonaws.com/prod/hello
恭喜,您已成功使用 建立、部署和與您的應用程式互動 AWS CDK!
步驟 7:刪除您的應用程式
在此步驟中,您會使用 AWS CDK CLI 從 刪除您的應用程式 AWS 雲端。
若要刪除您的應用程式,請執行 cdk destroy
。出現提示時,請確認您刪除應用程式的請求:
$
cdk destroy
Are you sure you want to delete: CdkHelloWorldStack (y/n)?y
CdkHelloWorldStack: destroying... [1/1] ... ✅ CdkHelloWorldStack: destroyed
故障診斷
錯誤:{「訊息」:「內部伺服器錯誤」}%
叫用部署的 Lambda 函數時,您會收到此錯誤。此錯誤可能有多種原因。
進一步疑難排解
使用 AWS CLI 來叫用 Lambda 函數。
-
修改堆疊檔案,以擷取已部署 Lambda 函數名稱的輸出值。以下是範例:
... 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 // ...
-
再次部署您的應用程式。將輸出已部署 Lambda AWS CDK CLI函數名稱的值:
$
cdk deploy
✨ Synthesis time: 0.29s ... ✅ CdkHelloWorldStack ✨ Deployment time: 20.36s Outputs: ... CdkHelloWorldStack.HelloWorldFunctionName = CdkHelloWorldStack-HelloWorldFunctionunique-identifier
... -
使用 AWS CLI 在 中叫用 Lambda 函數, AWS 雲端 並將回應輸出至文字檔案:
$
aws lambda invoke --function-name CdkHelloWorldStack-HelloWorldFunction
unique-identifier
output.txt -
檢查
output.txt
以查看結果。
- 可能原因:堆疊檔案中的 API Gateway 資源定義不正確。
-
如果
output.txt
顯示成功的 Lambda 函數回應,問題可能出在您定義 API Gateway REST API 的方式。會直接 AWS CLI 叫用您的 Lambda,而不是透過您的端點。檢查您的程式碼,以確保其符合本教學課程。然後,再次部署。 - 可能原因:堆疊檔案中的 Lambda 資源定義不正確。
-
如果
output.txt
傳回錯誤,問題可能是您定義 Lambda 函數的方式。檢查您的程式碼,以確保其符合本教學課程。然後再次部署。