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

使用 AWS CLI 设置具有私有集成的 API Gateway API

Before creating an API with the private integration, you must have your VPC resource set up and a network load balancer created and configured with your VPC source as the target. If the requirements are not met, follow 为 API Gateway 私有集成设置网络负载均衡器 to install the VPC resource, create a NLB, set the VPC resource as a target of the network load balancer.

For you to be able to create and manage a VpcLink, you must also have the appropriate permissions configured. For more information, see 授予创建 VPC 链接的权限.

注意

You only need the permissions to create a VpcLink in your API. You do not need the permissions to use the VpcLink.

创建网络负载均衡器之后,记录其 ARN。您需要它来为私有集成创建 VPC 链接。

使用 AWS CLI 设置具有私有集成的 API

  1. 创建 VpcLink 定位到指定网络负载均衡器。

    在此讨论中,我们假设网络负载均衡器的 ARN 为 arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/my-vpclink-test-nlb/1f8df693cd094a72

    aws apigateway create-vpc-link \ --name my-test-vpc-link \ --target-arns arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/my-vpclink-test-nlb/1f8df693cd094a72 \ --endpoint-url https://apigateway.us-east-1.amazonaws.com \ --region us-east-1

    如果 AWS 配置使用 us-east-1 作为默认区域,您可以跳过之前输入中的 endpoint-urlregion 参数。

    之前的命令立即返回以下响应,确认收到请求,并为所创建的 VpcLink 显示 PENDING 状态。

    { "status": "PENDING", "targetArns": [ "arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/my-vpclink-test-nlb/1f8df693cd094a72" ], "id": "gim7c3", "name": "my-test-vpc-link" }

    API Gateway 完成创建 VpcLink 大约需要 2-4 分钟。操作成功完成后,statusAVAILABLE。您可以通过调用以下 CLI 命令验证这一点:

    aws apigateway get-vpc-link --vpc-link-id gim7c3

    如果操作失败,您将收到 FAILED 状态,以及包含错误消息的 statusMessage。例如,如果您尝试使用已经与 VPC 终端节点关联的网络负载均衡器创建 VpcLink,在 statusMessage 属性上将获得以下内容:

    "NLB is already associated with another VPC Endpoint Service"

    只有在成功创建 VpcLink 之后,我们才准备好创建 API 并通过 VpcLink 将其与 VPC 资源集成。

    记录新创建 VpcLinkid 值 (之前输出中的 gim7c3)。设置私有集成时需要该值。

  2. 通过创建 API Gateway RestApi 资源设置 API:

    aws apigateway create-rest-api --name 'My VPC Link Test'

    我们已删除 endpoint-urlregion 的输入参数,以使用在 AWS 配置中指定的默认区域。

    请记录返回结果中 RestApiid 值。在本例中,我们假设它为 6j4m3244we。您需要此值在 API 上进一步执行操作,包括设置方法和集成。

    为了方便说明,我们将在根资源 (/) 上创建仅具有 GET 方法的 API,并将方法与 VpcLink 集成。

  3. 设置 GET / 方法。首先获取根资源 (/) 的标识符:

    aws apigateway get-resources --rest-api-id 6j4m3244we

    在输出中,记录 / 路径的 id 值。在本例中,我们假设它为 skpp60rab7

    为 API 方法 GET / 设置方法请求:

    aws apigateway put-method \ --rest-api-id 6j4m3244we \ --resource-id skpp60rab7 \ --http-method GET \ --authorization-type "NONE"

    要使用 IAM 权限、自定义授权方或 Amazon Cognito 用户池对调用方进行身份验证,请将 authorization-type 分别设置为 AWS_IAMCUSTOMCOGNITO_USER_POOLS

    如果您不将代理集成用于 VpcLink,则还必须至少设置一个 200 状态代码的方法响应。我们在这里使用代理集成。

  4. 设置 HTTP_PROXY 类型的私有集成,并按以下所示调用 put-integration 命令:

    aws apigateway put-integration \ --rest-api-id 6j4m3244we \ --resource-id skpp60rab7 \ --uri 'http://myApi.example.com' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id gim7c3

    对于私有集成,您必须将 connection-type 设置为 VPC_LINK,将 connection-id 设置为 VpcLink 的标识符或引用 VpcLink ID 的阶段变量。uri 参数不用于将请求路由到终端节点,而是用于设置 Host 标头和证书验证。

    如果成功,该命令会返回以下输出:

    { "passthroughBehavior": "WHEN_NO_MATCH", "timeoutInMillis": 29000, "connectionId": "gim7c3", "uri": "http://myApi.example.com", "connectionType": "VPC_LINK", "httpMethod": "GET", "cacheNamespace": "skpp60rab7", "type": "HTTP_PROXY", "cacheKeyParameters": [] }

    使用阶段变量,在创建集成时设置 connectionId 属性:

    aws apigateway put-integration \ --rest-api-id 6j4m3244we \ --resource-id skpp60rab7 \ --uri 'http://myApi.example.com' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id "\${stageVariables.vpcLinkId}"

    请确保使用双引号括起阶段变量表达式 (${stageVariables.vpcLinkId}) 并转义 $ 字符。

    或者,您可以更新集成以使用阶段变量重置 connectionId 值:

    aws apigateway update-integration \ --rest-api-id 6j4m3244we \ --resource-id skpp60rab7 \ --http-method GET \ --patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]'

    请确保使用字符串化的 JSON 列表作为 patch-operations 参数值。

    使用阶段变量设置 connectionId 值的优点在于,可以通过重置阶段变量值,将相同 API 集成到不同 VpcLink。这在将 API 切换到不同 VPC 链接以迁移到不同网络负载均衡器或者不同 VPC 时非常有用。

    由于我们使用了私有代理集成,API 现已准备好,可用于部署和测试运行。使用非代理集成,您还必须设置方法响应和集成响应,就像您在使用 HTTP 自定义集成设置 API 时一样。

  5. 测试 API 需要部署 API。如果您使用了阶段变量作为 VpcLink ID 的占位符,则这是必需的。要使用阶段变量部署 API,请按以下所示调用 create-deployment 命令:

    aws apigateway create-deployment \ --rest-api-id 6j4m3244we \ --stage-name test \ --variables vpcLinkId=gim7c3

    要使用不同 VpcLink ID 更新阶段变量 (例如 asf9d7),请调用 update-stage 命令:

    aws apigateway update-stage \ --rest-api-id 6j4m3244we \ --stage-name test \ --patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'

    要测试 API,请使用以下 cURL 命令调用它:

    curl -X GET https://6j4m3244we.beta.execute-api.us-east-1.amazonaws.com/test

    此外,您可以在 Web 浏览器中键入 API 的调用 URL 来查看结果。

    当您使用 VpcLink ID 文本硬编码 connection-id 时,您还可以调用 test-invoke-method,在部署 API 之前进行测试。