Creates an API Gateway stage w…

# AWS API Gateway v2部署配置指南

一、前置条件确认

• 已有 myapp-prod REST API 及其 IAM 角色（API Gateway日志写入CloudWatch需该角色，ARN格式形如 arn:aws:iam::<account-id>:role/service-role/<role-name>，可在控制台 Settings 中查看）
• X-Ray 需给该 IAM 角色附加 AWSXRayDaemonWriteAccess 托管策略
• CloudWatch 需附加 AmazonAPIGatewayPushToCloudWatchLogs 托管策略（账号级别设置一次即可）

二、创建 Deployment 并挂载新阶段

推荐用 AWS CLI（控制台操作同理）：

```bash

# 1. 创建部署

aws apigateway create-deployment \

--rest-api-id <your-api-id> \

--stage-name v2 \

--region us-east-1

```

三、配置阶段级 CloudWatch 日志（ERROR级别）

```bash

aws apigateway update-stage \

--rest-api-id <your-api-id> \

--stage-name v2 \

--region us-east-1 \

--patch-operations \

op=replace,path=/*/*/logging/loglevel,value=ERROR \

op=replace,path=/*/*/logging/dataTrace,value=false \

op=replace,path=/*/*/metrics/enabled,value=true

```

说明：

• loglevel=ERROR：仅记录 ERROR 级别及以上的日志，不记录 access/debug 全量信息
• 如需访问日志，可额外设置 accessLogSettings（destinationArn 指向 CloudWatch Logs 组）

四、开启 X-Ray 追踪并设置采样率 0.2

```bash

aws apigateway update-stage \

--rest-api-id <your-api-id> \

--stage-name v2 \

--region us-east-1 \

--patch-operations \

op=replace,path=tracing/enabled,value=true

```

采样率说明：

• X-Ray 采样率通过采样规则控制，默认规则不可编辑采样率
• 需在 X-Ray 控制台（或 CLI put-sampling-rule）创建一条自定义采样规则：规则名自定义，Service 名匹配你的 API，FixedRate 设为 0.2，优先级设为高于默认规则（如 1）

五、验证

• 控制台进入 Stages → v2，确认 Logs/Tracing 标签下配置生效
• 发送一个会报错的请求，在 CloudWatch Logs 中确认有 ERROR 日志产生
• X-Ray 控制台查看服务地图中是否出现该 API 节点及约 20% 的采样段

六、注意事项

• ERROR 级别下常规请求日志不会写入，排障时可临时调为 INFO
• 阶段名 v2 与已有阶段独立，不影响现有流量
• CloudWatch 日志保留期默认永不过期，建议设置保留策略以控制成本