Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

在 API Gateway 中为区域 REST API 或 WebSocket API 设置自定义域名

与边缘优化的 API 终端节点一样,您可为区域 API 终端节点创建自定义域名。要支持区域自定义域名,必须提供证书。如果使用 AWS Certificate Manager (ACM) 证书,此证书必须是特定于区域的。如果 ACM 在区域中可用,则必须提供特定于该区域的 ACM 证书。如果该区域不支持 ACM,则必须在创建区域自定义域名时将证书上传到该区域的 API Gateway。有关创建或上传自定义域名证书的更多信息,请参阅在 AWS Certificate Manager 中准备好证书

重要

对于 API Gateway 区域自定义域名,您必须在与 API 相同的区域中请求或导入证书。

在您创建(或迁移)包含 ACM 证书的区域自定义域名时,如果不存在服务相关角色,API Gateway 会在您的账户中创建一个这样的角色。需要使用服务相关角色,才能将 ACM 证书附加到您的区域终端节点。该角色名为 AWSServiceRoleForAPIGateway,将附加 APIGatewayServiceRolePolicy 托管策略。有关使用服务相关角色的更多信息,请参阅使用服务相关角色

重要

您必须创建将自定义域名指向区域域名的 DNS 记录。这使绑定到自定义域名的流量可以路由到 API 的区域主机名。DNS 记录可以是 CNAME 或 A 类型。

使用 API Gateway 控制台设置带 ACM 证书的区域自定义域名

要使用 API Gateway 控制台设置区域自定义域名,请使用以下过程。

使用 API Gateway 控制台设置区域自定义域名

  1. 登录到 API Gateway 控制台并在主导航窗格中选择 Custom Domain Names (自定义域名)

  2. 选择 Custom Domain Names (自定义域名) 表上方的 +Create New Custom Domain Name (+创建新自定义域名)

  3. New Custom Domain Name (新的自定义域名) 下:

    1. 选择 API 协议:HTTPWebSocket

    2. Domain Name (域名) 下的 Domain Name (域名) 中,键入自定义域名,例如 my-api.example.com

  4. Security Policy (安全策略) 中,选择所需的最低传输层安全性 (TLS) 版本。

  5. Endpoint Configuration (终端节点配置) 下选择 Regional (区域)

  6. ACM Certificate (ACM 证书) 下拉列表中选择证书。证书必须来自部署 API 的同一区域。

  7. 如果您已创建和部署了 API 来使用此自定义域名,请选择 Add mapping (添加映射),在自定义域名下的 Path (路径) 中键入基本路径,从 Destination (目标) 下的 API 下拉列表中选择 API,然后从 Stage (阶段) 下拉列表中选择阶段。要添加另一个基本路径映射,请重复该步骤。此外,您还可以在创建自定义域名后设置基本路径映射。有关更多信息,请参阅 配置其中自定义域名作为主机名的 API 的基本路径映射

  8. 选择 Save

  9. 按照 Route 53 文档中有关配置 Route 53 以将流量路由至 API Gateway 的说明操作。

使用 AWS CLI 设置带 ACM 证书的区域自定义域名

要使用 AWS CLI 为区域 API 设置自定义域名,请使用以下过程。

  1. 调用 create-domain-name,并指定 REGIONAL 类型的自定义域名和区域证书的 ARN。

    aws apigateway create-domain-name \ --domain-name 'regional.example.com' \ --endpoint-configuration types=REGIONAL \ --regional-certificate-arn 'arn:aws:acm:us-west-2:123456789012:certificate/c19332f0-3be6-457f-a244-e03a423084e6'

    请注意,指定的证书来自 us-west-2 区域,在此示例中,我们假定底层 API 来自同一区域。

    如果成功,调用返回的结果类似于以下内容:

    { "certificateUploadDate": "2017-10-13T23:02:54Z", "domainName": "regional.example.com", "endpointConfiguration": { "types": "REGIONAL" }, "regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/c19332f0-3be6-457f-a244-e03a423084e6", "regionalDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com" }

    regionalDomainName 属性值返回区域 API 的主机名。您必须创建将您的自定义域名指向此区域域名的 DNS 记录。这使绑定到自定义域名的流量可以路由到该区域 API 的主机名。

  2. 创建将自定义域名与区域域名进行关联的 DNS 记录。这使绑定到自定义域名的请求可以路由到 API 的区域主机名。

  3. 添加基本路径映射,以在部署阶段 (例如 0qzs2sy7bh) 在指定的自定义域名 (例如 test) 下公开指定的 API (例如 regional.example.com)。

    aws apigateway create-base-path-mapping \ --domain-name 'regional.example.com' \ --base-path 'RegionalApiTest' \ --rest-api-id 0qzs2sy7bh \ --stage 'test'

    这样,在此阶段部署的使用 API 的自定义域名的基本 URL 会变为 https://regional.example.com/RegionalApiTest

  4. 配置 DNS 记录,以将区域自定义域名映射到给定的托管区域 ID 的主机名。首先创建一个 JSON 文件,其中包含为区域域名设置 DNS 记录的配置。以下示例显示了如何创建 DNS A 记录,以将区域自定义域名 (regional.example.com) 映射到在创建自定义域名时为其预配置的区域主机名 (d-numh1z56v6.execute-api.us-west-2.amazonaws.com)。DNSNameHostedZoneIdAliasTarget 属性可分别采用自定义域名的 regionalDomainNameregionalHostedZoneId 值。您也可以在 API Gateway 区域和终端节点中获取区域 Route 53 托管区域 ID。

    { "Changes": [ { "Action": "CREATE", "ResourceRecordSet": { "Name": "regional.example.com", "Type": "A", "AliasTarget": { "DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com", "HostedZoneId": "Z2OJLYMUO9EFXC", "EvaluateTargetHealth": false } } } ] }
  5. 运行以下 CLI 命令:

    aws route53 change-resource-record-sets \ --hosted-zone-id {your-hosted-zone-id} \ --change-batch file://path/to/your/setup-dns-record.json

    其中,{your-hosted-zone-id} 是您账户中的 DNS 记录集的 Route 53 托管区域 ID。change-batch 参数值指向文件夹 (path/to/your) 中的 JSON 文件 (setup-dns-record.json)。

使用 AWS CLI 设置不带 ACM 的区域自定义域名证书

要使用 AWS CLI 在 ACM 不可用的区域中为区域 API 设置自定义域名,您需要使用以下过程直接将证书上传到 API Gateway。

要将服务器证书上传到 API Gateway,您必须提供证书及其匹配的私有密钥。如果证书不是自签名的,则您还必须提供证书链。(上传自签名证书时无需证书链。) 在上传证书前,请确保您已具有所有这些项目而且它们满足以下条件:

  • 证书在上传时必须是有效的。您不能在证书有效期开始 (证书的 NotBefore 日期) 之前或证书有效期到期 (证书的 NotAfter 日期) 之后上传证书。

  • 私有密钥必须是未加密的。您不能上传受密码或口令保护的私有密钥。有关解密加密私有密钥的帮助信息,请参阅故障排除

  • 证书、私有密钥和证书链必须均采用 PEM 编码。有关将这些项目转换为 PEM 格式的帮助信息,请参阅故障排除

  1. 创建以下 PEM 文件。如果您使用不同的文件名,您需要更改 create-domain-name 命令中的文件名以进行匹配。

    • 将 PEM 编码的证书存储在名为 Certificate.pem 的文件中。

    • 将 PEM 编码的证书链存储在名为 CertificateChain.pem 的文件中。

    • 将 PEM 编码的未加密私有密钥存储在名为 PrivateKey.pem 的文件中。

  2. 要使用以下示例命令,请将这些文件名替换为您自己的名称并且将 'regional.example.com cert' 替换为您上传的证书的名称。在一个连续行上键入命令。为更便于阅读,以下示例包含了换行符和多余的空格。

    aws apigateway create-domain-name --domain-name 'regional.example.com' --regional-certificate-name 'regional.example.com cert' --certificate-body file://Certificate.pem --certificate-private-key file://PrivateKey.pem --certificate-chain file://CertificateChain.pem --endpoint-configuration types=REGIONAL

    如果成功,调用返回的结果类似于以下内容:

    { "certificateUploadDate": "2017-10-13T23:02:54Z", "domainName": "regional.example.com", "endpointConfiguration": { "types": "REGIONAL" }, "regionalCertificateArn": "arn:aws:apigateway:us-west-2:123456789012:certificate/c19332f0-3be6-457f-a244-e03a423084e6", "regionalDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com" }

    regionalDomainName 属性值返回区域 API 的主机名。您必须创建将您的自定义域名指向此区域域名的 DNS 记录。这使绑定到自定义域名的流量可以路由到该区域 API 的主机名。

  3. 添加基本路径映射,以在部署阶段 (例如 0qzs2sy7bh) 在指定的自定义域名 (例如 test) 下公开指定的 API (例如 regional.example.com)。

    aws apigateway create-base-path-mapping \ --domain-name 'regional.example.com' \ --base-path 'RegionalApiTest' \ --rest-api-id 0qzs2sy7bh \ --stage 'test'

    这样,在此阶段部署的使用 API 的自定义域名的基本 URL 会变为 https://regional.example.com/RegionalApiTest

  4. 注意

    此步骤假定您的域将托管在 Route 53 中。

    配置 DNS 记录以将区域自定义域名映射到目标域名。首先创建一个 JSON 文件,其中包含为区域域名设置 DNS 记录的配置。以下示例显示了如何创建 DNS A 记录,以将区域自定义域名 (regional.example.com) 映射到在创建自定义域名时为其预配置的区域主机名 (d-numh1z56v6.execute-api.us-west-2.amazonaws.com)。AliasTargetDNSNameHostedZoneId 属性可以分别获取您在 API Gateway 控制台中看到的自定义域名的目标域名和托管区域 ID 值。您也可以在 API Gateway 区域和终端节点中获取区域 Route 53 托管区域 ID。

    { "Changes": [ { "Action": "CREATE", "ResourceRecordSet": { "Name": "regional.example.com", "Type": "A", "AliasTarget": { "DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com", "HostedZoneId": "Z2OJLYMUO9EFXC", "EvaluateTargetHealth": false } } } ] }
  5. 运行以下 CLI 命令:

    aws route53 change-resource-record-sets \ --hosted-zone-id {your-hosted-zone-id} \ --change-batch file://path/to/your/setup-dns-record.json

    其中,{your-hosted-zone-id} 是您账户中的 DNS 记录集的 Route 53 托管区域 ID。change-batch 参数值指向文件夹 (path/to/your) 中的 JSON 文件 (setup-dns-record.json)。