# 选择 HTTP 集成教程
<a name="getting-started-http-integrations"></a>

 要使用 HTTP 集成构建 API，您可以使用 HTTP 代理集成或 HTTP 自定义集成。

在 HTTP 代理集成中，您只需根据后端要求设置 HTTP 方法和 HTTP 端点 URI。我们建议您尽可能使用 HTTP 代理集成，以利用简化版的 API 设置过程。

如果您需要为后端转换客户端请求数据或为客户端转换后端响应数据，则您可能要使用 HTTP 自定义集成。

**Topics**
+ [教程：利用 HTTP 代理集成创建 REST API](api-gateway-create-api-as-simple-proxy-for-http.md)
+ [教程：使用 HTTP 非代理集成创建 REST API](api-gateway-create-api-step-by-step.md)

# 教程：利用 HTTP 代理集成创建 REST API
<a name="api-gateway-create-api-as-simple-proxy-for-http"></a>

HTTP 代理集成是一个简单、强大的多功能机制，用于构建 API，它允许 Web 应用程序通过简单设置单个 API 方法即可访问集成的 HTTP 终端节点的多个资源或特征，例如整个网站。在 HTTP 代理集成中，API Gateway 会将客户端提交的方法请求传递至后端。传递的请求数据包括请求标头、查询字符串参数、URL 路径变量和负载。后端 HTTP 终端节点或 Web 服务器会对传入请求数据进行解析，以确定要返回的响应。在设置 API 方法后，HTTP 代理集成使得客户端和后端可以直接交互，而不受 API Gateway 的任何干预。不受支持的字符等已知问题除外，[Amazon API Gateway 重要说明](api-gateway-known-issues.md) 中列出了此类问题。

借助无所不包的代理资源 `{proxy+}` 和用于 HTTP 方法的“捕获全部”`ANY` 动词，您可以使用 HTTP 代理集成来创建单个 API 方法的 API。该方法会公开网站的一整套可公开访问的 HTTP 资源和操作。当后端 Web 服务器打开更多资源以供公开访问时，客户端可以通过相同的 API 设置来使用这些新资源。为了实现此功能，网站开发人员必须向客户端开发人员讲清楚什么是新资源以及适用于每个新资源的操作是什么。



作为快速介绍，以下教程演示了 HTTP 代理集成。在本教程中，我们将使用 API Gateway 控制台创建一个 API，以通过通用代理资源 `{proxy+}` 与 PetStore 网站集成，还将创建 `ANY` 的 HTTP 方法占位符。

**Topics**
+ [通过 API Gateway 控制台使用 HTTP 代理集成创建 API](#api-gateway-create-api-as-simple-proxy-for-http-build)
+ [使用 HTTP 代理集成测试 API](#api-gateway-create-api-as-simple-proxy-for-http-test)

## 通过 API Gateway 控制台使用 HTTP 代理集成创建 API
<a name="api-gateway-create-api-as-simple-proxy-for-http-build"></a>

 以下过程将指导您完成在 API Gateway 控制台中使用代理资源创建并测试用于 HTTP 后端的 API 的步骤。HTTP 后端是来自 `PetStore` 的 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` 网站 ([教程：使用 HTTP 非代理集成创建 REST API](api-gateway-create-api-step-by-step.md))，其中的屏幕截图用作直观辅助手段来阐释 API Gateway UI 元素。如果您是首次使用 API Gateway 控制台来创建 API，可能需要先按照该部分中的说明操作。

**创建 API**

1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 如果您是第一次使用 API Gateway，您会看到一个介绍服务特征的页面。在 **REST API** 下，选择**生成**。当**创建示例 API** 弹出框出现时，选择**确定**。

   如果这不是您首次使用 API Gateway，请选择**创建 API**。在 **REST API** 下，选择**生成**。

1.  对于 **API 名称**，请输入 **HTTPProxyAPI**。

1. （可选）对于**描述**，输入描述。

1. 将 **API 端点类型**设置保留为**区域**。

1. 为 **IP 地址类型**选择 **IPv4**。

1. 选择**创建 API**。

在此步骤中，您将创建一个 `{proxy+}` 代理资源路径。这是 `http://petstore-demo-endpoint.execute-api.com/` 下任意后端端点的占位符。例如，它可以是 `petstore`、`petstore/pets` 和 `petstore/pets/{petId}`。API Gateway 可在您创建 `{proxy+}` 资源时创建 `ANY` 方法，并在运行时用作任意支持的 HTTP 动词的占位符。

**创建 **/\$1proxy\$1\$1** 资源**

1. 选择 API。

1. 在主导航窗格中，选择**资源**。

1. 选择**创建资源**。

1. 开启**代理资源**。

1. 将**资源路径**保持为 `/`。

1. 对于**资源名称**，输入 **\$1proxy\$1\$1**。

1. 将 **CORS（跨源资源共享）**保持为关闭状态。

1. 选择**创建资源**。  
![\[创建子资源。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/api-gateway-simple-proxy-create-proxy-resource-new-console.png)

在此步骤中，您将使用代理集成将 `ANY` 方法与后端 HTTP 端点集成。在代理集成中，API Gateway 会将客户端提交的方法请求传递至后端，而不进行任何干预。

**创建 `ANY` 方法**

1. 选择 **/\$1proxy\$1\$1** 资源。

1. 选择 **ANY** 方法。

1. 在警告符号下，选择**编辑集成**。您无法部署具有方法但没有集成的 API。

1. 对于**集成类型**，选择 **HTTP**。

1. 打开 **HTTP 代理集成**。

1. 对于 **HTTP 方法**，选择 **ANY**。

1. 对于**端点 URL**，输入 **http://petstore-demo-endpoint.execute-api.com/\$1proxy\$1**。

1. 选择**保存**。

## 使用 HTTP 代理集成测试 API
<a name="api-gateway-create-api-as-simple-proxy-for-http-test"></a>

 特定客户端请求是否成功取决于以下因素：
+  后端是否提供了相应的后端终端节点，如果已提供，是否授予了所需的访问权限。
+ 客户端是否提供了正确输入。

例如，此处使用的 PetStore API 不会公开 `/petstore` 资源。因此，您会收到 `404 Resource Not Found` 响应，其中包含错误消息 `Cannot GET /petstore`。

此外，客户端必须能够处理后端的输出格式，以便正确解析结果。API Gateway 不会通过调解来促进客户端与后端之间的交互。

**通过代理资源使用 HTTP 代理集成测试与 PetStore 网站集成的 API**

1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。

1. 对于**方法类型**，选择 `GET`。

1. 对于**路径**，在**代理**下输入 **petstore/pets**。

1. 对于**查询字符串**，输入 **type=fish**。

1. 选择**测试**。

     
![\[使用测试功能来测试方法。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/api-gateway-simple-proxy-petstore-call-proxy-resource-new-console.png)

   由于后端网站支持 `GET /petstore/pets?type=fish` 请求，它将返回类似于以下内容的成功响应：

   ```
   [
     {
       "id": 1,
       "type": "fish",
       "price": 249.99
     },
     {
       "id": 2,
       "type": "fish",
       "price": 124.99
     },
     {
       "id": 3,
       "type": "fish",
       "price": 0.99
     }
   ]
   ```

   如果尝试调用 `GET /petstore`，您将会收到 `404` 响应，并显示一条错误消息：`Cannot GET /petstore`。这是因为后端不支持指定的操作。如果调用 `GET /petstore/pets/1`，您会收到包含以下负载的 `200 OK` 响应，因为 PetStore 网站支持该请求。

   ```
   {
     "id": 1,
     "type": "dog",
     "price": 249.99
   }
   ```

您也可以使用浏览器来测试您的 API。部署您的 API 并将其关联到阶段以创建 API 的调用 URL。

**部署 API**

1. 选择**部署 API**。

1. 对于**阶段**，选择**新建阶段**。

1. 对于**阶段名称**，输入 **test**。

1. （可选）对于**描述**，输入描述。

1. 选择**部署**。

现在，客户端可以调用您的 API。

**调用 API**

1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 选择 API。

1. 在主导航窗格中，选择**阶段**。

1. 在**阶段详细信息**下，选择复制图标以复制您 API 的调用 URL。

   在 Web 浏览器中输入 API 的调用 URL。

   完整的 URL 应类似于 `https://abcdef123.execute-api.us-east-2.amazonaws.com/test/petstore/pets?type=fish`。

   您的浏览器向 API 发送 `GET` 请求。

1. 结果应与您在 API Gateway 控制台中使用**测试**功能时返回的结果相同。

# 教程：使用 HTTP 非代理集成创建 REST API
<a name="api-gateway-create-api-step-by-step"></a>

 在本教程中，您将使用 Amazon API Gateway 控制台从头开始创建 API。您可以将控制台看作一个 API 设计室，并将其用于确定 API 的特征、试验其行为、构建 API 并分阶段部署您的 API。

**Topics**
+ [使用 HTTP 自定义集成创建 API](#api-gateway-create-resource-and-methods)
+ [（可选）映射请求参数](#api-gateway-create-resources-and-methods-next-steps)

## 使用 HTTP 自定义集成创建 API
<a name="api-gateway-create-resource-and-methods"></a>

 本部分详细介绍了创建资源、在资源上公开方法、配置方法来实现所需的 API 行为以及测试和部署 API 的步骤。

在此步骤中，您将创建空 API。在以下步骤中，您将创建资源和方法，以使用非代理 HTTP 集成将 API 连接到 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` 端点。

**创建 API**

1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 如果您是第一次使用 API Gateway，您会看到一个介绍服务特征的页面。在 **REST API** 下，选择**生成**。当**创建示例 API** 弹出框出现时，选择**确定**。

   如果这不是您首次使用 API Gateway，请选择**创建 API**。在 **REST API** 下，选择**生成**。

1.  对于 **API 名称**，请输入 **HTTPNonProxyAPI**。

1. （可选）对于**描述**，输入描述。

1. 将 **API 端点类型**设置保留为**区域**。

1. 为 **IP 地址类型**选择 **IPv4**。

1. 选择**创建 API**。

**资源**树显示了不带任何方法的根资源 (`/`)。在本练习中，我们将创建一个与 PetStore 网站 (http://petstore-demo-endpoint.execute-api.com/petstore/pets) 进行 HTTP 自定义集成的 API。出于说明目的，我们将创建一个 `/pets` 资源作为根的子项，并在该资源上公开一个 GET 方法，以便客户端从 PetStore 网站上检索可用宠物项目列表。

**创建 /pets 资源**

1. 选择**创建资源**。

1. 将**代理资源**保持为关闭状态。

1. 将**资源路径**保持为 `/`。

1. 对于**资源名称**，输入 **pets**。

1. 将 **CORS（跨源资源共享）**保持为关闭状态。

1. 选择**创建资源**。

在此步骤中，您将在 **/pets** 资源上创建 `GET` 方法。该 `GET` 方法已与 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` 网站集成。适用于 API 方法的其他选项包括以下这些：
+ **POST**，主要用于创建子资源。
+ **PUT**，主要用于更新现有资源（也可用于创建子资源，但我们不建议这样做）。
+ **DELETE**，用于删除资源。
+ **PATCH**，用于更新资源。
+ **HEAD**，主要用在测试场景中。它与 GET 相同，但不能返回资源表示。
+ **OPTIONS**，可供调用方用于获取目标服务的可用通信选项相关信息。

 对于集成请求的 **HTTP 方法**，您必须选择一种受后端支持的方法。对于 `HTTP` 或 `Mock integration`，方法请求和集成请求可以使用相同的 HTTP 动词。对于其他集成类型，方法请求与集成请求可能会使用不同的 HTTP 动词。例如，要调用 Lambda 函数，集成请求必须使用 `POST` 调用该函数，而方法请求可能会根据 Lambda 函数的逻辑使用任何 HTTP 动词来进行调用。

**在 **/pets** 资源上创建 `GET` 方法**

1. 选择 **/pets** 资源。

1. 选择**创建方法**。

1. 对于**方法类型**，选择 **GET**。

1. 对于**集成类型**，选择 **HTTP 集成**。

1. 将 **HTTP 代理集成**保持为关闭状态。

1. 对于 **HTTP 方法**，选择 **GET**。

1. 对于**端点 URL**，输入 **http://petstore-demo-endpoint.execute-api.com/petstore/pets**。

   PetStore 网站可让您在给定页面上按宠物类型（例如“Dog”或“Cat”）检索 `Pet` 项目的列表。

1. 对于**内容处理**，选择**传递**。

1. 选择 **URL 查询字符串参数**。

   PetStore 网站使用 `type` 和 `page` 查询字符串参数来接受输入。您可以将查询字符串参数添加到方法请求中，并将其映射到集成请求的相应查询字符串参数中。

1. 要添加查询字符串参数，请执行以下操作：

   1. 选择**添加查询字符串**。

   1. 对于**名称**，输入 **type**。

   1. 保持**必填**和**缓存**为已关闭状态。

   重复上述步骤，再创建一个命名为 **page** 查询字符串。

1. 选择**创建方法**。

客户端现在可以在提交请求时提供一个宠物类型和页码作为查询字符串参数。这些输入参数必须映射到集成的查询字符串参数中，以便将输入值转发到后端的 PetStore 网站。

**将输入参数映射到集成请求**

1. 在**集成请求**选项卡的**集成请求设置**下，选择**编辑**。

1. 选择 **URL 查询字符串参数**，然后执行以下操作：

   1. 选择**添加查询字符串参数**。

   1. 对于**名称**，请输入 **type**。

   1. 对于**映射自**，输入 **method.request.querystring.type**。

   1. 将**缓存**保持为关闭状态。

   1. 选择**添加查询字符串参数**。

   1. 对于**名称**，请输入 **page**。

   1. 对于**映射自**，输入 **method.request.querystring.page**。

   1. 将**缓存**保持为关闭状态。

1. 选择**保存**。

**测试 API**

1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。

1. 对于**查询字符串**，输入 **type=Dog&page=2**。

1. 选择**测试**。

    结果类似于以下内容：

      
![\[GET on Pets 方法的调用测试结果\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/api-gateway-create-api-step-by-step-test-invoke-get-on-pets-result-new-console.png)

    测试成功后，我们可以部署 API 以使其公开可用。

1. 选择**部署 API**。

1. 对于**阶段**，选择**新建阶段**。

1. 对于**阶段名称**，输入 **Prod**。

1. （可选）对于**描述**，输入描述。

1. 选择**部署**。

1.  （可选）在**阶段详细信息**下，对于**调用 URL**，您可以选择复制图标以复制您 API 的调用 URL。您可以将此值与 [Postman](https://www.postman.com) 和 [cURL](https://curl.se/) 等工具结合使用来测试您的 API。

 如果您使用开发工具包创建客户端，您可以调用开发工具包公开的方法来对请求签名。有关具体实施方式，请参阅您选择的[AWS开发工具包](https://aws.amazon.com/developer/tools/)。

**注意**  
 如果您的 API 发生更改，您必须重新部署 API 以便让新特征或更新后的特征生效，然后才能再次调用请求 URL。

## （可选）映射请求参数
<a name="api-gateway-create-resources-and-methods-next-steps"></a>

### API Gateway API 的映射请求参数
<a name="getting-started-mappings"></a>

 本教程演示了如何对 API 的方法请求创建 `{petId}` 路径参数以指定一个项目 ID，将其映射到集成请求 URL 中的 `{id}` 路径参数，并将请求发送至 HTTP 端点。

**注意**  
 如果未正确输入字母的大小写，例如应该输入大写字母时输入了小写字母，则可能会在稍后的演练中导致错误。

#### 步骤 1：创建资源
<a name="getting-started-mappings-add-resources"></a>

在此步骤中，您将使用路径参数 \$1petId\$1 创建资源。

**创建 \$1petId\$1 资源**

1. 选择 **/pets** 资源，然后选择**创建资源**。

1. 将**代理资源**保持为关闭状态。

1. 对于**资源路径**，选择 **/pets/**。

1. 对于**资源名称**，输入 **\$1petId\$1**。

    在 `petId` 两边使用大括号 (`{ }`)，以便显示为 **/pets/\$1petId\$1**。

1. 将 **CORS（跨源资源共享）**保持为关闭状态。

1. 选择**创建资源**。

#### 步骤 2：创建和测试方法
<a name="getting-started-mappings-set-methods"></a>

 在此步骤中，您将使用 `{petId}` 路径参数创建 `GET` 方法。

**设置 GET 方法**

1. 选择 **/\$1petId\$1** 资源，然后选择**创建方法**。

1. 对于**方法类型**，选择 **GET**。

1. 对于**集成类型**，选择 **HTTP 集成**。

1. 将 **HTTP 代理集成**保持为关闭状态。

1. 对于 **HTTP 方法**，选择 **GET**。

1. 对于**端点 URL**，输入 **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**。

1. 对于**内容处理**，选择**传递**。

1. 将**默认超时**保持为开启状态。

1. 选择**创建方法**。

现在，将刚刚创建的 `{petId}` 路径参数映射到集成请求的 HTTP 端点 URL 中的 `{id}` 路径参数。HTTP 端点 URL 为 **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**。

**映射 `{petId}` 路径参数**

1. 在**集成请求**选项卡的**集成请求设置**下，选择**编辑**。

1. 选择 **URL 路径参数**。

1.  API Gateway 为名为 **petId** 的集成请求创建路径参数，但是，此路径参数对您设置为后端集成的 HTTP 端点 URL 无效。HTTP 端点使用 `{id}` 作为路径参数。对于**名称**，删除 **petId** 并输入 **id**。

   这可将方法请求路径参数 `petId` 映射到集成请求路径参数 `id`。

1. 选择**保存**。

现在测试该方法。

**测试 方法**

1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。

1. 在 **petId** 的**路径**下，输入 **4**。

1. 选择 **Test (测试)**。

   如果成功，**响应正文**将显示以下内容：

   ```
   {
     "id": 4,
     "type": "bird",
     "price": 999.99
   }
   ```

#### 步骤 3：部署 API
<a name="getting-started-mappings-deploy"></a>

在此步骤中，您将部署 API，以便在 API Gateway 控制台外部对其进行调用。

**部署 API**

1. 选择**部署 API**。

1. 对于**阶段**，选择 **Prod**。

1. （可选）对于**描述**，输入描述。

1. 选择 **Deploy (部署)**。

#### 步骤 4：测试 API
<a name="getting-started-mappings-test"></a>

在此步骤中，您将转到 API Gateway 控制台外部，并使用您的 API 访问 HTTP 端点。

1. 在主导航窗格中，选择**阶段**。

1. 在**阶段详细信息**下，选择复制图标以复制您 API 的调用 URL。

   它应该如下所示：

   ```
   https://my-api-id.execute-api.region-id.amazonaws.com/prod
   ```

1. 将此 URL 输入到新浏览器标签页的地址框中并在提交请求前将 `/pets/4` 附加到该 URL。

1. 浏览器将返回以下内容：

   ```
   {
     "id": 4,
     "type": "bird",
     "price": 999.99
   }
   ```

#### 后续步骤
<a name="api-gateway-create-resources-and-methods-next-steps"></a>

您可以通过开启请求验证、转换数据或创建自定义网关响应来进一步自定义 API。

要探索更多自定义 API 的方法，请参阅以下教程：
+ 有关请求验证的更多信息，请参阅[在 API Gateway 中设置基本请求验证](api-gateway-request-validation-set-up.md)。
+ 有关如何转换请求和响应负载的信息，请参阅[教程：修改集成请求和响应以集成到 AWS 服务](set-up-data-transformations-in-api-gateway.md)。
+ 有关如何创建自定义网关响应的信息，请参阅[使用 API Gateway 控制台为 REST API 设置网关响应](set-up-gateway-response-using-the-console.md)。