AWS CLI apigatewayv2 update-api 实战为 HTTP API 配置 CORS 的完整指南【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli本文基于 aws-cli 仓库中 apigatewayv2 update-api 官方示例 展开完整讲解aws apigatewayv2 update-api命令如何通过--cors-configuration参数为 HTTP API 开启跨域资源共享CORS。读完本文你将掌握该示例命令的完整用法与输出结构、update-api各请求参数的适用范围HTTP API 与 WebSocket API 的差异、底层 API 的 HTTP 行为与错误类型以及如何配合delete-cors-configuration完成 CORS 配置的生命周期管理。示例的定位它如何出现在 CLI 帮助里这条示例并非随意编写的教程片段。在 aws-cli 中人工撰写的 ReST 示例文件存放在examples/服务名/服务名-操作名.rst目录下并由 addexamples.py 这个定制模块在生成文档时注入到对应操作的帮助页面中。从源码结构看add_examples函数会拼接examples/apigatewayv2/update-api.rst这样的路径若文件存在就在aws help apigatewayv2 update-api输出中追加一个 Examples 小节并把文件内容逐行写入。因此你在 CLI 本地帮助中看到的 CORS 配置示例其内容源头就是 update-api.rst。官方示例启用一个 HTTP API 的 CORS示例场景是允许来自https://www.example.com的浏览器请求访问指定的 API。完整命令如下aws apigatewayv2 update-api \ --api-id a1b2c3d4 \ --cors-configuration AllowOriginshttps://www.example.com要点说明--api-id a1b2c3d4目标 API 的标识符是本次更新的唯一必填定位参数--cors-configuration使用了 AWS CLI 的shorthand简写语法AllowOriginshttps://www.example.com会被解析为{allowOrigins: [https://www.example.com]}这一结构体。你也可以改用--cors-configuration file://cors.json传入 JSON 文件该示例只更新了AllowOrigins其余 CORS 字段AllowHeaders、AllowMethods 等保持 API 上已有配置不变。命令成功后返回完整的 API 描述对象示例输出如下与 update-api.rst 中记录完全一致{ ApiEndpoint: https://a1b2c3d4.execute-api.us-west-2.amazonaws.com, ApiId: a1b2c3d4, ApiKeySelectionExpression: $request.header.x-api-key, CorsConfiguration: { AllowCredentials: false, AllowHeaders: [ header1, header2 ], AllowMethods: [ GET, OPTIONS ], AllowOrigins: [ https://www.example.com ] }, CreatedDate: 2020-04-08T18:39:3700:00, Name: my-http-api, ProtocolType: HTTP, RouteSelectionExpression: $request.method $request.path, Tags: {}, Version: v1.0 }从输出字段可以看出该 API 是一个ProtocolType为HTTP的 HTTP APIApiEndpoint给出了默认的execute-api端点RouteSelectionExpression为 HTTP API 固定的$request.method $request.path而CorsConfiguration中AllowOrigins已成功包含https://www.example.com说明跨域来源配置已生效。底层 API 行为从服务模型看 update-apiCLI 命令与 Amazon API Gateway 服务模型一一映射。在 service-2.json 中UpdateApi操作定义为HTTP 方法PATCH请求路径为/v2/apis/{apiId}成功时返回状态码 200请求体UpdateApiRequest结构体其中ApiId位于 URI 路径对应 CLI 的--api-id其余字段放入请求体可能的错误同一位置的服务模型中列出NotFoundException请求中指定的资源不存在例如--api-id拼写错误或属于其他账号/区域TooManyRequestsException客户端请求频率超出限制BadRequestException请求中某个参数不合法例如 shorthand 语法写错或字段取值超出范围ConflictException资源已存在导致的冲突。请求参数详解谁只支持 HTTP API谁只支持 WebSocket APIupdate-api的请求结构体service-2.json 中的 UpdateApiRequest包含以下成员。各字段在服务模型中都带有明确的适用范围说明使用时务必注意 HTTP API 与 WebSocket API 的差异CLI 参数对应字段说明来自服务模型文档--api-idApiIdAPI 标识符位于 URI 路径必填--cors-configurationCorsConfigurationCORS 配置仅支持 HTTP API--nameNameAPI 名称--descriptionDescriptionAPI 描述--versionVersion版本标识符--route-selection-expressionRouteSelectionExpression路由选择表达式HTTP API 固定为${request.method} ${request.path}WebSocket API 必填--api-key-selection-expressionApiKeySelectionExpressionAPI Key 选择表达式仅支持 WebSocket API--disable-schema-validationDisableSchemaValidation创建部署时跳过模型校验仅支持 WebSocket API--disable-execute-api-endpointDisableExecuteApiEndpoint禁用默认的execute-api端点强制客户端走自定义域名--ip-address-typeIpAddressType可调用 API 或域名的 IP 地址类型--credentials-arnCredentialsArnquick create 集成所需的凭证 ARN仅支持 HTTP API--route-keyRouteKeyquick create 创建的路由键提供后替换原值仅支持 HTTP API--targetTargetquick create 的后端目标URL 或 Lambda ARN仅支持 HTTP APIupdate-api是一个“部分更新”语义的 PATCH 操作请求中未提供的字段保持原值不变。因此示例中只传AllowOrigins并不会清空 API 上已存在的AllowHeaders、AllowMethods等其他 CORS 字段——这一点也可从示例输出中AllowHeaders仍保留header1、header2得到印证。CORS 结构体的全部字段--cors-configuration接收的Cors结构体service-2.json 中的 Cors 定义共有 6 个成员全部仅支持 HTTP API字段类型说明AllowOrigins字符串列表允许发起跨域请求的来源Origin集合示例中即设置此字段AllowHeaders字符串列表允许携带的请求头集合AllowMethods字符串列表允许的 HTTP 方法集合如GET、OPTIONSExposeHeaders字符串列表暴露给浏览器 JS 的响应头集合AllowCredentials布尔值是否允许请求携带凭证MaxAge整数-1 到 86400浏览器对预检preflight请求结果的缓存秒数一个更完整的配置示例shorthand 语法可以参考aws apigatewayv2 update-api \ --api-id a1b2c3d4 \ --cors-configuration {AllowOriginshttps://www.example.com,AllowMethodsGET,POST,OPTIONS,AllowHeadersX-Amz-Date,Authorization,MaxAge3600}其中AllowOrigins、AllowMethods、AllowHeaders这类列表字段在 shorthand 中直接以逗号分隔多个值。关闭 CORS配套命令 delete-cors-configurationCORS 配置的生命周期管理还有对应的删除操作。同目录下的 delete-cors-configuration.rst 记录了官方示例aws apigatewayv2 delete-cors-configuration \ --api-id a1b2c3d4该命令删除 API 的整个 CORS 配置从而关闭 CORS且不产生任何输出执行成功即静默返回。也就是说需要调整跨域策略时用update-api --cors-configuration覆盖式更新需要彻底关闭时用delete-cors-configuration。使用前提与注意事项执行这些命令需要已完成 AWS CLI 的安装与凭证配置示例文档中引用的 Getting started 指引即为此目的示例中的引号规则遵循类 Unix shell 规范若在 Windows 等其他终端执行需按当地引号规则调整这一提示同样来自 addexamples.py 注入帮助页面的标准说明--cors-configuration对 WebSocket API 无效服务模型明确标注其“Supported only for HTTP APIs”示例中的a1b2c3d4与https://a1b2c3d4.execute-api.us-west-2.amazonaws.com均为演示值实际使用时替换为你所在区域、账号下的真实 API 标识符与端点。小结update-api.rst 这条示例展示了 aws-cli 中 apigatewayv2 服务最典型的配置操作模式一条update-api命令、一个 shorthand 参数的 CORS 结构体、一段返回完整 API 描述的 JSON 输出。结合 service-2.json 中的服务模型可以进一步确认该命令对应PATCH /v2/apis/{apiId}请求CORS 字段仅适用于 HTTP API且未传字段保持原值不变。理解这三点后你就可以把这条示例迁移到自己的 API 上安全地增改或撤销跨域配置。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考