AWS CLIapigatewayv2 create-route命令完全指南为 HTTP API 与 WebSocket API 创建路由【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli本指南围绕 aws-cli 官方示例文档 create-route.rst 展开系统讲解aws apigatewayv2 create-route命令的两种典型用法创建$default兜底路由、创建 HTTP API 业务路由并结合本仓库中 API Gateway v2 的服务模型定义service-2.json深入剖析全部请求参数、RouteKey 语法规则、响应字段与常见错误。读完本文你将能够熟练使用该命令为 API Gateway v2 的 HTTP API 和 WebSocket API 定义任意路由并能结合update-route、get-routes完成路由的后续管理与验证。一、命令概览Route 在 API Gateway v2 中的作用在 Amazon API Gateway v2即 HTTP API 与 WebSocket API中Route路由决定了客户端请求到达 API 后如何被分发与处理。每一条路由都拥有一个RouteKeyAPI Gateway 会先对请求执行选择表达式selection expression再将表达式的结果与各路由的 RouteKey 做匹配命中后把请求转发到与该路由绑定的集成Integration例如 Lambda 函数或 HTTP 端点。create-route命令就是用来在指定 API--api-id下创建一条新路由的核心命令。本仓库的示例文档 create-route.rst 给出了两个最具代表性的使用场景创建$default兜底路由以及创建带 HTTP 方法前缀的业务路由。从服务模型看该操作的底层 HTTP 请求定义为POST /v2/apis/{apiId}/routes成功时返回 HTTP 201见 service-2.json即资源已创建。命令行层面的必填参数只有两个--api-idAPI 标识符作为 URL 路径参数与--route-key路由键其余均为可选参数。二、示例一创建$default兜底路由WebSocket 或 HTTP API 通用原文档的第一个示例演示了如何创建$default路由。$default是 API Gateway v2 内置的特殊 RouteKey作为兜底路由当请求无法匹配 API 中任何其他路由时请求会被发送到$default路由。WebSocket API 和 HTTP API 都支持这一机制。aws apigatewayv2 create-route \ --api-id aabbccddee \ --route-key $default命令返回如下输出{ ApiKeyRequired: false, AuthorizationType: NONE, RouteKey: $default, RouteId: 1122334 }对输出字段的理解RouteIdAPI Gateway 为这条路由自动生成的唯一标识符后续执行update-route、delete-route、create-route-response等操作时都会用到它RouteKey回显你创建的路由键$defaultAuthorizationType默认值为NONE表示该路由开放访问未配置鉴权ApiKeyRequired默认值为false表示该路由不强制要求 API Key。需要特别说明的是$default的两点特性当使用create-api的 quick create快速创建方式创建 API 时API Gateway 会自动生成一条$default路由且该路由由 API Gateway 托管ApiGatewayManaged为true无法修改其 RouteKey。这一行为在服务模型中有所说明见 service-2.json。因此如果你的 API 是 quick create 生成的再次调用create-route创建$default会收到ConflictException资源已存在。$default路由与$request.body.action、$request.method $request.path这类**选择表达式selection expression**配合工作。以 WebSocket API 为例API 在创建时可指定--route-selection-expression $request.body.action参见 create-api.rst即从消息体的action字段取值去匹配 RouteKey若匹配不到任何路由流量便落入$default。三、示例二为 HTTP API 创建带方法与路径的业务路由原文档的第二个示例演示了 HTTP API 下最常见的业务路由创建方式——RouteKey 采用HTTP方法 空格 路径的格式aws apigatewayv2 create-route \ --api-id aabbccddee \ --route-key POST /signup命令返回如下输出{ ApiKeyRequired: false, AuthorizationType: NONE, RouteKey: POST /signup, RouteId: 1122334 }这条命令的含义是创建一个仅接收POST请求、路径为/signup的路由。HTTP API 默认的选择表达式为$request.method $request.path即方法 空格 路径因此 RouteKey 必须与此格式对齐才能被正确匹配。创建路由时并不强制要求立刻绑定集成。你可以先创建路由之后通过update-route --target integrations/integration-id将路由关联到某个集成上。仓库示例 update-route.rst 中的第一条示例正是演示了这一点aws apigatewayv2 update-route \ --api-id a1b2c3d4 \ --route-id a1b2c3 \ --target integrations/a1b2c6输出中可以看到RouteKey: ANY /pets与Target: integrations/a1b2c6说明ANY也是合法的 HTTP 方法前缀表示匹配任意 HTTP 方法。对于 WebSocket APIRouteKey 的格式则不同通常为$request.body.字段名所对应的键值例如aws apigatewayv2 create-route \ --api-id aabbccddee \ --route-key join结合 WebSocket API 的选择表达式$request.body.action客户端发送形如{action: join, ...}的消息时action字段的值join就会与这条路由的 RouteKey 匹配。四、CreateRoute 全部请求参数详解原文档示例只展示了--api-id与--route-key两个参数。实际上根据本仓库服务模型 service-2.json 中CreateRouteRequest的定义该命令还支持以下参数。理解这些参数能让你写出真正生产可用的create-route命令CLI 参数类型必填说明与取值--api-idstring是API 标识符作为 URL 路径参数location: uri可通过get-apis获取--route-keystring是路由键用于与选择表达式的结果匹配。HTTP API 形如POST /signupWebSocket API 可为$default或自定义键值--api-key-requiredboolean否是否要求 API Key仅 WebSocket API 支持--authorization-typestring否鉴权类型。WebSocket API 取值为NONE开放、AWS_IAM、CUSTOMLambda 授权器HTTP API 额外支持JWT。枚举定义见 service-2.json--authorization-scopeslist否授权作用域列表与 JWT 授权器配合使用。请求中的 access token 声明的 scope 只要与任一 route scope 匹配即授权通过--authorizer-idstring否关联的授权器标识符通过create-authorizer创建时生成--model-selection-expressionstring否模型选择表达式仅 WebSocket API 支持--operation-namestring否路由的操作名称长度为 164 字符--request-modelsmap否请求模型映射键为 content type值为模型名仅 WebSocket API 支持--request-parametersmap否请求参数映射仅 WebSocket API 支持--route-response-selection-expressionstring否路由响应选择表达式仅 WebSocket API 支持--targetstring否路由目标格式为integrations/integration-id长度 1128 字符几个值得注意的实现细节RouteKey的类型是SelectionKey服务模型中的注释明确指出选择表达式求值后的结果会与一个或多个选择键进行比较以找到匹配项见 service-2.json。这正是 RouteKey 语义的底层来源。AuthorizationType的枚举顺序为NONE、AWS_IAM、CUSTOM、JWT见 service-2.json。其中JWT仅对 HTTP API 合法向 WebSocket API 传JWT会得到BadRequestException。AuthorizationScopes是字符串列表每个 scope 长度为 164 字符。仓库示例 update-route.rst 中演示了为路由附加user.id、user.email两个 scope 的完整用法可对照参考。RequestModels与RequestParameters均为映射类型map前者键为 content type、值为模型名1128 字符后者值为ParameterConstraints见 service-2.json它们共同构成 WebSocket API 的请求校验能力。五、一个完整的实战组合创建带 JWT 鉴权的业务路由将以上参数组合起来可以一次调用完成路由创建 鉴权配置。例如为 HTTP API 创建一条受 JWT 授权的GET /pets路由假设授权器 ID 为a1b2c5aws apigatewayv2 create-route \ --api-id a1b2c3d4 \ --route-key GET /pets \ --authorization-type JWT \ --authorizer-id a1b2c5 \ --authorization-scopes user.id user.email \ --target integrations/a1b2c6 \ --operation-name getPets该命令一次完成了四件事定义路由键、绑定 JWT 授权器、声明授权作用域、关联集成目标。参考 update-route.rst 中第二条示例的输出可以预见本次调用将返回包含AuthorizationType: JWT、AuthorizationScopes: [user.id, user.email]、Target: integrations/a1b2c6等字段的完整 JSON。若你的 API 使用 quick create 创建$default路由与$default阶段已由 API Gateway 自动托管此时应跳过$default路由的创建直接创建业务路由即可。六、验证与管理get-routes、update-route、delete-route创建路由后可以通过get-routes验证结果aws apigatewayv2 get-routes \ --api-id a1b2c3d4输出中会列出该 API 的全部路由见 get-routes.rst注意其中的两个典型形态普通业务路由如ANY /admin带Target与ApiGatewayManaged: true的$default路由。若你的 API 是 quick create 生成的$default会以ApiGatewayManaged: true出现在列表中。后续管理操作对应关系修改路由属性换集成、加授权器→aws apigatewayv2 update-route --api-id api-id --route-id route-id ...为 WebSocket 路由定义响应模板 →aws apigatewayv2 create-route-response --api-id api-id --route-id route-id ...删除路由 →aws apigatewayv2 delete-route --api-id api-id --route-id route-id其中update-route与create-route的请求参数基本一致服务模型中两者的参数形状复用同一套结构定义因此本文第四节中的参数说明同样适用于update-route。七、错误处理与注意事项根据服务模型 service-2.jsoncreate-route可能抛出以下异常异常触发场景NotFoundException--api-id指向的 API 不存在ConflictException同名的 RouteKey 已存在例如在 quick create 的 API 上重复创建$defaultBadRequestException参数不合法如 RouteKey 格式错误、对 WebSocket API 传入JWT鉴权类型TooManyRequestsException请求频率超出 API 的限流阈值实操中还需注意RouteKey 大小写与格式敏感HTTP API 的 RouteKey 必须形如METHOD /path方法与路径之间有且仅有一个空格如POST /signupWebSocket API 的 RouteKey 由创建 API 时指定的选择表达式决定如$request.body.action对应消息体action字段的值并遵循$default兜底规则。单引号保护$符号示例中--route-key $default使用了单引号这是为了防止 Shell 将$default当作变量展开。在 bash 等 Shell 中务必保留单引号。创建路由与绑定集成是两个步骤create-route时--target为可选参数若路由创建时未指定需在路由与集成均就绪后通过update-route --target integrations/id完成关联否则路由会因缺少目标而无法正常转发请求。API Key 与鉴权差异--api-key-required仅对 WebSocket API 生效HTTP API 的访问控制主要通过--authorization-typeJWT/AWS_IAM/CUSTOM实现。八、小结aws apigatewayv2 create-route是 API Gateway v2 中频率最高、最基础的路由管理命令之一。通过 create-route.rst 中的两个官方示例你可以快速掌握$default兜底路由与METHOD /path业务路由的创建方式结合本仓库 service-2.json 中CreateRouteRequest的完整参数定义你还能进一步解锁 JWT 鉴权、授权作用域、集成绑定等生产级能力并借助get-routes、update-route完成路由的全生命周期管理。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AWS CLI `apigatewayv2 create-route` 命令完全指南：为 HTTP API 与 WebSocket API 创建路由
AWS CLIapigatewayv2 create-route命令完全指南为 HTTP API 与 WebSocket API 创建路由【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli本指南围绕 aws-cli 官方示例文档 create-route.rst 展开系统讲解aws apigatewayv2 create-route命令的两种典型用法创建$default兜底路由、创建 HTTP API 业务路由并结合本仓库中 API Gateway v2 的服务模型定义service-2.json深入剖析全部请求参数、RouteKey 语法规则、响应字段与常见错误。读完本文你将能够熟练使用该命令为 API Gateway v2 的 HTTP API 和 WebSocket API 定义任意路由并能结合update-route、get-routes完成路由的后续管理与验证。一、命令概览Route 在 API Gateway v2 中的作用在 Amazon API Gateway v2即 HTTP API 与 WebSocket API中Route路由决定了客户端请求到达 API 后如何被分发与处理。每一条路由都拥有一个RouteKeyAPI Gateway 会先对请求执行选择表达式selection expression再将表达式的结果与各路由的 RouteKey 做匹配命中后把请求转发到与该路由绑定的集成Integration例如 Lambda 函数或 HTTP 端点。create-route命令就是用来在指定 API--api-id下创建一条新路由的核心命令。本仓库的示例文档 create-route.rst 给出了两个最具代表性的使用场景创建$default兜底路由以及创建带 HTTP 方法前缀的业务路由。从服务模型看该操作的底层 HTTP 请求定义为POST /v2/apis/{apiId}/routes成功时返回 HTTP 201见 service-2.json即资源已创建。命令行层面的必填参数只有两个--api-idAPI 标识符作为 URL 路径参数与--route-key路由键其余均为可选参数。二、示例一创建$default兜底路由WebSocket 或 HTTP API 通用原文档的第一个示例演示了如何创建$default路由。$default是 API Gateway v2 内置的特殊 RouteKey作为兜底路由当请求无法匹配 API 中任何其他路由时请求会被发送到$default路由。WebSocket API 和 HTTP API 都支持这一机制。aws apigatewayv2 create-route \ --api-id aabbccddee \ --route-key $default命令返回如下输出{ ApiKeyRequired: false, AuthorizationType: NONE, RouteKey: $default, RouteId: 1122334 }对输出字段的理解RouteIdAPI Gateway 为这条路由自动生成的唯一标识符后续执行update-route、delete-route、create-route-response等操作时都会用到它RouteKey回显你创建的路由键$defaultAuthorizationType默认值为NONE表示该路由开放访问未配置鉴权ApiKeyRequired默认值为false表示该路由不强制要求 API Key。需要特别说明的是$default的两点特性当使用create-api的 quick create快速创建方式创建 API 时API Gateway 会自动生成一条$default路由且该路由由 API Gateway 托管ApiGatewayManaged为true无法修改其 RouteKey。这一行为在服务模型中有所说明见 service-2.json。因此如果你的 API 是 quick create 生成的再次调用create-route创建$default会收到ConflictException资源已存在。$default路由与$request.body.action、$request.method $request.path这类**选择表达式selection expression**配合工作。以 WebSocket API 为例API 在创建时可指定--route-selection-expression $request.body.action参见 create-api.rst即从消息体的action字段取值去匹配 RouteKey若匹配不到任何路由流量便落入$default。三、示例二为 HTTP API 创建带方法与路径的业务路由原文档的第二个示例演示了 HTTP API 下最常见的业务路由创建方式——RouteKey 采用HTTP方法 空格 路径的格式aws apigatewayv2 create-route \ --api-id aabbccddee \ --route-key POST /signup命令返回如下输出{ ApiKeyRequired: false, AuthorizationType: NONE, RouteKey: POST /signup, RouteId: 1122334 }这条命令的含义是创建一个仅接收POST请求、路径为/signup的路由。HTTP API 默认的选择表达式为$request.method $request.path即方法 空格 路径因此 RouteKey 必须与此格式对齐才能被正确匹配。创建路由时并不强制要求立刻绑定集成。你可以先创建路由之后通过update-route --target integrations/integration-id将路由关联到某个集成上。仓库示例 update-route.rst 中的第一条示例正是演示了这一点aws apigatewayv2 update-route \ --api-id a1b2c3d4 \ --route-id a1b2c3 \ --target integrations/a1b2c6输出中可以看到RouteKey: ANY /pets与Target: integrations/a1b2c6说明ANY也是合法的 HTTP 方法前缀表示匹配任意 HTTP 方法。对于 WebSocket APIRouteKey 的格式则不同通常为$request.body.字段名所对应的键值例如aws apigatewayv2 create-route \ --api-id aabbccddee \ --route-key join结合 WebSocket API 的选择表达式$request.body.action客户端发送形如{action: join, ...}的消息时action字段的值join就会与这条路由的 RouteKey 匹配。四、CreateRoute 全部请求参数详解原文档示例只展示了--api-id与--route-key两个参数。实际上根据本仓库服务模型 service-2.json 中CreateRouteRequest的定义该命令还支持以下参数。理解这些参数能让你写出真正生产可用的create-route命令CLI 参数类型必填说明与取值--api-idstring是API 标识符作为 URL 路径参数location: uri可通过get-apis获取--route-keystring是路由键用于与选择表达式的结果匹配。HTTP API 形如POST /signupWebSocket API 可为$default或自定义键值--api-key-requiredboolean否是否要求 API Key仅 WebSocket API 支持--authorization-typestring否鉴权类型。WebSocket API 取值为NONE开放、AWS_IAM、CUSTOMLambda 授权器HTTP API 额外支持JWT。枚举定义见 service-2.json--authorization-scopeslist否授权作用域列表与 JWT 授权器配合使用。请求中的 access token 声明的 scope 只要与任一 route scope 匹配即授权通过--authorizer-idstring否关联的授权器标识符通过create-authorizer创建时生成--model-selection-expressionstring否模型选择表达式仅 WebSocket API 支持--operation-namestring否路由的操作名称长度为 164 字符--request-modelsmap否请求模型映射键为 content type值为模型名仅 WebSocket API 支持--request-parametersmap否请求参数映射仅 WebSocket API 支持--route-response-selection-expressionstring否路由响应选择表达式仅 WebSocket API 支持--targetstring否路由目标格式为integrations/integration-id长度 1128 字符几个值得注意的实现细节RouteKey的类型是SelectionKey服务模型中的注释明确指出选择表达式求值后的结果会与一个或多个选择键进行比较以找到匹配项见 service-2.json。这正是 RouteKey 语义的底层来源。AuthorizationType的枚举顺序为NONE、AWS_IAM、CUSTOM、JWT见 service-2.json。其中JWT仅对 HTTP API 合法向 WebSocket API 传JWT会得到BadRequestException。AuthorizationScopes是字符串列表每个 scope 长度为 164 字符。仓库示例 update-route.rst 中演示了为路由附加user.id、user.email两个 scope 的完整用法可对照参考。RequestModels与RequestParameters均为映射类型map前者键为 content type、值为模型名1128 字符后者值为ParameterConstraints见 service-2.json它们共同构成 WebSocket API 的请求校验能力。五、一个完整的实战组合创建带 JWT 鉴权的业务路由将以上参数组合起来可以一次调用完成路由创建 鉴权配置。例如为 HTTP API 创建一条受 JWT 授权的GET /pets路由假设授权器 ID 为a1b2c5aws apigatewayv2 create-route \ --api-id a1b2c3d4 \ --route-key GET /pets \ --authorization-type JWT \ --authorizer-id a1b2c5 \ --authorization-scopes user.id user.email \ --target integrations/a1b2c6 \ --operation-name getPets该命令一次完成了四件事定义路由键、绑定 JWT 授权器、声明授权作用域、关联集成目标。参考 update-route.rst 中第二条示例的输出可以预见本次调用将返回包含AuthorizationType: JWT、AuthorizationScopes: [user.id, user.email]、Target: integrations/a1b2c6等字段的完整 JSON。若你的 API 使用 quick create 创建$default路由与$default阶段已由 API Gateway 自动托管此时应跳过$default路由的创建直接创建业务路由即可。六、验证与管理get-routes、update-route、delete-route创建路由后可以通过get-routes验证结果aws apigatewayv2 get-routes \ --api-id a1b2c3d4输出中会列出该 API 的全部路由见 get-routes.rst注意其中的两个典型形态普通业务路由如ANY /admin带Target与ApiGatewayManaged: true的$default路由。若你的 API 是 quick create 生成的$default会以ApiGatewayManaged: true出现在列表中。后续管理操作对应关系修改路由属性换集成、加授权器→aws apigatewayv2 update-route --api-id api-id --route-id route-id ...为 WebSocket 路由定义响应模板 →aws apigatewayv2 create-route-response --api-id api-id --route-id route-id ...删除路由 →aws apigatewayv2 delete-route --api-id api-id --route-id route-id其中update-route与create-route的请求参数基本一致服务模型中两者的参数形状复用同一套结构定义因此本文第四节中的参数说明同样适用于update-route。七、错误处理与注意事项根据服务模型 service-2.jsoncreate-route可能抛出以下异常异常触发场景NotFoundException--api-id指向的 API 不存在ConflictException同名的 RouteKey 已存在例如在 quick create 的 API 上重复创建$defaultBadRequestException参数不合法如 RouteKey 格式错误、对 WebSocket API 传入JWT鉴权类型TooManyRequestsException请求频率超出 API 的限流阈值实操中还需注意RouteKey 大小写与格式敏感HTTP API 的 RouteKey 必须形如METHOD /path方法与路径之间有且仅有一个空格如POST /signupWebSocket API 的 RouteKey 由创建 API 时指定的选择表达式决定如$request.body.action对应消息体action字段的值并遵循$default兜底规则。单引号保护$符号示例中--route-key $default使用了单引号这是为了防止 Shell 将$default当作变量展开。在 bash 等 Shell 中务必保留单引号。创建路由与绑定集成是两个步骤create-route时--target为可选参数若路由创建时未指定需在路由与集成均就绪后通过update-route --target integrations/id完成关联否则路由会因缺少目标而无法正常转发请求。API Key 与鉴权差异--api-key-required仅对 WebSocket API 生效HTTP API 的访问控制主要通过--authorization-typeJWT/AWS_IAM/CUSTOM实现。八、小结aws apigatewayv2 create-route是 API Gateway v2 中频率最高、最基础的路由管理命令之一。通过 create-route.rst 中的两个官方示例你可以快速掌握$default兜底路由与METHOD /path业务路由的创建方式结合本仓库 service-2.json 中CreateRouteRequest的完整参数定义你还能进一步解锁 JWT 鉴权、授权作用域、集成绑定等生产级能力并借助get-routes、update-route完成路由的全生命周期管理。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考