企业官网建设流程全解析

AWS CLI apigatewayv2 update-integration：更新 Lambda 集成指向的完整实操指南

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

本文基于 aws-cli 仓库中 awscli/examples/apigatewayv2/update-integration.rst 官方示例文档展开，围绕aws apigatewayv2 update-integration命令，讲解如何把已存在的 API Gateway V2 集成更新为指向另一个 Lambda 函数。读完后你将掌握：该命令的必选/可选参数、Lambda 集成 URI 的书写格式、返回结果中各字段的含义、底层请求的 HTTP 语义与错误类型，以及示例文档是如何被 CLI 帮助系统动态注入的。

一、场景：把集成切换到新的 Lambda 函数

在 HTTP API / WebSocket API 中，一个「集成（Integration）」定义了 API 的某个路由最终把请求转发到哪个后端。当后端 Lambda 函数被替换、升级或迁移时，通常不需要删除并重建集成，而是一条update-integration命令完成热切换。

原文档给出的示例即是将现有 AWS Lambda 集成更新为使用指定的 Lambda 函数：

aws apigatewayv2 update-integration \ --api-id a1b2c3d4 \ --integration-id a1b2c3 \ --integration-uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-new-function/invocations

命令执行后，API Gateway 返回更新后的集成对象，示例输出如下：

{ "ConnectionType": "INTERNET", "IntegrationId": "a1b2c3", "IntegrationMethod": "POST", "IntegrationType": "AWS_PROXY", "IntegrationUri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-new-function/invocations", "PayloadFormatVersion": "2.0", "TimeoutInMillis": 5000 }

这个输出里有几个值得注意的点：

• IntegrationMethod为POST：Lambda 集成在更新后固定以 POST 方式调用后端；
• PayloadFormatVersion为2.0：请求/响应 payload 使用 v2.0 格式（v2 与 v1 在请求头大小写、认证字段等方面有差异，迁移函数时要确认新函数能兼容该格式）；
• TimeoutInMillis为 5000：当前集成的超时时间为 5 秒，低于 HTTP API 30 秒的默认上限，说明此前有人显式调低过它。update-integration只修改你显式传入的字段，未传入的字段保持原值——所以切换函数不会顺带把超时改回默认值。

二、参数详解：以服务模型为准

CLI 参数并非凭空而来，它们一一对应 awscli/botocore/data/apigatewayv2/2018-11-29/service-2.json 中UpdateIntegrationRequest结构定义的服务模型。结合模型可以确认：

必选参数

常用可选参数

其中--integration-uri是本文示例的主角。对 Lambda 集成，服务模型给出的取值规则是「For a Lambda integration, specify the URI of a Lambda function」。实践中存在两种等价写法：

1. 带/invocations路径的完整调用 URI（本文示例采用）：arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-new-function/invocations
2. 简洁的函数 ARN：arn:aws:lambda:us-west-2:123456789012:function:my-function

同目录的 awscli/examples/apigatewayv2/create-integration.rst 中创建 Lambda 集成时使用的就是简洁 ARN 写法，两种形式 API Gateway 均可识别。注意示例中 URI 包含冒号，在 shell 中务必按引号规则处理（CLI 生成的帮助文本会提醒示例默认采用类 Unix 引号规则，需按终端实际情况调整）。

三、底层机制：一条 PATCH 请求与可能的错误

从 awscli/botocore/data/apigatewayv2/2018-11-29/service-2.json 中UpdateIntegration操作的定义可以直接读出底层语义：

{ "http": { "method": "PATCH", "requestUri": "/v2/apis/{apiId}/integrations/{integrationId}", "responseCode": 200 } }

即：update-integration最终对 API Gateway 发出的是HTTP PATCH请求，--api-id与--integration-id分别填充 URI 中的{apiId}和{integrationId}占位符。该服务采用rest-json协议、API 版本2018-11-29，签名方式为aws.auth#sigv4（SigV4）。这也解释了为什么它是「部分更新」语义：PATCH 只覆盖请求体中出现的字段，与上文「未传入字段保持原值」的行为一致。

同一处模型定义还列出了该操作可能抛出的四类错误：

实操中遇到NotFoundException，通常先执行aws apigatewayv2 get-integrations --api-id <id>核对集成 ID 是否属于该 API；从同仓库 awscli/examples/apigatewayv2/get-integrations.rst 的示例输出可见，列表中每条集成都带有IntegrationId、IntegrationType、IntegrationUri等字段，可直接用于拼写更新命令。

四、示例文档如何进入 CLI 帮助系统

值得一提的是，awscli/examples/apigatewayv2/update-integration.rst 并不只是躺在仓库里的静态文档——它会被aws help apigatewayv2 update-integration动态引用。这一机制实现在 awscli/customizations/addexamples.py：

• 该模块监听doc-examples.*.*文档事件；
• 按事件类名推导路径，在examples/<service_name>/<op_name>.rst下查找对应文件（例如examples/apigatewayv2/update-integration.rst）；
• 若文件存在，就在生成的帮助页末尾插入「Examples」二级标题、一段关于 CLI 需已安装配置及引号规则的使用提示，然后逐行写入示例内容。

所以你在终端执行aws help apigatewayv2 update-integration时看到的示例块，其内容与仓库中这份 RST 文件完全一致。若需了解 CLI 侧参数命名细节，可参考 awscli/customizations/argrename.py，其中对 apigatewayv2 做了version到api-version的参数重命名（针对create-api/update-api），体现了 CLI 对保留关键字的处理方式。

另外，V1 版 REST API 也有同名的 update-integration 命令，其示例见 awscli/examples/apigateway/update-integration.rst；V1（apigateway）与 V2（apigatewayv2，HTTP/WebSocket API）的集成参数模型不同，混用命令时注意区分。

五、完整工作流速查

结合上述内容，一个「切换后端函数」的完整操作流程如下（前提：AWS CLI 已安装并完成凭证配置，且具备 API Gateway 相应写权限）：

# 1. 找到目标集成 aws apigatewayv2 get-integrations \ --api-id a1b2c3d4 \ --query 'Items[*].{Id:IntegrationId,Type:IntegrationType,Uri:IntegrationUri}' \ --output table # 2. 更新集成的 Lambda 指向 aws apigatewayv2 update-integration \ --api-id a1b2c3d4 \ --integration-id a1b2c3 \ --integration-uri "arn:aws:lambda:us-west-2:123456789012:function:my-new-function" # 3. 校验更新结果 aws apigatewayv2 get-integration \ --api-id a1b2c3d4 \ --integration-id a1b2c3

注意事项：

• 若该集成是 API Gateway 托管集成（快速创建产生，返回中带ApiGatewayManaged: true），可以更新但不可删除；
• 更新集成只作用于 API 定义层，客户端生效通常还需部署（deployment）；
• Lambda 函数需具备允许 API Gateway 调用的权限配置，否则更新命令本身成功、调用时才会报后端错误。

参考路径

• 示例文档（本文核心）：awscli/examples/apigatewayv2/update-integration.rst
• 服务模型（参数/HTTP 语义/错误定义）：awscli/botocore/data/apigatewayv2/2018-11-29/service-2.json
• 帮助系统示例注入机制：awscli/customizations/addexamples.py
• 相关示例：create-integration.rst、get-integrations.rst、delete-integration.rst、V1 版 update-integration.rst

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli