

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 将 Amazon API Gateway 与亚马逊 SQS 集成以处理异步 REST APIs
<a name="integrate-amazon-api-gateway-with-amazon-sqs-to-handle-asynchronous-rest-apis"></a>

*Natalia Colantonio Favero 和 Gustavo Martim，Amazon Web Services*

## Summary
<a name="integrate-amazon-api-gateway-with-amazon-sqs-to-handle-asynchronous-rest-apis-summary"></a>

部署 REST 时 APIs，有时需要公开客户端应用程序可以发布的消息队列。例如，您可能遇到第三方延迟 APIs 和响应延迟的问题，或者您可能希望避免数据库查询的响应时间，或者避免在存在大量并发请求时扩展服务器 APIs。在这些情况下，发布到队列的客户端应用程序只需要知道 API 已收到数据，而不是收到数据后会发生什么。

此模式使用 [Amazon API Gateway](https://aws.amazon.com/api-gateway/) 向 [Amazon Simple Queue Service（Amazon SQS）](https://aws.amazon.com/sqs/)发送消息，进而创建 REST API 端点。它在两个服务之间创建了 easy-to-implement集成，从而避免了直接访问 SQS 队列。

## 先决条件和限制
<a name="integrate-amazon-api-gateway-with-amazon-sqs-to-handle-asynchronous-rest-apis-prereqs"></a>
+ 一个[活跃的 AWS 账户](https://portal.aws.amazon.com/billing/signup/iam)

## 架构
<a name="integrate-amazon-api-gateway-with-amazon-sqs-to-handle-asynchronous-rest-apis-architecture"></a>

![用于将 API Gateway 与 Amazon SQS 集成的架构](http://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/patterns/images/pattern-img/70984dee-e49f-4446-9d52-49ce826c3909/images/737ba0b2-da8f-4478-8c54-0a4835fd69f9.png)


该图阐释了以下步骤：

1. 使用工具（例如 Postman、其他 API、其他技术）请求 POST REST API 端点。

1. API Gateway 将请求正文中收到的消息发布到队列中。

1. Amazon SQS 收到消息并向 API Gateway 发送答案，并附上成功或失败代码。

## 工具
<a name="integrate-amazon-api-gateway-with-amazon-sqs-to-handle-asynchronous-rest-apis-tools"></a>
+ [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) 可帮助您创建、发布、维护、监控和保护任何规模的 RES WebSocket APIs T、HTTP。
+ [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) 通过控制谁经过身份验证并有权使用 AWS 资源，从而帮助您安全地管理对资源的访问权限。
+ [Amazon Simple Queue Service（Amazon SQS）](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html)提供了一个安全、持久且可用的托管队列，它可帮助您集成和分离分布式软件系统与组件。  

## 操作说明
<a name="integrate-amazon-api-gateway-with-amazon-sqs-to-handle-asynchronous-rest-apis-epics"></a>

### 创建 SQS 队列。
<a name="create-an-sqs-queue"></a>


| Task | 说明 | 所需技能 | 
| --- | --- | --- | 
| 创建队列。 | 要创建接收来自 REST API 的消息的 SQS 队列，请执行以下操作：1. 登录到您的 [AWS 账户](https://portal.aws.amazon.com/billing/signup/iam)。<br />2. 打开 Amazon SQS 控制台，网址为。[https://console.aws.amazon.com/sqs/](https://console.aws.amazon.com/sqs/)<br />3. 选择**创建队列**。<br />4. 在 “**创建队列**” 页面上， AWS 区域 从 “**区域**” 下拉列表中选择正确的队列。<br />5. 对于**类型**，保留默认设置（**标准**）。<br />6. 输入队列的**名称**。<br />7. 将所有其他设置保留为默认值。<br />8. 选择**创建队列**。 | 应用程序开发人员 | 

### 提供对 Amazon SQS 的访问权限
<a name="provide-access-to-sqs"></a>


| Task | 说明 | 所需技能 | 
| --- | --- | --- | 
| 创建 IAM 角色。 | 此 IAM 角色授予 API Gateway 对 Amazon SQS 的完全访问权限。1. 使用 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。<br />2. 在导航窗格中，选择 **Roles**（角色）和 **Create role**（创建角色）。<br />3. 对于 **Trusted entity type**（可信实体类型），选择 **AWS 服务**。<br />4. 对于**使用案例**，从下拉列表中选择 **API Gateway**，然后选择**下一步**，**下一步**。<br />5. **在角色名称**中，输入 **AWSGatewayRoleForSQS** 和可选描述，然后选择**创建角色**。<br />6. 在 “**角色**” 窗格中，搜索 S **AWSGatewayRoleForQS**，然后选中其复选框。<br />7. 在**权限策略**部分中，选择**添加权限**、**附加策略**。<br />8. 搜索 **Amazon A SQSFull cces** s 并将其选中。<br />9. 选择**添加权限**。<br />10. 在 **AWSGatewayRoleForSQS** 的 “**摘要**” 部分，复制亚马逊资源编号 (ARN)。您将在后面的步骤中用到此 ID。 | AWS 开发人员、AWS 管理人 | 

### 创建 REST API
<a name="create-a-rest-api"></a>


| Task | 说明 | 所需技能 | 
| --- | --- | --- | 
| 创建 REST API。 | 这是 HTTP 请求发送到的 REST API。1. 打开 API Gateway 控制台，网址为[https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/)。<br />2. 在 **REST API** 部分中，选择**构建**。<br />3. 在 **API 名称**中，输入您的 API 的名称和可选描述，保留所有其他默认设置，然后选择**创建 API**。 | 应用程序开发人员 | 
| 将 API Gateway 连接到 Amazon SQS。 | 此步骤允许消息从 HTTP 请求正文内部流向 Amazon SQS。1. 在 [API Gateway 控制台](https://console.aws.amazon.com/apigateway/)上，选择您创建的 API。<br />2. 在**资源**页面的**方法**部分，选择**创建方法**。<br />3. 对于**方法类型**，选择 **POST**。 <br />4. 对于**集成类型**， 选择 **AWS 服务**。<br />5. 对于 **AWS 区域**，选择要在其中创建 SQS 的区域。<br />6. 对于 **AWS 服务**，选择 **Simple Queue Service（SQS）**。<br />7. 对于 **HTTP 方法**，选择 POST。<br />8. 对于**操作类型**，选择**使用路径覆盖**。<br />9. 对于**路径覆盖**，输入 **<AWS account ID>/<name of SQS queue>**。<br />10. 对于**执行角色**，请输入您之前创建的角色的 ARN。<br />11. 选择**创建方法**。 | 应用程序开发人员 | 

### 测试 REST API
<a name="test-the-rest-api"></a>


| Task | 说明 | 所需技能 | 
| --- | --- | --- | 
| 测试 REST API。 | 运行测试以检查是否缺少配置：1. 在 [API Gateway 控制台](https://console.aws.amazon.com/apigateway/)上，选择您创建的 REST API。<br />2. 在**资源**窗格中，选择 **POST **方法。<br />3. 选择**测试**选项卡。（如果未显示选项卡，则请使用右箭头。）<br />4. 对于**请求正文**，粘贴以下 JSON 代码：<pre>{<br />     "message": "lorem ipsum"<br />}</pre><br />5. 选择**测试**。<br />您收到类似于以下内容的错误：<pre><UnknownOperationException/></pre> | 应用程序开发人员 | 
| 更改 API 集成，将请求正确转发给 Amazon SQS。 | 完成配置以修复集成错误：1. 在 [API Gateway 控制台](https://console.aws.amazon.com/apigateway/)上，选择您创建的 API，然后选择 **POST**。<br />2. **方法执行**部分显示了 API Gateway 和 Amazon SQS 之间的直观映射。从此部分中，选择**集成请求**，然后选择**编辑**。<br />3. 展开 **HTTP 标头**部分，然后选择**添加请求标头**参数。在**名称**中，指定**内容类型**。对于 “**映射来源**”，输入 **“应用程序/ x-www-form-urlencoded**”。确保包含单引号内。选中**缓存**复选框。<br />4. 展开**映射模板**部分。选择 **Add mapping template (添加映射模板)**。对于**内容类型**，输入 **application/json**。对于**模板正文**，请粘贴此代码：<pre>Action=SendMessage&MessageBody=$input.body</pre>选择**保存**。 | 应用程序开发人员 | 
| 在 Amazon SQS 中测试并验证消息。 | 运行测试，以验证测试是否成功完成：1. 在 [API Gateway 控制台](https://console.aws.amazon.com/apigateway/)上，选择您创建的 REST API。<br />2. 在**资源**窗格中，选择 **POST **方法。<br />3. 选择**测试**选项卡。（如果未显示选项卡，则请使用右箭头。）<br />4. 对于**请求正文**，粘贴以下 JSON 代码：<pre>{<br />     "message": "lorem ipsum"<br />}</pre><br />5. 选择**测试**。<br />6. 打开 [Amazon SQS 控制台](https://console.aws.amazon.com/sqs/)。<br />7. 在导航窗格中，选择**队列**，然后选择您的队列。<br />8. 选择**发送和接收消息**。<br />9. 选择**轮询消息**。<br />10. 选择**消息**。应显示以下输出。<pre>Body { "message": "lorem ipsum" }</pre> | 应用程序开发人员 | 
| 使用特殊字符测试 API Gateway。 | 运行包含消息中不可接受的特殊字符（例如 &）的测试：1. 在 [API Gateway 控制台](https://console.aws.amazon.com/apigateway/)中选择您的 API。<br />2. 使用以下 JSON 代码重复前面步骤中的测试：<pre>{<br />     "message": "lorem ipsum &"<br />}</pre><br />3. 选择**测试**。<br />否则，您将收到以下错误：<pre>{<br />  "Error": {<br />    "Code": "AccessDenied",<br />    "Message": "Access to the resource https://sqs.us-east-2.amazonaws.com/976166761794/Apg2 is denied.",<br />    "Type": "Sender"<br />  },<br />  "RequestId": "e83c9c67-bcf6-5e9a-91e9-c737094b17ab"<br />}</pre><br />这是因为默认情况下，邮件正文中不支持特殊字符。在下一步中，您将配置 API Gateway 以支持特殊字符。有关内容类型转换的更多信息，请参阅 [API Gateway 文档](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings-workflow.html)。 | 应用程序开发人员 | 
| 更改 API 配置以支持特殊字符。 | 调整配置，以接受消息中的特殊字符：1. 在 [API Gateway 控制台](https://console.aws.amazon.com/apigateway)上，选择您创建的 API，然后选择 **POST**。<br />2. 选择**集成请求**，然后选择**编辑**。<br />3. 将**内容处理**更改为**转换为文本**。<br />4. 在**映射模板**部分中：对于**内容类型**，输入 **application/json**。对于**模板正文**，请指定：<pre>Action=SendMessage&MessageBody=$util.urlEncode($input.body)</pre>选择**保存**。<br />5. 选择**测试**选项卡。<br />6. 在**请求正文**中，输入之前的 JSON 代码：<pre>{<br />     " message": "lorem ipsum &" }</pre><br />7. 选择**测试**。<br />8. 打开 [Amazon SQS 控制台](https://console.aws.amazon.com/sqs/)。<br />9. 选择您的队列，然后像之前一样依次选择**发送和接收消息**、**轮询消息**、**消息**。<br />新消息应包含特殊字符。 | 应用程序开发人员 | 

### 部署 REST API
<a name="deploy-the-rest-api"></a>


| Task | 说明 | 所需技能 | 
| --- | --- | --- | 
| 部署 API。 |  <br />要部署 REST API：1. 打开 [API Gateway 控制台](https://console.aws.amazon.com/apigateway/)。<br />2. 选择 API。<br />3. 选择**部署 API**。有关此步骤的详情，请参阅 [API Gateway 文档](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-deploy-api-with-console.html)。 | 应用程序开发人员 | 
| 使用外部工具进行测试。 | 使用外部工具运行测试，以确认消息已成功接收：1. 打开诸如 Postman、Insomnia 或 cURL 之类的工具。<br />2. 运行您的 API。<br />3. 打开 [Amazon SQS 控制台](https://console.aws.amazon.com/sqs/)。<br />4. 选择您的队列。<br />5. 加载消息以查看新消息。 | 应用程序开发人员 | 

### 清除
<a name="clean-up"></a>


| Task | 说明 | 所需技能 | 
| --- | --- | --- | 
| 删除 API。 | 在 [API Gateway 控制台](https://console.aws.amazon.com/apigateway/)上，选择您创建的 API，然后选择 **删除**。 | 应用程序开发人员 | 
| 删除 IAM 角色。 | 在 [IAM 控制台](https://console.aws.amazon.com/iam/)的**角色**窗格中，选择 **AWSGatewayRoleForSQS**，然后选择**删除**。 | 应用程序开发人员 | 
| 删除 SQS 队列。 | 在 [Amazon SQS 控制台](https://console.aws.amazon.com/sqs/)的**队列**窗格中，选择您创建的 SQS 队列，然后选择**删除**。 | 应用程序开发人员 | 

## 相关资源
<a name="integrate-amazon-api-gateway-with-amazon-sqs-to-handle-asynchronous-rest-apis-resources"></a>
+ [SQS-SendMessage](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-aws-services-reference.html#SQS-SendMessage)（API Gateway 文档）
+ [API Gateway 中的内容类型转换](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings-workflow.html)（API Gateway 文档）
+ [$util 变量](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#util-template-reference)（API Gateway 文档）
+ [如何将 API Gateway REST API 与亚马逊 SQS 集成，并解决常见错误？](https://repost.aws/knowledge-center/api-gateway-rest-api-sqs-errors) （re AWS : post 文章）