AWS CLI 实战：用 `apigateway delete-domain-name` 删除 API Gateway 自定义域名

AWS CLI 实战：用apigateway delete-domain-name删除 API Gateway 自定义域名

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

本文以 aws-cli 仓库中 delete-domain-name.rst 示例文档为主线，完整讲解aws apigateway delete-domain-name命令的参数用法、底层 API 定义、错误处理与完整的自定义域名生命周期实践。读完本文，你将掌握如何在 API Gateway 中安全、准确地删除不再使用的自定义域名，并能结合get-domain-names、get-domain-name等配套命令完成删除前的确认与故障排查。

命令速览：一条命令删除自定义域名

在 AWS API Gateway 中，自定义域名（DomainName）是为 REST API、HTTP API 或 WebSocket API 绑定的自有域名（例如api.domain.tld），它替代默认的execute-api端点对外提供服务。当域名不再需要时，可以使用delete-domain-name命令将其从 API Gateway 中移除。

仓库中的 delete-domain-name.rst 给出了最简用法：

aws apigateway delete-domain-name --domain-name 'api.domain.tld'

命令执行成功时不返回任何输出。这是因为该操作在 API Gateway 侧对应一个异步删除流程（HTTP 响应码为 202 Accepted，详见下文"底层 API 定义"一节），API Gateway 收到请求后即开始执行删除，命令本身无需等待删除最终完成即可正常退出。

参数详解：--domain-name与--domain-name-id

从 API 服务模型中定义的DeleteDomainNameRequest结构（见 service-2.json）可以看出，该命令支持两个参数：

其中--domain-name直接嵌入请求的 URI 路径中，是该操作的唯一必填参数，需要与创建时使用的域名完全一致。--domain-name-id是私有自定义域名的专属参数——由于私有域名存在同名多实例的可能（通过domainNameId区分资源），当同一域名存在多个资源标识时，需要显式指定要删除的那个标识符。公有（EDGE/REGIONAL）自定义域名不需要该参数。

从请求结构还可以看出，domainName对应 URI 位置参数（location: "uri"），domainNameId对应查询字符串参数（location: "querystring"），二者在底层由 botocore 序列化到不同的请求位置，这也是为什么 CLI 上看起来只是两个普通 flag，实际发送的 HTTP 请求路径却是/domainnames/api.domain.tld?domainNameId=...这样的形态。

底层 API 定义：DELETE /domainnames/{domain_name}

delete-domain-name命令在 botocore 服务模型中的对应操作定义位于 service-2.json：

• 操作名称：DeleteDomainName
• HTTP 方法：DELETE
• 请求 URI：/domainnames/{domain_name}
• 响应码：202（Accepted，异步操作）
• 可返回错误：BadRequestException、ConflictException、NotFoundException、UnauthorizedException、TooManyRequestsException
• 操作说明：Deletes the DomainName resource

其中响应码 202 表明这是一个异步操作：API Gateway 接受删除请求后即返回，实际的资源清理在服务端异步完成。这也是该命令"无输出、立即返回"现象的根本原因。

删除前的确认与排查：搭配查询类命令使用

删除是不可逆操作，在生产环境执行前应先用查询类命令确认目标域名与当前状态。仓库中的示例文档提供了两种确认手段：

列出账号下所有自定义域名

使用 get-domain-names 命令查看当前账号下的全部自定义域名，确认要删除的域名确实存在且拼写无误：

aws apigateway get-domain-names

输出示例：

{ "items": [ { "domainName": "api.domain.tld", "distributionDomainName": "d1a2f3a4c5o6d.cloudfront.net", "certificateName": "uploadedCertificate", "certificateUploadDate": 1462565487 } ] }

对于私有自定义域名场景，还可以通过--resource-owner SELF过滤出本账号拥有的域名，或结合--resource-owner OTHER_ACCOUNTS查看其他账号的域名。

查看单个域名的详细状态

使用 get-domain-name 命令获取单个域名的完整状态（如私有域名需附带--domain-name-id）：

aws apigateway get-domain-name \ --domain-name api.domain.tld

输出中domainNameStatus字段的取值决定了该域名当前是否可安全删除。根据服务模型中的DomainNameStatus枚举（见 service-2.json），其取值包括：

从模型文档可知，当状态为UPDATING时域名不能被进一步修改，直到现有操作完成；只有当状态为AVAILABLE时才可安全执行删除。

异常与错误处理

DeleteDomainName操作在 service-2.json 中声明了 5 种可能的错误响应，这些错误会以对应的 AWS 异常形式反映到 CLI 输出中：

其中最常遇到的是NotFoundException：当--domain-name指定的域名不存在、或拼写与创建时不一致（例如漏掉点号或大小写不同）时，CLI 会报出资源不存在的错误。此时应回到get-domain-names输出中核对域名的准确写法。

另外，删除操作需要apigateway:DELETE对应资源的 IAM 权限（在 API Gateway 侧体现为对arn:aws:apigateway:*::/domainnames/{domain_name}资源的删除权限），权限不足时会触发UnauthorizedException，这可以从源码结构推断：该操作在服务端是受 IAM 鉴权的管理面操作，与 create-domain-name.rst 等管理操作属于同一权限体系。

完整生命周期实践：创建 → 查询 → 删除

自定义域名的典型运维闭环是"创建 → 查询确认 → 删除回收"，三个环节在仓库示例文档中均有对应的命令示例：

第一步：创建自定义域名（参考 create-domain-name.rst）：

aws apigateway create-domain-name \ --domain-name 'my.domain.tld' \ --certificate-name 'my.domain.tld cert' \ --certificate-arn 'arn:aws:acm:us-east-1:012345678910:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3'

创建成功后返回的distributionDomainName（如abcd1234.cloudfront.net）即为需要配置 DNS CNAME 记录的目标；私有域名场景则需携带--endpoint-configuration '{"types": ["PRIVATE"]}'及访问策略。

第二步：查询确认（参考 get-domain-names.rst）：

aws apigateway get-domain-names

第三步：删除回收（本文主题，参考 delete-domain-name.rst）：

aws apigateway delete-domain-name --domain-name 'api.domain.tld'

删除后域名不再被 API Gateway 托管，但需要注意的是：删除命令本身只作用于 API Gateway 的 DomainName 资源——从DeleteDomainNameRequest的参数结构看，该操作只接收域名名称与标识符，不涉及 DNS 记录和证书资源的清理。可以推断，你还需要在 DNS 服务商侧手动移除指向distributionDomainName（或regionalDomainName）的 CNAME/别名记录，并按需在 AWS Certificate Manager（ACM）中处理证书的吊销或复用，这些步骤不在delete-domain-name命令的能力范围内。

小结

aws apigateway delete-domain-name是 API Gateway 自定义域名回收的标准手段，其本质是对DELETE /domainnames/{domain_name}的异步调用。实战中的关键要点可以归纳为：

1. 必填参数是--domain-name；仅私有自定义域名需要额外的--domain-name-id；
2. 命令无成功输出，响应码 202 表示异步删除；
3. 删除前用get-domain-names/get-domain-name确认域名拼写与domainNameStatus状态（建议AVAILABLE时再操作）；
4. 常见错误为NotFoundException（域名不存在或拼写错误）、UnauthorizedException（权限不足）等 5 类异常；
5. 删除仅作用于 API Gateway 资源，DNS 记录与证书需另行处理。

相关命令的完整示例均可直接在仓库的 apigateway 示例目录 中查阅，API 模型的权威定义见 service-2.json。

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