企业官网建设流程全解析

使用 aws apigateway update-api-key 管理 API Key：从 PATCH 操作到实战示例

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

导读

本文以 awscli/examples/apigateway/update-api-key.rst 中的官方示例为骨架，系统讲解 AWS CLI 中aws apigateway update-api-key命令的完整用法。你将掌握：API Key 的定位方式、--patch-operations参数中op/path/value的编写规则、修改名称与禁用密钥两类核心场景的真实命令与输出，并结合仓库中的服务模型（service-2.json）理解该命令底层的 PATCH 请求语义与可选字段，最终能独立完成 API Key 的日常变更管理。

一、命令概述：update-api-key 能做什么

在 API Gateway 中，API Key 是分发给调用方、用于访问需要鉴权的 Method 的凭证资源。当密钥已创建并投入使用后，其名称、描述、启用状态等属性仍可能随业务调整而变化，例如将开发环境的密钥改名、或在安全事件中紧急禁用某个密钥。update-api-key正是用于"就地变更"已有 API Key 资源的命令。

从本仓库的服务模型文件 awscli/botocore/data/apigateway/2015-07-09/service-2.json 可以看到，UpdateApiKey操作在 REST API 层面映射为：

"http": { "method": "PATCH", "requestUri": "/apikeys/{api_Key}" }

也就是说，CLI 的update-api-key本质上是对/apikeys/{api_Key}资源发起一次HTTP PATCH请求。与put-api-key（整体替换）不同，PATCH 语义是"局部更新"——只修改你显式声明的字段，其余字段保持不变。这一点也解释了为什么该命令的参数中没有一个具体的--name或--enabled开关，而是统一通过--patch-operations来表达"要改什么、改成什么"。

二、参数详解与获取 API Key 标识

2.1 参数结构

update-api-key的核心参数有两个，其定义见 service-2.json 中的 UpdateApiKeyRequest 形状：

2.2 如何拿到 API Key 的标识符

--api-key需要的是 API Key 的Id（形如sNvjQDMReA1eEQPNAW8r37XsU2rDD7fc7m2SiMnu的字符串），而不是密钥值本身。获取 Id 有两种途径：

• 查看某个密钥详情：aws apigateway get-api-key --api-key <id>，返回体中的id字段即当前密钥标识；
• 列出全部密钥：aws apigateway get-api-keys，输出中的items[].id即为各密钥的 Id（参考 get-api-keys.rst 与 get-api-key.rst 中的官方示例）。

ApiKey资源完整的可读字段由 service-2.json 中的 ApiKey 形状 定义，包括：id（标识符）、value（密钥值）、name（名称）、description（描述）、enabled（是否可用）、createdDate（创建时间）、lastUpdatedDate（最近更新时间）、stageKeys（关联的 Stage 列表，格式为restApiId/stageName）、tags（标签集合）、customerId（集成 AWS Marketplace 时的客户标识）。

三、--patch-operations 的语法与规则

3.1 操作结构

--patch-operations接受一个或多个补丁操作对象，每个对象可含四个属性，其定义位于 service-2.json 的 PatchOperation 形状：

op的合法取值由 Op 枚举 定义，共六种：add、remove、replace、move、copy、test。需要特别注意的是，并非所有操作对每个资源都受支持——模型文档明确说明"支持的 op 取决于具体操作上下文，对资源应用不支持的 op 会返回错误信息"。在 API Key 场景下，官方示例使用的就是replace。

3.2 path 的 JSON Pointer 规则

path使用 JSON Pointer 语法定位目标字段。模型文档给出了两个关键规则：

• 若资源有一个可更新属性{"name": "value"}，则其 path 为/name；
• 若属性值是 JSON 对象，path 需要逐级拼接，且path 名称中出现的斜杠/必须转义为~1。例如属性值为{"name": {"child/name": "child-value"}}时，child/name字段的 path 写作/name/child~1name；
• 每个op操作只能关联一个path。

3.3 value 的传参注意事项

value是add或replace操作的新目标值。当用 CLI 更新一个 JSON 对象的属性时，模型文档特别强调：在 Linux shell 中要把 JSON 对象用一对单引号包裹，例如'{"a": ...}'，以避免 shell 对花括号和引号做错误解析。示例中的value='newName'使用单引号包住字符串值，同样是出于 shell 转义安全考虑。

四、实战一：修改 API Key 的名称

官方示例的第一种场景是重命名密钥。命令如下（原样取自 update-api-key.rst）：

aws apigateway update-api-key --api-key sNvjQDMReA1eEQPNAW8r37XsU2rDD7fc7m2SiMnu --patch-operations op='replace',path='/name',value='newName'

这里--patch-operations使用 CLI 的 shorthand 语法，一次传入了三个键值对：op='replace'声明操作为替换、path='/name'定位到名称字段、value='newName'给出新名称。op/path/value之间用逗号分隔，外层无需花括号，这正是 API Gateway 各update-*命令通用的--patch-operations写法。

命令成功后的输出如下：

{ "description": "currentDescription", "enabled": true, "stageKeys": [ "41t2j324r5/dev" ], "lastUpdatedDate": 1470086052, "createdDate": 1445460347, "id": "sNvjQDMReA1vEQPNzW8r3dXsU2rrD7fcjm2SiMnu", "name": "newName" }

对输出做三点解读：

1. name已变为newName，而description、enabled、stageKeys等字段保持原值——这正是 PATCH 局部更新的直观体现，未被path指向的字段不受影响；
2. lastUpdatedDate与createdDate为 Unix 时间戳（秒级），其中createdDate记录创建时刻、lastUpdatedDate记录最近一次变更时刻，两者在重命名前后可对照验证变更是否生效；
3. 返回体中的id与请求参数中的api-key是同一密钥的标识符，用于确认更新作用在正确的资源上。

如果需要同时修改多个字段（例如改名并顺带更新描述），可以在--patch-operations后追加多个操作，用空格分隔即可，例如：

aws apigateway update-api-key --api-key sNvjQDMReA1eEQPNAW8r37XsU2rDD7fc7m2SiMnu --patch-operations op='replace',path='/name',value='newName' op='replace',path='/description',value='Updated description'

五、实战二：禁用 API Key

第二种场景是禁用密钥，这在怀疑密钥泄露、需要临时下线的场景中非常实用。命令如下：

aws apigateway update-api-key --api-key sNvjQDMReA1eEQPNAW8r37XsU2rDD7fc7m2SiMnu --patch-operations op='replace',path='/enabled',value='false'

与重命名相比，唯一的差异在于path指向/enabled、value传布尔值false。对应输出如下：

{ "description": "currentDescription", "enabled": false, "stageKeys": [ "41t2j324r5/dev" ], "lastUpdatedDate": 1470086052, "createdDate": 1445460347, "id": "sNvjQDMReA1vEQPNzW8r3dXsU2rrD7fcjm2SiMnu", "name": "newName" }

enabled字段在 ApiKey 形状 中的文档语义为"指定 API Key 是否可被调用方使用"，从true改为false后，携带该密钥的请求将不再通过鉴权。若后续需要恢复，只需再次执行 replace 操作并把value改回true。注意示例中禁用操作执行前密钥名称已改为newName，说明两次更新操作可以先后作用于同一资源，且每次更新互不冲突。

六、底层原理与错误处理

6.1 从 CLI 参数到 PATCH 请求

--patch-operations属于模型中的列表结构参数（ListOfPatchOperation）。CLI 会将其按 shorthand 规则解析为若干PatchOperation结构体，再序列化进 PATCH 请求体。由于该命令没有普通的位置参数承载"要改的值"，所有变更意图都必须编码在patchOperations中——这也是 API Gateway 所有update-*系列命令（update-rest-api、update-stage、update-usage-plan等）共享的交互模式。

6.2 可能返回的错误

UpdateApiKey 操作的 errors 定义 列出了该命令可能抛出的六类异常，可作为排错依据：

最常见的实操失误是把--api-key误传成密钥值（value）而非 Id，以及path拼写错误（如写成/Name），两者都会触发BadRequestException或NotFoundException。

6.3 快速验证变更

更新完成后，建议用aws apigateway get-api-key --api-key <id>（参考 get-api-key.rst）复查返回体，确认name、enabled、lastUpdatedDate等字段符合预期；需要枚举全部密钥时使用 get-api-keys.rst 中的aws apigateway get-api-keys命令。这三个命令（get / update / get）组合起来即可构成 API Key 变更的完整闭环。

七、小结与扩展阅读

aws apigateway update-api-key通过--patch-operations以 PATCH 语义对 API Key 做字段级更新，核心要点可归纳为三条：

• 定位靠 Id：--api-key传密钥标识符（Id），不传密钥值；
• 变更靠 patch：op/path/value三元组描述每次修改，replace是 API Key 场景最常用的操作，path使用 JSON Pointer（/name、/enabled、/description等）；
• 更新是局部的：未被指向的字段原样保留，lastUpdatedDate可作为变更生效的佐证。

如果想进一步了解 API Key 的创建与查询，可继续阅读同目录下的 create-api-key.rst、get-api-key.rst 与 get-api-keys.rst；关于op/path/value/from的完整字段语义，可直接查阅 service-2.json 中 PatchOperation 形状的定义。由于 API Key 的属性集合随 API Gateway 服务演进而变化，具体可更新的字段以当前服务模型为准。

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