aws-cli 使用指南：为私有 API 网关自定义域名创建 VPC 端点访问关联（create-domain-name-access-association）

aws-cli 使用指南为私有 API 网关自定义域名创建 VPC 端点访问关联create-domain-name-access-association【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读本文围绕 AWS CLI 中apigateway create-domain-name-access-association命令展开讲解如何为 API Gateway 的私有自定义域名private custom domain name创建域名访问关联Domain Name Access Association使指定的 VPC 端点VPC Endpoint在完全隔离于公网的情况下调用该私有 API。读完本文你将掌握该命令的完整参数语义、调用示例、返回字段含义以及关联的查询与删除操作并了解其在仓库中对应的 API 模型定义与底层 REST 调用关系。命令概述什么是 Domain Name Access Associationcreate-domain-name-access-association用于在访问关联源access association source与私有自定义域名private custom domain name之间创建一条域名访问关联资源。从仓库中的 API 模型定义看该操作的官方说明为Creates a domain name access association resource between an access association source and a private custom domain name.其模型定义位于 service-2.jsonHTTP 方法POST请求 URI/domainnameaccessassociations成功响应码201可能抛出的异常BadRequestException、ConflictException、LimitExceededException、UnauthorizedException、TooManyRequestsException对应的响应结构DomainNameAccessAssociation的官方说明service-2.json明确指出借助域名访问关联访问关联源可以在与公网隔离的前提下调用私有自定义域名。换句话说私有 API 的流量不再要求客户端必须与域名处于同一 VPC 网络路径下的固定配置而是可以显式授权某个 VPC 端点作为合法访问来源。参数详解根据请求模型CreateDomainNameAccessAssociationRequestservice-2.json该命令包含 4 个参数其中前 3 个为必填项。参数是否必填类型说明--domain-name-arn是String目标私有自定义域名的 ARN--access-association-source-type是String枚举访问关联源的类型当前仅支持VPCE--access-association-source是String访问关联源的标识符对于 VPCE值为 VPC 端点 ID--tags否Map资源的键值对标签用于成本分配与管理access-association-source-type 的取值范围AccessAssociationSourceType形状定义于 service-2.json其枚举值当前仅有VPCE即目前访问关联源仅支持VPC 端点这一种类型。--access-association-source参数接收的是 VPC 端点的 ID形如vpce-abcd1234efg。关于 ARN 的格式说明--domain-name-arn使用的是 API Gateway 私有自定义域名的 ARN格式为arn:aws:apigateway:region:account-id:/domainnames/domain-namehash例如示例中的arn:aws:apigateway:us-west-2:111122223333:/domainnames/my.private.domain.tldabcd1234。其中abcd1234部分是域名哈希后缀用于区分同名域名。命令执行成功后API 会为新建的关联资源生成一个专属 ARNdomainNameAccessAssociationArn格式形如arn:aws:apigateway:region:account-id:/domainnameaccessassociations/domainname/domain-name/vpcesource/vpce-id命令示例与输出解析创建关联以下命令在us-west-2区域的私有自定义域名my.private.domain.tldabcd1234与 VPC 端点vpce-abcd1234efg之间建立访问关联示例出自 create-domain-name-access-association.rstaws apigateway create-domain-name-access-association \ --domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/my.private.domain.tldabcd1234 \ --access-association-source vpce-abcd1234efg \ --access-association-source-type VPCE输出解析命令成功执行后返回如下 JSON响应结构为DomainNameAccessAssociation{ domainNameAccessAssociationArn: arn:aws:apigateway:us-west-2:012345678910:/domainnameaccessassociations/domainname/my.private.domain.tld/vpcesource/vpce-abcd1234efg, accessAssociationSource: vpce-abcd1234efg, accessAssociationSourceType: VPCE, domainNameArn: arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.comabcd1234 }各字段含义如下与 DomainNameAccessAssociation 结构一一对应字段含义domainNameAccessAssociationArn新建的域名访问关联资源自身的 ARNaccessAssociationSource访问关联源标识符此处为 VPC 端点 ID在响应中官方文档描述为访问关联源的 ARN对于 VPCE 必须是 VPC 端点accessAssociationSourceType访问关联源类型此处为VPCEdomainNameArn被关联的私有自定义域名 ARN注意文档示例中返回的domainNameArn与请求时使用的域名不完全一致my.private.domain.tldvsprivate.example.com这是示例编写时的占位符不一致实际使用时返回的domainNameArn应与请求中指定的--domain-name-arn保持一致。关联操作查询与删除从 API 模型定义service-2.json可以看到与域名访问关联配套的还有查询与删除操作形成完整的生命周期管理闭环查询关联列表GetDomainNameAccessAssociationsservice-2.json用于分页查询当前账号下的所有域名访问关联其响应结构为DomainNameAccessAssociationsservice-2.json包含position分页游标用于获取下一页数据items当前页的DomainNameAccessAssociation元素列表对应 CLI 命令为aws apigateway get-domain-name-access-associations删除关联DeleteDomainNameAccessAssociationservice-2.json用于删除指定 ARN 的域名访问关联HTTP 方法DELETE请求 URI/domainnameaccessassociations/{domain_name_access_association_arn}成功响应码202模型文档特别强调了两点删除语义只有创建该关联资源的 AWS 账号才能删除它如果想停止其他账号中的访问关联源对私有自定义域名的访问应当使用RejectDomainNameAccessAssociation操作而不是DeleteDomainNameAccessAssociation。对应 CLI 命令aws apigateway delete-domain-name-access-association \ --domain-name-access-association-arn arn:aws:apigateway:us-west-2:012345678910:/domainnameaccessassociations/domainname/my.private.domain.tld/vpcesource/vpce-abcd1234efg底层实现视角从仓库的 API 模型service-2.json可以推断出该命令的底层调用链AWS CLI 将create-domain-name-access-association映射为CreateDomainNameAccessAssociationAPI 操作该操作向 API Gateway 服务端发送一个POST请求到/domainnameaccessassociations端点请求体包含domainNameArn、accessAssociationSourceType、accessAssociationSource三个必填字段及可选的tags服务端校验通过后返回201状态码及DomainNameAccessAssociation结构体其中包含新建关联资源的 ARN。使用场景与注意事项典型场景跨网络隔离的私有 API 访问授权当你的私有 API 网关自定义域名需要被特定 VPC 端点访问而又要保持与公网隔离时通过本命令显式建立授权关联多账号架构下的访问控制结合RejectDomainNameAccessAssociation/DeleteDomainNameAccessAssociation的权限语义可以精细管理谁有权限、何时回收权限。注意事项--access-association-source-type当前仅支持枚举值VPCE传入其他值会触发参数校验错误创建时若请求参数非法如 ARN 格式错误、VPC 端点不存在API 会抛出BadRequestException若关联已存在或状态冲突则抛出ConflictException账号级资源配额不足时抛出LimitExceededException删除跨账号的访问关联请使用RejectDomainNameAccessAssociation而不是DeleteDomainNameAccessAssociation可通过--tags为关联资源打标签标签键最长 128 字符不能以aws:开头标签值最长 256 字符合法字符集为[a-zA-Z-._:/]。延伸阅读命令完整示例create-domain-name-access-association.rstAPI 操作与形状定义service-2.jsonAPI Gateway 服务数据目录awscli/botocore/data/apigateway/2015-07-09/含endpoint-rule-set-1.json、examples-1.json、paginators-1.json、service-2.json更多 API Gateway 命令示例见 apigateway 示例目录关于私有 API 自定义域名的详细背景知识可参见 Amazon API Gateway Developer Guide 中 Custom domain names for private APIs in API Gateway 一节。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考