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

# API 整合請求的基本任務
<a name="integration-request-basic-setup"></a>

 整合請求是一項 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 中 REST API 的參數映射](rest-api-parameter-mapping.md)」中會詳加說明。

設定 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](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) 動作的 REST API URI 路徑。如果您使用 API Gateway 主控台設定 Lambda 整合，API Gateway 就會建立 ARN，並在提示您從區域選擇 `lambda-function-name` 後，將它指派給整合 URI。

使用另一個 AWS 服務動作設定整合請求時，整合請求 URI 也是 ARN，類似於與 Lambda `Invoke`動作的整合。例如，與 Amazon S3 [GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) 動作的整合，其整合請求 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 整合，您還必須設定[登入](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#credentials)資料，以允許 API Gateway 呼叫整合的動作。您可以針對 API Gateway 建立新的或選擇現有的 IAM 角色來呼叫動作，然後使用其 ARN 指定角色。以下所示為此 ARN 範例：

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

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

我們已討論過基本的整合設定。進階設定涉及將方法請求資料映射到整合請求資料。如需詳細資訊，請參閱[API Gateway 中用於 REST API 的資料轉換](rest-api-data-transformations.md)。