如何使用 API Gateway 作为其他亚马逊云科技服务的代理？

5 分钟阅读

我想使用 Amazon API Gateway 作为另一个亚马逊云科技服务的代理，并将其他服务与 API Gateway 集成。

简短描述

亚马逊云科技服务 API 本质上是 REST API，您可以向其发出 HTTPS 请求。您可以将许多亚马逊云科技服务与 API Gateway 集成，但设置和映射方法因特定服务 API 而异。

要将其他服务与 API Gateway 集成，请构建从 API Gateway 到服务 API 的 HTTPS 请求。如此，所有请求参数都能正确映射。

本文介绍了将 Amazon Simple Notiﬁcation Service (Amazon SNS) Publish API 与 API Gateway 集成的示例设置。此示例概述如何集成其他服务。

解决方法

**注意：**如果在运行 Amazon 命令行界面 (Amazon CLI) 命令时收到错误，请确保您使用的是最新的 Amazon CLI 版本。

设置所需的工具和资源

配置环境并创建用例所需的所有亚马逊云科技资源。对于 Amazon SNS 示例设置，请按下面的步骤操作：

安装 Amazon CLI。
创建 Amazon SNS 主题。记下该主题的 Amazon 资源名称 (ARN, Amazon Resource Name)。在下一步及稍后的设置中使用此信息。
为该主题创建订阅。
打开 Amazon Identity and Access Management (Amazon IAM) 控制台，然后创建亚马逊云科技服务代理执行角色。记下相应角色的 ARN，以便稍后在设置中使用。此 IAM 角色授权 API Gateway 作为可信实体，代入服务并执行要集成的 API 操作。对于 Amazon SNS 示例设置，请允许 sns:Publish 操作。有关更多信息，请参阅用于调用 API 的 API Gateway 权限模型。
使用测试资源，创建 API Gateway REST API。有关更多信息和示例，请参阅 Amazon API Gateway 教程和研讨会。
注意：或使用以下 OpenAPI 2.0 (Swagger) 示例定义，导入 REST API。此选项预配置 Amazon SNS 示例设置。确保将 arn:aws:iam::account-id:role/apigateway-sns-role 替换为您 IAM 角色的 ARN。将区域替换为要创建 REST API 的亚马逊云科技区域。

{
  "swagger": "2.0",
  "info": {
    "version": "2019-10-09T14:10:24Z",
    "title": "aws-service-integration"
  },
  "basePath": "/dev",
  "schemes": [
    "https"
  ],
  "paths": {
    "/test": {
      "post": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "Message",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "TopicArn",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "credentials": "arn:aws:iam::account-id:role/apigateway-sns-role",
          "uri": "arn:aws:apigateway:region:sns:action/Publish",
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn",
            "integration.request.querystring.Message": "method.request.querystring.Message"
          },
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws"
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  }
}

获取 HTTPS 请求示例

要集成的服务 API 发送的 HTTPS 请求示例可以帮助您在 API Gateway 中正确映射请求参数。要获取 HTTPS 请求示例，请执行下列操作之一：

查看 API 文档中的示例。对于 Amazon SNS Publish API，您可以参阅该服务的 API 参考，获取请求示例：

https://sns.us-west-2.amazonaws.com/?Action=Publish
&TargetArn=arn%3Aaws%3Asns%3Aus-west-2%3A803981987763%3Aendpoint%2FAPNS_SANDBOX%2Fpushapp%2F98e9ced9-f136-3893-9d60-776547eafebb
&Message=%7B%22default%22%3A%22This+is+the+default+Message%22%2C%22APNS_SANDBOX%22%3A%22%7B+%5C%22aps%5C%22+%3A+%7B+%5C%22alert%5C%22+%3A+%5C%22You+have+got+email.%5C%22%2C+%5C%22badge%5C%22+%3A+9%2C%5C%22sound%5C%22+%3A%5C%22default%5C%22%7D%7D%22%7D
&Version=2010-03-31
&AUTHPARAMS

-或-

调用 API，生成示例。使用 Amazon CLI 调用服务 API，然后分析输出。针对要集成的服务 API，确定相应的 Amazon CLI 命令，然后使用 --debug 选项，运行测试请求。

**提示：**查看 Amazon CLI 命令参考，找到相应的 Amazon CLI 命令。

对于 Amazon SNS 示例设置，请运行以下命令：

**注意：**将 arn:aws:sns:us-east-1:123456789012:test 替换为您 Amazon SNS 主题的 ARN。

$ aws sns publish --topic-arn arn:aws:sns:us-east-1:123456789012:test --message "hi" --debug

命令输出包含 HTTPS 请求和传递的标头。以下示例是要寻找的内容：

2018-11-22 11:56:39,647 - MainThread - botocore.client - DEBUG - Registering retry handlers for service: sns
2018-11-22 11:56:39,648 - MainThread - botocore.hooks - DEBUG - Event before-parameter-build.sns.Publish: calling handler <function generate_idempotent_uuid at 0x11093d320>
2018-11-22 11:56:39,649 - MainThread - botocore.endpoint - DEBUG - Making request for OperationModel(name=Publish) (verify_ssl=True) with params: {'body': {'Action': u'Publish', u'Message': u'hello', 'Version': u'2010-03-31', u'TopicArn': u'arn:aws:sns:us-east-1:123456789012:test'}, 'url': u'https://sns.us-east-1.amazonaws.com/', 'headers': {'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8', 'User-Agent': 'aws-cli/1.15.74 Python/2.7.14 Darwin/16.7.0 botocore/1.9.23'}, 'context': {'auth_type': None, 'client_region': 'us-east-1', 'has_streaming_input': False, 'client_config': <botocore.config.Config object at 0x1118437d0>}, 'query_string': '', 'url_path': '/', 'method': u'POST'}
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event request-created.sns.Publish: calling handler <bound method RequestSigner.handler of <botocore.signers.RequestSigner object at 0x111843750>>
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event choose-signer.sns.Publish: calling handler <function set_operation_specific_signer at 0x11093d230>
2018-11-22 11:56:39,650 - MainThread - botocore.auth - DEBUG - Calculating signature using v4 auth.
2018-11-22 11:56:39,651 - MainThread - botocore.auth - DEBUG - CanonicalRequest:
POST
/

content-type:application/x-www-form-urlencoded; charset=utf-8
host:sns.us-east-1.amazonaws.com
x-amz-date:20181122T062639Z

content-type;host;x-amz-date

在此示例中，请求以 POST HTTP 方法发送。

创建 API Gateway API 方法

在 API Gateway 控制台的 API 面板中，选择 API 的名称。
在资源面板中，选择一个资源。对于 Amazon SNS 示例设置，请选择您创建的测试资源。
选择操作，然后选择创建方法。
在 HTTPS 请求示例的下拉列表中，选择服务 API 使用的方法。（对于 Amazon SNS 示例设置，请选择 POST。）然后，选择复选标记图标。
在设置面板中，按下面的步骤操作：
对于集成类型，选择亚马逊云科技服务。
对于亚马逊云科技区域，选择与要集成的服务 API 关联的资源所在的亚马逊云科技区域。对于 Amazon SNS 示例设置，选择您 SNS 主题的区域。
对于亚马逊云科技服务，选择要与 API Gateway 集成的服务。例如 Simple Notiﬁcation Service (Amazon SNS)。
（可选）对于亚马逊云科技子域，输入亚马逊云科技服务使用的子域。查看服务的文档，确认子域是否可用。对于 Amazon SNS 示例设置，将其留空。
对于 HTTP 方法，选择与要集成的亚马逊云科技服务 API 对应的方法。对于 Amazon SNS 示例设置，选择 POST。
对于操作类型，如果支持您集成服务 API，请选择使用操作名称。查看服务的 API 参考，获取一系列支持的操作。有关 Amazon SNS，请参阅操作。
对于操作，输入服务 API 的名称。对于 Amazon SNS 示例设置，输入 Publish。
-或-
对于操作类型，如果亚马逊云科技服务 API 需要您请求的资源路径，请选择使用路径覆盖。例如，对于 Amazon Polly ListLexicons API，针对路径覆盖（可选），输入 /v1/lexicons。
对于执行角色，输入您创建的 IAM 角色的 ARN。
（可选）对于内容处理和使用默认超时，根据用例需要进行更改。对于 Amazon SNS 示例设置，请勿更改这些设置。
选择保存。

创建方法请求的参数

针对要集成的服务 API，确定必需和可选请求参数。要明确这些参数，请参阅您之前得到的 HTTPS 请求示例，或参阅服务 API 的 API 参考。例如，请参阅 Publish。

在 API Gateway 控制台中，前往 API Gateway API 方法的方法执行面板，选择方法请求。
（可选）如果您要验证查询字符串参数，请前往方法请求面板，针对请求验证程序，选择请求验证程序、正文和标头。
展开 URL 查询字符串参数。
选择添加查询字符串。
对于名称，针对要集成的服务 API，输入请求参数的名称。
选择复选标记图标（创建新的查询字符串）。
如果参数为必需参数，请选中必需下的复选框。
对要包含的所有请求参数重复步骤 4-7。对于 Amazon SNS 示例设置，创建一个名为 T****opicArn 的参数和另一个名为 Message 的参数。

有关更多信息，请参阅使用 API Gateway 控制台设置方法。

注意：对于某些服务 API，除了必需参数外，还必须在集成请求中发送必需的标头和正文。前往 HTTP 请求标头和请求正文，在集成请求面板中，可以创建标头和正文。

例如，如果要集成 Amazon Rekognition ListCollections API，则创建 X-Amz-Target: RekognitionService.ListCollections 标头。请求如下所示：

POST https://rekognition.us-west-2.amazonaws.com/ HTTP/1.1
    Host: rekognition.us-west-2.amazonaws.com
    Accept-Encoding: identity
    Content-Length: 2
    X-Amz-Target: RekognitionService.ListCollections
    X-Amz-Date: 20170105T155800Z
    User-Agent: aws-cli/1.11.25 Python/2.7.9 Windows/8 botocore/1.4.82
    Content-Type: application/x-amz-json-1.1
    Authorization: AWS4-HMAC-SHA256 Credential=XXXXXXXX/20170105/us-west-2/rekognition/aws4_request,
      SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=XXXXXXXX

    {}

如果要集成 Amazon Simple Queue Service (Amazon SQS) SendMessage API，则使用映射表达式 method.request.body.JSONPath_EXPRESSION，映射请求正文。（对于请求正文的 JSON 字段，将 JSONPath_EXPRESSION 替换为 JSONPath 表达式。）在此示例中，请求与以下内容类似：

{'url_path': '/', 'query_string': '', 'method': 'POST',
'headers': {'Content-Type': 'application/x-www-form-urlencoded;
charset=utf-8', 'User-Agent': 'aws-cli/1.16.81 Python/3.6.5 Darwin/18.7.0 botocore/1.12.183'},
'body': {'Action': 'SendMessage', 'Version': '2012-11-05', 'QueueUrl': 'https://sqs.ap-southeast-2.amazonaws.com/123456789012/test01', 'MessageBody': 'Hello'},
'url': 'https://ap-southeast-2.queue.amazonaws.com/', 'context': {'client_region': 'ap-southeast-2', 'client_config': <botocore.config.Config object at 0x106862da0>, 'has_streaming_input': False, 'auth_type': None}}

创建集成请求的参数

将创建的方法请求参数映射到集成请求参数。

在 API Gateway 控制台中，返回 API Gateway API 方法的方法执行面板，然后选择集成请求。
在集成请求面板中，展开 URL 查询字符串参数。
选择添加查询字符串。
对于名称，针对要集成的服务 API，输入请求参数的名称。
**注意：**名称区分大小写，且必须完全符合服务 API 的要求。
对于映射自，输入 method.request.querystring.param_name。将 param\ _name 替换为创建的方法请求参数的名称。例如 method.request.querystring.TopicArn。
选择复选标记图标（创建）。
重复步骤 3-6，为您创建的各个方法请求参数创建对应的集成请求参数。

注意：如果您创建了方法请求的必需标头和正文，请同时将其映射到集成请求。前往 HTTP 标头和映射模板，在集成请求面板中创建标头和正文。

有关更多信息，请参阅使用 API Gateway 控制台设置 API 集成请求。

（可选）检查集成配置

要确认您的集成设置符合要求，可以运行 Amazon CLI get-integration 命令，检查类似于以下内容的配置：

$ aws apigateway get-integration --rest-api-id 1234123412 --resource-id y9h6rt --http-method POST

对于 Amazon SNS 示例设置，输出类似于以下内容：

{
    "integrationResponses": {
        "200": {
            "responseTemplates": {
                "application/json": null
            },
            "statusCode": "200"
        }
    },
    "passthroughBehavior": "WHEN_NO_MATCH",
    "timeoutInMillis": 29000,
    "uri": "arn:aws:apigateway:us-east-2:sns:action/Publish",
    "httpMethod": "POST",
    "cacheNamespace": "y9h6rt",
    "credentials": "arn:aws:iam::1234567890:role/apigateway-sns-role",
    "type": "AWS",
    "requestParameters": {
        "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn",
        "integration.request.querystring.Message": "method.request.querystring.Message"
    },
    "cacheKeyParameters": []
}

在 API Gateway 控制台中，返回 API Gateway API 方法的方法执行面板，然后选择测试。

在方法测试面板中，按下面的步骤操作：
对于查询字符串，输入查询字符串，其中包含请求参数及其值。对于 Amazon SNS 示例设置，输入 TopicArn= arn:aws:sns:us-east-1:123456789012:test&Message="Hello"。将 arn:aws:sns:us-east-1:123456789012:test 替换为 Amazon SNS 主题的 ARN。
对于标头和请求正文，如果已在设置过程中创建，请输入标头名称和请求正文 JSON。
选择测试。响应会出现在方法测试窗格中。如果响应成功，您将看到状态： 200。对于 Amazon SNS 示例设置，成功的响应会在响应正文中包含 MessageId。
有关更多信息，请参阅使用 API Gateway 控制台测试 REST API 方法。
部署 REST API。
使用任何首选工具测试 API。