Get Hands-on with Amazon EKS - Workshop Event Series

Whether you're taking your first steps with Kubernetes or you're an experienced practitioner looking to sharpen your skills, our Amazon EKS workshop series delivers practical, real-world experience that moves you forward. Learn directly from AWS solutions architects and EKS specialists through hands-on sessions designed to build your confidence with Kubernetes. Register now and start building with Amazon EKS!

如何使用 API Gateway 作為另一個 AWS 服務的代理？

6 分的閱讀內容

我想要使用 Amazon API Gateway 作為另一個 AWS 服務的代理，並將其他服務與 API Gateway 整合。

解決方法

**注意：**如果您在執行 AWS Command Line Interface (AWS CLI) 命令時收到錯誤，請參閱AWS CLI 錯誤疑難排解。此外，請確認您使用的是最新的 AWS CLI 版本。

AWS 服務 API 是 REST API，您可以向其發送 HTTPS 請求。若要將另一個服務與 API Gateway 整合，請從 API Gateway 建立一個指向該服務 API 的 HTTPS 請求。使用此方法時，所有請求參數都會正確對應。

此解決方法說明了當您將 Amazon Simple Notification Service (Amazon SNS) 的發佈 API 與 API Gateway 整合時的範例設定。請使用以下範例作為您在將 API Gateway 與其他服務整合時可採用的方法概要。

設定必要的工具與資源

設定您的環境，並建立使用案例所需的所有 AWS 資源。對於 Amazon SNS 範例設定，請完成以下步驟：

安裝 AWS CLI。
建立 Amazon SNS 主題。記下主題的 Amazon Resource Name (ARN)。
建立主題的訂閱。
開啟 AWS Identity and Access Management (IAM) console (AWS Identity and Access Management (IAM) 主控台)，然後建立 AWS 服務 Proxy 執行角色。對於 Amazon SNS 範例設定，允許執行 sns:Publish 動作。如需更多資訊，請參閱在 API Gateway 中控制與管理對 REST API 的存取。
若要建立 API Gateway REST API，請使用測試資源。如需更多資訊與範例，請參閱 Amazon API Gateway 教學課程和工作坊。

若要匯入 REST API，請使用以下 OpenAPI 2.0 (Swagger) 定義範例：

{  "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:your-region:sns:action/Publish",
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.header.Content-Type": "'application/x-www-form-urlencoded'"
          },
          "requestTemplates": {
            "application/json": {
              "Fn::Sub": "Action=Publish&TopicArn=$util.urlEncode('${**YOUR-TOPIC-ARN**}')&Message=$util.urlEncode($input.body)##"
            }
          },
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws"
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  }
}

**注意：**將 arn:aws:iam::account-id:role/apigateway-sns-role 替換為您的 IAM 角色 ARN，並將 YOUR-TOPIC-ARN 替換為您的 SNS 主題 ARN。

上述選項會預先為 Amazon SNS 範例設定設定了相關設定。若要建立您的 REST API，請將 your-region 替換為您的 AWS 區域。如需更多資訊，請參閱 Swagger 網站上的什麼是 OpenAPI？。

取得 HTTPS 請求範例

來自您整合的服務 API 的 HTTPS 請求範例，有助於您在 API Gateway 中對應請求參數。

對於 Amazon SNS 的發佈 API，請參閱該服務的 API 參考文件中的請求範例。
若要取得 HTTPS 請求，請執行以下範例請求：

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 呼叫產生範例。使用 AWS CLI 呼叫服務 API，然後分析輸出。判斷與您整合的服務 API 對應的 AWS CLI 命令，然後使用 —debug 選項執行測試請求。

若要從 API 呼叫產生範例，請執行以下發佈命令：

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

**注意：**將 arn:aws:sns:us-east-1:123456789012:test 替換為您的 Amazon SNS 主題 ARN。

範例輸出：

2018-11-22 11:56:39,647 - MainThread - botocore.client - DEBUG - Registering retry handlers for service: sns2018-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

輸出包含 HTTPS 請求、傳遞的標頭，且請求為 POST HTTP 方法。

為您的 API Gateway API 建立方法

請完成下列步驟：

開啟 API Gateway console (API Gateway 主控台)。
在導覽窗格中，選擇 APIs，然後選擇您的 API 名稱。
在 Resources (資源) 窗格中，請選擇一個資源。對於 Amazon SNS 範例設定，請選擇您建立的測試資源。
選擇 Create method (建立方法)。
在新視窗中：
選擇範例 HTTPS 請求中服務 API 所使用的方法。
對於 Amazon SNS 範例設定，請選擇 POST。
對於 Integration type (整合類型)，請選擇 AWS Service (AWS 服務)。
對於 AWS Region (AWS 區域)，請選擇與您整合的服務 API 相關資源的 AWS 區域。
對於 Amazon SNS 範例設定，請選擇您的 SNS 主題所在的區域。
對於 AWS Service (AWS 服務)，請選擇您要與 API Gateway 整合的服務。例如，使用簡單通知服務 (SNS)。
對於 AWS Subdomain (AWS 子網域)，輸入 AWS 服務使用的子網域。請查看服務文件以確認子網域是否可用。
對於 Amazon SNS 範例設定，請將此欄位留空。
對於 HTTP method (HTTP 方法)，請選擇對應於您整合的 AWS 服務 API 的方法。
對於 Amazon SNS 範例設定，請選擇 POST。
對於 Action type (動作類型)，若您整合的服務 API 是支援的動作，則選擇 Use action name (使用動作名稱)。請查看服務 API 參考以取得支援動作清單。
對於 Amazon SNS，請參閱動作。
對於 Action (動作)，輸入服務 API 的名稱。對於 Amazon SNS 範例設定，輸入 Publish (發佈)。
-或-
對於 Action type (動作類型)，若 AWS 服務 API 需要在請求中提供資源路徑，則選擇 Use path override (使用路徑覆寫)。例如，對於 Amazon Polly 的 ListLexicons API，為 Path override (optional) (路徑覆寫 (選用))輸入 /v1/lexicons。
對於 Execution role (執行角色)，輸入您建立的 IAM 角色 ARN。
選擇 Create method (建立方法)。

為方法請求建立參數

判斷您整合的服務 API 所需的必填與選用請求參數。若要識別這些參數，請參考先前取得的 HTTPS 請求範例，或參閱服務 API 的 API 參考。例如，請參閱 Publish (發佈)。

請完成下列步驟：

開啟 API Gateway console (API Gateway 主控台)。
在導覽窗格中，選擇 APIs，然後選擇您的 API 名稱。
在 Resources (資源) 頁面中，選擇您的 Method type (方法類型)。
選擇 Method request (方法請求) 索引標籤，然後選擇 Edit (編輯)。
選擇 Request validator (請求驗證器) 下拉式清單，並選擇 Validate body, string parameters, and headers (驗證主體、字串參數及標頭)。
展開 URL query string parameters (URL 查詢字串參數)，然後選擇 Add query string (新增查詢字串)。
對於 Name (名稱)，輸入您整合的服務 API 的請求參數名稱。對於 Amazon SNS 範例設定，建立一個名為 TopicArn 的參數，另一個參數名為 Message。
(選用) 若此參數為必填，請在 Required (必填) 下勾選核取方塊。
選擇 Save (儲存)。

如需更多資訊，請參閱使用 API Gateway 主控台設定方法。

**注意：**對於某些服務 API，您必須在整合請求中除了必填參數之外，還要傳送必要的標頭與主體。您可以在 Integration request (整合請求) 窗格中，於 HTTP Request Headers (HTTP 請求標頭) 和 Request body (請求主體) 建立標頭與主體。

例如，若您整合 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 來對應請求主體。(將 JSONPath_EXPRESSION 替換為請求主體中 JSON 欄位的 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 console (API Gateway 主控台)。
在導覽窗格中，選擇 APIs，然後選擇您的 API 名稱。
在 Resources (資源) 頁面中，選擇您的 Method type (方法類型)。
選擇 Integration request (整合請求) 索引標籤，然後選擇 Edit (編輯)。
展開 URL query string parameters (URL 查詢字串參數)，然後選擇 Add query string parameter (新增查詢字串參數)。
對於 Name (名稱)，輸入您整合的服務 API 的請求參數名稱。
**注意：**名稱區分大小寫，且必須完全符合服務 API 的要求。
對於 Mapped from (對應來源)，請輸入 method.request.querystring.param_name。將 param_name 替換為您為方法請求建立的對應參數名稱。例如，method.request.querystring.TopicArn。
為整合請求建立與方法請求每個參數對應的參數。
選擇 Save (儲存)。

**注意：**若您已為方法請求建立必填標頭與主體，則將它們對應到整合請求。若要為方法請求建立必填標頭與主體，請在 Integration request (整合請求) 窗格中，於 HTTP Headers (HTTP 標頭) 和 Mapping templates (對應範本) 下操作。

如需更多資訊，請參閱使用 API Gateway 主控台設定 API 整合請求。

(選用) 檢查您的整合組態

若要驗證整合設定是否正確，請執行以下 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 上執行以下 Amazon SNS 整合：

"requestParameters": {       "integration.request.header.Content-Type": "'application/x-www-form-urlencoded'"
},
"requestTemplates" : {
    "application/json" : "Action=Publish&TopicArn=$util.urlEncode('<ourTopicArn>')&Message=$util.urlEncode($input.body)"
}

**注意：**Amazon SNS 支援的最大標頭大小為 16KB。在將請求傳送到整合之前，請使用請求對應範本將傳入的 HTTP 請求轉換為不同格式。因為 Amazon SNS 主題 ARN 已硬式編碼在對應範本中，用戶端在請求中不會傳遞 SNS 主題 ARN。

若要檢查您的整合組態，請完成以下步驟：

開啟 API Gateway console (API Gateway 主控台)。
在導覽窗格中，選擇 APIs，然後選擇您的 API 名稱。
在 Resources (資源) 頁面中，選擇您的 Method type (方法類型)，然後選擇 Test (測試) 索引標籤。
在 Test method (測試方法) 頁面，完成以下步驟：
對於查詢字串，輸入包含請求參數及其值的查詢字串。
對於 Amazon SNS 整合，輸入 TopicArn= arn:aws:sns:us-east-1:123456789012:test&Message="Hello"。將 arn:aws:sns:us-east-1:123456789012:test 替換為您的 Amazon SNS 主題 ARN。
對於使用對應範本的 Amazon SNS 整合，將訊息負載 JSON 資料輸入到 Request body (請求主體)，然後選擇 Test (測試)。
**注意：**負載內容會依您的組態而有所不同。
當您收到成功回應後，部署您的 REST API。