教程:使用 HTTP 代理集成构建 REST API - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

教程:使用 HTTP 代理集成构建 REST API

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

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

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

通过 API Gateway 控制台使用 HTTP 代理集成创建 API

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

创建 API
  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

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

    如果这不是您首次使用 API Gateway,请选择创建 API。在 REST API 下,选择 Build (生成)

  3. 对于 API Name (API 名称),请输入 HTTPProxyAPI

  4. (可选)对于描述,输入描述。

  5. API 端点类型设置保留为区域

  6. 选择创建 API

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

创建 /{proxy+} 资源
  1. 选择 API。

  2. 在主导航窗格中,选择资源

  3. 选择创建资源

  4. 开启代理资源

  5. 资源路径保持为 /

  6. 对于资源名称,输入 {proxy+}

  7. CORS(跨源资源共享)保持为关闭状态。

  8. 选择创建资源

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

创建 ANY 方法
  1. 选择 /{proxy+} 资源。

  2. 选择 ANY 方法。

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

  4. 对于集成类型,选择 HTTP

  5. 打开 HTTP 代理集成

  6. 对于 HTTP 方法,选择 ANY

  7. 对于端点 URL,输入 http://petstore-demo-endpoint.execute-api.com/{proxy}

  8. 选择保存

使用 HTTP 代理集成测试 API

特定客户端请求是否成功取决于以下因素:

  • 后端是否提供了相应的后端终端节点,如果已提供,是否授予了所需的访问权限。

  • 客户端是否提供了正确输入。

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

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

通过代理资源使用 HTTP 代理集成测试与 PetStore 网站集成的 API
  1. 选择测试选项卡。您可能需要选择右箭头按钮,以显示该选项卡。

  2. 对于方法类型中,选择 GET

  3. 对于路径,在代理下输入 petstore/pets

  4. 对于查询字符串,输入 type=fish

  5. 选择测试

    由于后端网站支持 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

  2. 对于阶段,选择新建阶段

  3. 对于阶段名称,输入 test

  4. (可选)对于描述,输入描述。

  5. 选择部署

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

调用 API
  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 选择 API。

  3. 在主导航窗格中,选择阶段

  4. 阶段详细信息下,选择复制图标以复制您 API 的调用 URL。

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

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

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

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