本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 Amazon API Gateway、Amazon SQS 和 AWS Fargate 非同步處理事件
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate"></a>

*Andrea Meroni、Mariem Kthiri、Nadim Majed、Alessandro Trisolini 和 Michael Wallner，Amazon Web Services*

## 總結
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-summary"></a>

[Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) 是一項全受管服務，開發人員可用來建立、發佈、維護、監控和保護任何規模APIs。它會處理涉及接受和處理多達數十萬個並行 API 呼叫的任務。

API Gateway 的一項重要服務配額是整合逾時。逾時是後端服務必須在 REST API 傳回錯誤之前傳回回應的最長時間。對於同步工作負載，通常可接受 29 秒的硬性限制。不過，該限制對想要將 API Gateway 與非同步工作負載搭配使用的開發人員來說是一項挑戰。

此模式顯示使用 API Gateway、Amazon Simple Queue Service (Amazon SQS) 和 非同步處理事件的範例架構 AWS Fargate。架構支援在沒有持續時間限制的情況下執行處理任務，並使用基本 REST API 做為界面。

[Projen](https://pypi.org/project/projen/) 用於設定本機開發環境 AWS 帳戶，並將範例架構與 [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/cli.html)、[Docker](https://docs.docker.com/get-docker/) 和 [Node.js](https://nodejs.org/en/download/) 結合部署至目標。Projen 會自動使用[預先遞交](https://pre-commit.com/)和用於程式碼品質保證、安全掃描和單元測試的工具來設定 [Python](https://www.python.org/downloads/) 虛擬環境。如需詳細資訊，請參閱[工具](#process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-tools)一節。

## 先決條件和限制
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-prereqs"></a>

**先決條件**
+ 作用中 AWS 帳戶
+ 工作站上安裝了下列工具：
  + [AWS Cloud Development Kit (AWS CDK) 工具組](https://docs.aws.amazon.com/cdk/v2/guide/cli.html) 2.85.0 版或更新版本
  + [Docker](https://docs.docker.com/get-docker/) 20.10.21 版或更新版本
  + [Node.js](https://nodejs.org/en/download/) 第 18 版或更新版本
  + [Projen](https://pypi.org/project/projen/) 0.71.111 版或更新版本
  + [Python](https://www.python.org/downloads/) 3.9.16 版或更新版本

**限制**
+ 並行任務限制為每分鐘 500 個任務，這是 Fargate 可以佈建的任務數量上限。

## Architecture
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-architecture"></a>

下圖顯示任務 API 與 `jobs` Amazon DynamoDB 資料表、事件處理 Fargate 服務和錯誤處理 AWS Lambda 函數的互動。事件會存放在 Amazon EventBridge 事件存檔中。

![\[結構圖與圖表後面的描述。\]](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/images/pattern-img/8a03149c-8f34-4593-84d5-accc1800a0a2/images/5e1071aa-4fbc-495c-bc22-8e62a32a136b.png)


典型的工作流程包括以下步驟：

1. 您可以驗證 AWS Identity and Access Management (IAM) 並取得安全登入資料。

1. 您可以將 HTTP `POST`請求傳送至`/jobs`任務 API 端點，在請求內文中指定任務參數。

1. 任務 API 是一種 API Gateway REST API，會傳回包含任務識別符的 HTTP 回應給您。

1. 任務 API 會傳送訊息至 SQS 佇列。

1. Fargate 從 SQS 佇列提取訊息、處理事件，然後將任務結果放入 `jobs` DynamoDB 資料表。

1. 您可以將 HTTP `GET`請求傳送至`/jobs/{jobId}`任務 API 端點，並將步驟 3 的任務識別符做為 `{jobId}`。

1. 任務 API 會查詢 `jobs` DynamoDB 資料表來擷取任務結果。

1. 任務 API 會傳回包含任務結果的 HTTP 回應。

1. 如果事件處理失敗，SQS 佇列會將事件傳送至無效字母佇列 (DLQ)。

1. EventBridge 事件會啟動錯誤處理函數。

1. 錯誤處理函數會將任務參數放在 `jobs` DynamoDB 資料表中。

1. 您可以透過傳送 HTTP `GET`請求至任務 API 端點來擷取`/jobs/{jobId}`任務參數。

1. 如果錯誤處理失敗，錯誤處理函數會將事件傳送至 EventBridge 封存。

   您可以使用 EventBridge 重播封存的事件。

## 工具
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-tools"></a>

**AWS 服務**
+ [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) 是一種軟體開發架構，可協助您在程式碼中定義和佈建 AWS 雲端 基礎設施。
+ [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html) 是一項全受管 NoSQL 資料庫服務，可提供快速、可預期且可擴展的效能。
+ [AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html) 可協助您執行容器，而無需管理伺服器或 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體。它與 Amazon Elastic Container Service (Amazon ECS) 搭配使用。
+ [Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) 是一種無伺服器事件匯流排服務，可協助您將應用程式與來自各種來源的即時資料連線。例如，Lambda 函數、使用 API 目的地的 HTTP 調用端點，或其他事件匯流排 AWS 帳戶。
+ [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) 是一項運算服務，可協助您執行程式碼，無需佈建或管理伺服器。它只會在需要時執行程式碼並自動擴展，因此您只需支付使用的運算時間。
+ [Amazon Simple Queue Service (Amazon SQS)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html) 提供安全、耐用且可用的託管佇列，可協助您整合和分離分散式軟體系統和元件。

**其他工具**
+ [autopep8](https://github.com/hhatto/autopep8) 會根據 Python Enhancement Proposal (PEP) 8 樣式指南自動格式化 Python 程式碼。
+ [Bandit](https://bandit.readthedocs.io/en/latest/) 會掃描 Python 程式碼來尋找常見的安全問題。
+ [Commitizen](https://commitizen-tools.github.io/commitizen/) 是 Git 遞交檢查程式和`CHANGELOG`產生器。
+ [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) 是 AWS CloudFormation linter
+ [Checkov](https://github.com/bridgecrewio/checkov) 是一種靜態程式碼分析工具，可將基礎設施檢查為程式碼 (IaC) 是否有安全性和合規設定錯誤。
+ [jq](https://stedolan.github.io/jq/download/) 是用於剖析 JSON 的命令列工具。
+ [Postman](https://www.postman.com/) 是 API 平台。
+ [預先遞交](https://pre-commit.com/)是 Git hooks 管理員。
+ [Projen](https://github.com/projen/projen) 是專案產生器。
+ [pytest](https://docs.pytest.org/en/7.2.x/index.html) 是一種 Python 架構，用於撰寫小型且可讀取的測試。

**程式碼儲存庫**

您可以在 GitHub [非同步處理與 API Gateway 和 SQS](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk) 儲存庫中找到此架構程式碼範例。

## 最佳實務
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-best-practices"></a>
+ 此範例架構不包含對已部署基礎設施的監控。如果您的使用案例需要監控，請評估新增 [CDK 監控建構](https://constructs.dev/packages/cdk-monitoring-constructs)或其他監控解決方案。
+ 此範例架構使用 [IAM 許可](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html)來控制對任務 API 的存取。有權擔任 的任何人`JobsAPIInvokeRole`都可以叫用任務 API。因此，存取控制機制是二進位。如果您的使用案例需要更複雜的授權模型，請使用不同的[存取控制機制](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-to-api.html)進行評估。
+ 當使用者傳送 HTTP `POST`請求到`/jobs`任務 API 端點時，輸入資料會在兩個不同的層級進行驗證：
  + API Gateway 負責第一個[請求驗證](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html)。
  + 事件處理函數會執行第二個請求。

    當使用者對`/jobs/{jobId}`任務 API 端點提出 HTTP `GET`請求時，不會執行驗證。如果您的使用案例需要額外的輸入驗證和更高的安全性，請使用 評估 [AWS WAF 來保護您的 API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-aws-waf.html)。

## 史詩
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-epics"></a>

### 設定環境
<a name="set-up-the-environment"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 複製儲存庫。 | 若要在本機複製儲存庫，請執行下列命令：<pre>git clone https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk.git</pre> | DevOps 工程師 | 
| 設定專案。 | 將目錄變更為儲存庫根目錄，並使用 [Projen](https://github.com/projen/projen) 設定 Python 虛擬環境和所有工具：<pre>cd asynchronous-event-processing-api-gateway-api-gateway-sqs-cdk<br />npx projen</pre> | DevOps 工程師 | 
| 安裝預先遞交掛鉤。 | 若要安裝預先遞交掛鉤，請執行下列動作：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate.html) | DevOps 工程師 | 

### 部署範例架構
<a name="deploy-the-example-architecture"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 引導 AWS CDK。 | 若要在 [AWS CDK](https://aws.amazon.com/cdk/)中引導 AWS 帳戶，請執行下列命令：<pre>AWS_PROFILE=$YOUR_AWS_PROFILE npx projen bootstrap</pre> | AWS DevOps | 
| 部署範例架構。 | 若要在 中部署範例架構 AWS 帳戶，請執行下列命令：<pre>AWS_PROFILE=$YOUR_AWS_PROFILE npx projen deploy</pre> | AWS DevOps | 

### 測試架構
<a name="test-the-architecture"></a>


| 任務 | Description | 所需的技能 | 
| --- | --- | --- | 
| 安裝測試先決條件。 | 在工作站上安裝 [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)、[Postman](https://www.postman.com/downloads/) 和 [jq](https://jqlang.github.io/jq/)。建議使用 [Postman](https://www.postman.com/downloads/) 測試此範例架構，但不強制。如果您選擇替代 API 測試工具，請確定它支援 [AWS Signature 第 4 版身分驗證](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)，並參考可透過[匯出 REST API 檢查的公開 API ](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html)端點。 | DevOps 工程師 | 
| 擔任 `JobsAPIInvokeRole`。 | [假設](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/assume-role.html)`JobsAPIInvokeRole`從 `deploy`命令列印為輸出的 ：<pre>CREDENTIALS=$(AWS_PROFILE=$<YOUR_AWS_PROFILE> aws sts assume-role \<br />--no-cli-pager \<br />--role-arn $<JOBS_API_INVOKE_ROLE_ARN> \<br />--role-session-name JobsAPIInvoke)<br />export AWS_ACCESS_KEY_ID=$(cat $CREDENTIALS | jq ‘.Credentials’’.AccessKeyId’)<br />export AWS_SECRET_ACCESS_KEY=$(cat $CREDENTIALS | jq ‘.Credentials’’.SecretAccessKey’)<br />export AWS_SESSION_TOKEN==$(cat $CREDENTIALS | jq ‘.Credentials’’.SessionToken’)</pre> | AWS DevOps | 
| 設定 Postman。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate.html) | AWS DevOps | 
| 測試範例架構。 | 若要測試範例架構，請將請求傳送至任務 API。如需詳細資訊，請參閱 [Postman 文件](https://learning.postman.com/docs/getting-started/first-steps/sending-the-first-request/#send-an-api-request)。 | DevOps 工程師 | 

## 疑難排解
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-troubleshooting"></a>


| 問題 | 解決方案 | 
| --- | --- | 
| 範例架構的銷毀和後續重新部署失敗，因為 [Amazon CloudWatch Logs 日誌群組](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html)`/aws/apigateway/JobsAPIAccessLogs`已存在。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate.html) | 
| 範例架構的銷毀和後續重新部署失敗，因為 [CloudWatch Logs 日誌群組](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html)`/aws/ecs/EventProcessingServiceLogs`已存在。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate.html) | 

## 相關資源
<a name="process-events-asynchronously-with-amazon-api-gateway-amazon-sqs-and-aws-fargate-resources"></a>
+ [API Gateway 映射範本和存取記錄變數參考](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html)
+ [如何將 API Gateway REST API 與 Amazon SQS 整合並解決常見錯誤？](https://aws.amazon.com/premiumsupport/knowledge-center/api-gateway-rest-api-sqs-errors/)