API 整合請求的基本任務

整合請求是一項 HTTP 請求，由 API Gateway 提交到後端，隨用戶端提交的請求資料一併傳送，並在必要時轉換資料。HTTP 方法 (或動詞) 和整合請求的 URI 是由後端 (即整合端點) 提出。它們分別和方法請求的 HTTP 方法和 URI 可以相同或不同。

例如，當 Lambda 函數傳回從 Amazon S3 擷取的檔案時，您可以直覺地向用戶端公開此操作為 GET 方法請求，即使對應的整合請求需要使用 POST 請求呼叫 Lambda 函數。若為 HTTP 端點，有可能方法請求和對應的整合請求都使用相同的 HTTP 動詞。不過，這不是必要的。您可以整合以下方法請求：

GET /{var}?query=value
Host: api.domain.net

使用以下整合請求：

POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...

{
   path: "{var}'s value",
   type: "value"
}

身為 API 開發人員，您可以使用任何滿足您需求的方法請求 HTTP 動詞和 URI。但是，您必須遵循整合端點的需求。當方法請求資料和整合請求資料不同時，您可以提供方法請求資料到整合請求資料的映射，以調節差異。

在上述範例中，映射會將 {var} 方法請求的路徑變數 (query) 和查詢參數 (GET) 值轉譯為整合請求承載屬性 path 和 type 的值。其他可映射請求資料包括請求標頭和內文。「使用 API Gateway 主控台設定請求與回應資料映射」中會詳加說明。

設定 HTTP 或 HTTP 代理整合請求時，您要將後端 HTTP 端點 URL 指派為整合請求 URI 值。例如，在 PetStore API 中，取得寵物頁面的方法請求有以下整合請求 URI：

http://petstore-demo-endpoint.execute-api.com/petstore/pets

設定 Lambda 或 Lambda 代理整合時，您要將呼叫 Lambda 函數的 Amazon Resource Name (ARN) 指派為整合請求 URI 值。此 ARN 的格式如下：

arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations

arn:aws:apigateway:api-region:lambda:path/ 後面的部分，亦即 /2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations，是 Lambda Invoke 動作的 REST API URI 路徑。如果您使用 API Gateway 主控台設定 Lambda 整合，API Gateway 就會建立 ARN，並在提示您從區域選擇 lambda-function-name 後，將它指派給整合 URI。

設定另一項 AWS 服務動作的整合請求時，整合請求 URI 也是 ARN，類似與 Lambda Invoke 動作的整合。例如，與 Amazon S3 GetBucket 動作的整合，其整合請求 URI 是以下格式的 ARN：

arn:aws:apigateway:api-region:s3:path/{bucket}

整合請求 URI 是指定動作的路徑慣例，其中 {bucket} 是儲存貯體名稱的預留位置。或者，您可以依其名稱參考 AWS 服務動作。使用動作名稱，Amazon S3 GetBucket 動作的整合請求 URI 會變成如下：

arn:aws:apigateway:api-region:s3:action/GetBucket

使用動作型整合請求 URI，您必須在整合請求內文 ({bucket}) 中指定儲存貯體名稱 ({ Bucket: "{bucket}" })，遵循 GetBucket 動作的輸入格式。

若為 AWS 整合，您還必須設定憑證，讓 API Gateway 呼叫整合的動作。您可以針對 API Gateway 建立新的或選擇現有的 IAM 角色來呼叫動作，然後使用其 ARN 指定角色。以下所示為此 ARN 範例：

arn:aws:iam::account-id:role/iam-role-name

此 IAM 角色必須包含允許執行動作的政策。它還必須讓 API Gateway 宣告 (在角色的信任關係中) 為信任的實體以擔任該角色。這種許可能夠授予動作本身。它們稱為資源型許可。針對 Lambda 整合，您可以呼叫 Lambda 的 addPermission 動作來設定資源型許可，然後在 API Gateway 整合請求中將 credentials 設定為 null。

我們已討論過基本的整合設定。進階設定涉及將方法請求資料映射到整合請求資料。討論過整合回應的基本設定之後，我們會在「使用 API Gateway 主控台設定請求與回應資料映射」中涵蓋進階主題，同時論及傳送承載和處理內容編碼。