创建私有 API - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

创建私有 API

在创建私有 API 之前,您首先为 API Gateway 创建一个 VPC 端点。接下来,您要创建私有 API 并向其附加资源策略。(可选)您可以将 VPC 端点与私有 API 关联,来简化调用 API 的过程。最后,您部署 API。

以下过程介绍了如何执行完成此操作。您可以使用 Amazon Web Services Management Console、Amazon CLI 或 Amazon SDK 创建私有 REST API。

先决条件

要执行以下步骤,您必须拥有完全配置的 VPC。要了解如何创建 VPC,请参阅《Amazon VPC 用户指南》中的仅创建 VPC。要在创建 VPC 时遵循所有推荐的步骤,请启用私有 DNS。这样,您就可以在 VPC 内调用 API,而不必传递 Host 或 x-apigw-api-id 标头。

要启用私有 DNS,VPC 的 enableDnsSupportenableDnsHostnames 属性必须设置为 true。有关更多信息,请参阅 VPC 中的 DNS 支持更新 VPC 的 DNS 支持

步骤 1:在 VPC 中为 API Gateway 创建 VPC 端点

以下过程展示如何为 API Gateway 创建 VPC 端点。要为 API Gateway 创建 VPC 端点,您需要为在其中创建私有 API 的 Amazon Web Services 区域指定 execute-api 域。execute-api 域是用于 API 执行的 API Gateway 组件服务。

在为 API Gateway 创建 VPC 端点时,需要指定 DNS 设置。如果您关闭私有 DNS,则只能使用公有 DNS 访问您的 API。有关更多信息,请参阅 问题:我无法从 API Gateway VPC 端点连接到我的公有 API

Amazon Web Services Management Console
为 API Gateway 创建接口 VPC 端点
  1. 通过 https://console.aws.amazon.com/vpc/ 登录到Amazon Web Services Management Console并打开 Amazon VPC 控制台。

  2. 在导航窗格中的虚拟私有云下,选择端点

  3. 选择创建端点

  4. (可选)对于名称标签,输入名称以协助标识您的 VPC 端点。

  5. 对于服务类别,选择 Amazon 服务

  6. 服务下的搜索栏中,输入 execute-api。然后,在您将创建 API 的 Amazon Web Services 区域中选择 API Gateway 服务端点。服务名称应类似于 com.amazonaws.us-east-1.execute-api类型应为接口

  7. 对于 VPC,选择要在其中创建端点的 VPC。

  8. (可选)要关闭启用私有 DNS 名称,请选择其他设置,然后清除启用私有 DNS 名称

  9. 对于子网,选择在其中创建了端点网络接口的可用区。要提高 API 的可用性,请选择多个子网。

  10. 对于安全组,选择要与 VPC 端点网络接口关联的安全组。

    您选择的安全组必须设置为允许来自您的 VPC 中的 IP 范围或您的 VPC 中的其他安全组的 TCP 端口 443 入站 HTTPS 通信。

  11. 对于策略,请执行以下操作之一:

    • 如果您尚未创建私有 API 或者不想配置自定义 VPC 端点策略,请选择完全访问权限

    • 如果您已经创建了私有 API 并想要配置自定义 VPC 端点策略,则可以输入自定义 VPC 端点策略。有关更多信息,请参阅 在 API Gateway 中为私有 API 使用 VPC 端点策略

    创建 VPC 端点后,您可以更新 VPC 端点策略。有关更多信息,请参阅 Update a VPC endpoint policy

  12. 选择创建端点

  13. 复制生成的 VPC 端点 ID,以便在将来的步骤中使用。

Amazon CLI

以下 create-vpc-endpoint 命令可用于创建 VPC 端点:

aws ec2 create-vpc-endpoint \ --vpc-id vpc-1a2b3c4d \ --vpc-endpoint-type Interface \ --service-name com.amazonaws.us-east-1.execute-api \ --subnet-ids subnet-7b16de0c \ --security-group-id sg-1a2b3c4d

复制生成的 VPC 端点 ID,以便在将来的步骤中使用。

步骤 2:创建私有密钥

创建 VPC 端点后,您创建一个私有 REST API。以下过程说明了如何创建私有 API。

Amazon Web Services Management Console
要创建私有 API
  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 选择创建 API

  3. REST API 下,选择 Build (生成)

  4. 对于名称,输入名称。

  5. (可选)对于描述,输入描述。

  6. 对于 API 端点类型,选择私有

  7. (可选)对于 VPC 端点 ID,输入 VPC 端点 ID。

    如果您将 VPC 端点 ID 与私有 API 关联,则可以从 VPC 内调用 API,而无需覆盖 Host 标头或传递 x-apigw-api-id header。有关更多信息,请参阅(可选)将 VPC 端点与私有 API 关联或取消关联

  8. 选择创建 API

完成前面的步骤之后,您可以按照开始使用 REST API 控制台中的说明来为此 API 设置方法和集成,但您无法部署 API。要部署您的 API,请执行步骤 3 并将资源策略附加到 API。

Amazon CLI

以下 update-rest-api 命令显示如何创建私有 API:

aws apigateway create-rest-api \ --name 'Simple PetStore (Amazon CLI, Private)' \ --description 'Simple private PetStore API' \ --region us-west-2 \ --endpoint-configuration '{ "types": ["PRIVATE"] }'

成功调用返回类似于以下内容的输出:

{ "createdDate": "2017-10-13T18:41:39Z", "description": "Simple private PetStore API", "endpointConfiguration": { "types": "PRIVATE" }, "id": "0qzs2sy7bh", "name": "Simple PetStore (Amazon CLI, Private)" }

完成前面的步骤之后,您可以按照教程:使用 Amazon SDK 或 Amazon CLI 设置边缘优化的 API中的说明来为此 API 设置方法和集成,但您无法部署 API。要部署您的 API,请执行步骤 3 并将资源策略附加到 API。

SDK JavaScript v3

以下示例说明了如何使用适用于 JavaScript 的 Amazon SDK v3 创建私有 API:

import {APIGatewayClient, CreateRestApiCommand} from "@aws-sdk/client-api-gateway"; const apig = new APIGatewayClient({region:"us-east-1"}); const input = { // CreateRestApiRequest name: "Simple PetStore (JavaScript v3 SDK, private)", // required description: "Demo private API created using the AWS SDK for JavaScript v3", version: "0.00.001", endpointConfiguration: { // EndpointConfiguration types: [ "PRIVATE"], }, }; export const handler = async (event) => { const command = new CreateRestApiCommand(input); try { const result = await apig.send(command); console.log(result); } catch (err){ console.error(err) } };

成功调用返回类似于以下内容的输出:

{ apiKeySource: 'HEADER', createdDate: 2024-04-03T17:56:36.000Z, description: 'Demo private API created using the AWS SDK for JavaScript v3', disableExecuteApiEndpoint: false, endpointConfiguration: { types: [ 'PRIVATE' ] }, id: 'abcd1234', name: 'Simple PetStore (JavaScript v3 SDK, private)', rootResourceId: 'efg567', version: '0.00.001' }

完成前面的步骤之后,您可以按照教程:使用 Amazon SDK 或 Amazon CLI 设置边缘优化的 API中的说明来为此 API 设置方法和集成,但您无法部署 API。要部署您的 API,请执行步骤 3 并将资源策略附加到 API。

Python SDK

以下示例说明了如何使用适用于 Python 的 Amazon SDK 创建私有 API:

import json import boto3 import logging logger = logging.getLogger() apig = boto3.client('apigateway') def lambda_handler(event, context): try: result = apig.create_rest_api( name='Simple PetStore (Python SDK, private)', description='Demo private API created using the AWS SDK for Python', version='0.00.001', endpointConfiguration={ 'types': [ 'PRIVATE', ], }, ) except botocore.exceptions.ClientError as error: logger.exception("Couldn't create private API %s.", error) raise attribute=["id", "name", "description", "createdDate", "version", "apiKeySource", "endpointConfiguration"] filtered_data ={key:result[key] for key in attribute} result = json.dumps(filtered_data, default=str, sort_keys='true') return result

成功调用返回类似于以下内容的输出:

"{\"apiKeySource\": \"HEADER\", \"createdDate\": \"2024-04-03 17:27:05+00:00\", \"description\": \"Demo private API created using the AWS SDK for \", \"endpointConfiguration\": {\"types\": [\"PRIVATE\"]}, \"id\": \"abcd1234\", \"name\": \"Simple PetStore (Python SDK, private)\", \"version\": \"0.00.001\"}"

完成前面的步骤之后,您可以按照教程:使用 Amazon SDK 或 Amazon CLI 设置边缘优化的 API中的说明来为此 API 设置方法和集成,但您无法部署 API。要部署您的 API,请执行步骤 3 并将资源策略附加到 API。

步骤 3:为私有 API 设置资源策略

所有 VPC 都无法访问您当前的私有 API。使用资源策略授予您的 VPC 和 VPC 端点访问私有 API 的权限。您可以向任何 Amazon 账户中的 VPC 端点授予访问权限。

您的资源策略应包含 aws:SourceVpcaws:SourceVpce 条件来限制访问权限。我们建议您标识特定的 VPC 和 VPC 端点,而不要创建允许所有 VPC 和 VPC 端点访问的资源策略。

以下过程展示如何向 API 附加资源策略。

Amazon Web Services Management Console
  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 选择一个 REST API。

  3. 在主导航窗格中,选择资源策略

  4. 选择创建策略

  5. 选择选择模板,然后选择源 VPC

  6. {{vpceID}}(包括大括号)替换为您的 VPC 端点 ID。

  7. 选择 Save changes(保存更改)

Amazon CLI

以下 update-rest-api 命令显示如何将资源策略附加到现有 API:

aws apigateway update-rest-api \ --rest-api-id a1b2c3 \ --patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"'

您可能还要控制哪些资源可以访问您的 VPC 端点。要控制哪些资源可以访问 VPC 端点,请向 VPC 端点附加端点策略。有关更多信息,请参阅 在 API Gateway 中为私有 API 使用 VPC 端点策略

(可选)将 VPC 端点与私有 API 关联或取消关联

当您将 VPC 端点与私有 API 关联时,API Gateway 将生成新的 Route 53 别名 DNS 记录。您可以使用此记录调用私有 API,就像使用公有 API 一样,而无需覆盖 Host 标头或传递 x-apigw-api-id 标头。

生成的基本 URL 采用以下格式:

https://{rest-api-id}-{vpce-id}.execute-api.{region}.amazonaws.com/{stage}
Associate a VPC endpoint (Amazon Web Services Management Console)

您可以在创建私有 API 时或创建后,将 VPC 端点与私有 API 关联起来。以下过程展示如何将 VPC 端点与先前创建的 API 相关联。

将 VPC 端点与私有 API 关联
  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 选择您的私有 API。

  3. 在主导航窗格中,选择资源策略

  4. 编辑您的资源策略以允许来自其他 VPC 端点的调用。

  5. 在主导航窗格中,选择 API 设置

  6. API 详细信息部分中,选择编辑

  7. 对于 VPC 端点 ID,请选择其他 VPC 端点 ID。

  8. 选择保存

  9. 重新部署 API 以使更改生效。

Dissociate a VPC endpoint (Amazon Web Services Management Console)
将 VPC 端点与私有 REST API 取消关联
  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 选择您的私有 API。

  3. 在主导航窗格中,选择资源策略

  4. 编辑您的资源策略,对于您要与私有 API 取消关联的 VPC 端点,删除提及该端点的内容。

  5. 在主导航窗格中,选择 API 设置

  6. API 详细信息部分中,选择编辑

  7. 对于 VPC 端点 ID,选择 X 以与 VPC 端点取消关联。

  8. 选择保存

  9. 重新部署 API 以使更改生效。

Associate a VPC endpoint (Amazon CLI)

以下 create-rest-api 命令显示如何在创建 API 时关联 VPC 端点。

aws apigateway create-rest-api \ --name Petstore \ --endpoint-configuration '{ "types": ["PRIVATE"], "vpcEndpointIds" : ["vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee"] }' \ --region us-west-2

输出将与以下内容类似:

{ "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "PRIVATE" ], "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee" ] }, "id": "u67n3ov968", "createdDate": 1565718256, "name": "Petstore" }

以下 update-rest-api 命令显示如何将 VPC 端点与已经创建的 API 关联:

aws apigateway update-rest-api \ --rest-api-id u67n3ov968 \ --patch-operations "op='add',path='/endpointConfiguration/vpcEndpointIds',value='vpce-01d622316a7df47f9'" \ --region us-west-2

输出将与以下内容类似:

{ "name": "Petstore", "apiKeySource": "1565718256", "tags": {}, "createdDate": 1565718256, "endpointConfiguration": { "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee", "vpce-01d622316a7df47f9" ], "types": [ "PRIVATE" ] }, "id": "u67n3ov968" }

重新部署 API 以使更改生效。

Disassociate a VPC endpoint (Amazon CLI)

以下 update-rest-api 命令显示如何将 VPC 端点与私有 API 取消关联:

aws apigateway update-rest-api \ --rest-api-id u67n3ov968 \ --patch-operations "op='remove',path='/endpointConfiguration/vpcEndpointIds',value='vpce-0393a628149c867ee'" \ --region us-west-2

输出将与以下内容类似:

{ "name": "Petstore", "apiKeySource": "1565718256", "tags": {}, "createdDate": 1565718256, "endpointConfiguration": { "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9" ], "types": [ "PRIVATE" ] }, "id": "u67n3ov968" }

重新部署 API 以使更改生效。

步骤 4:部署私有 API

要部署 API,您可以创建 API 部署并将其与阶段关联。以下过程显示如何部署私有 API。

Amazon Web Services Management Console
部署私有 API
  1. 选择 API。

  2. 选择部署 API

  3. 对于阶段,选择新建阶段

  4. 对于阶段名称,输入阶段名称。

  5. (可选)对于描述,输入描述。

  6. 选择部署

Amazon CLI

以下 create-deployment 命令显示如何部署私有 API:

aws apigateway create-deployment --rest-api-id a1b2c3 \ --stage-name test \ --stage-description 'Private API test stage' \ --description 'First deployment'

对私有 API 进行故障排除

以下内容为您在创建私有 API 时可能遇到的错误和问题提供故障排除建议。

问题:我无法从 API Gateway VPC 端点连接到我的公有 API

创建 VPC 时,您可以配置 DNS 设置。我们建议您为 VPC 开启私有 DNS。如果您选择关闭私有 DNS,您只能通过公有 DNS 访问您的 API。

如果您启用私有 DNS,则无法从 VPC 端点访问公有 API Gateway API 的默认端点。您可以使用自定义域名访问 API。

如果您创建区域自定义域名,请使用 A 类型别名记录;如果您创建边缘优化的自定义域名,则不限制记录类型。您可以在启用私有 DNS 的情况下访问这些公有 API。有关更多信息,请参阅问题:我无法从 API Gateway VPC 端点连接到我的公有 API

问题:我的 API 返回 {"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: arn:aws:execute-api:us-east-1:********/****/****/"}

在资源策略中,如果您将主体设置为 Amazon 主体,如下所示:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", ""Principal": { "AWS": [ "arn:aws:iam::account-id:role/developer", "arn:aws:iam::account-id:role/Admin" ] }, "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, ... }

您必须对 API 中的每个方法使用 AWS_IAM 授权,否则 API 会返回之前的错误消息。有关如何为方法开启 AWS_IAM 授权的更多说明,请参阅 API Gateway 中用于 REST API 的方法

问题:我无法分辨我的 VPC 端点是否与我的 API 关联

如果您将 VPC 端点与私有 API 关联或取消关联,则需要重新部署 API。由于 DNS 传播,更新操作可能需要几分钟才能完成。在这段时间内,您的 API 将可用,但新生成的 DNS URL 的 DNS 传播可能仍在进行中。如果几分钟后,您的新 URL 仍无法在 DNS 中解析,我们建议您重新部署 API。