教程:使用 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,可能需要先按照该部分中的说明操作。

通过代理资源使用 HTTP 代理集成构建与 PetStore 网站集成的 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 (生成)

    1. 选择 New API (新 API)

    2. API Name (API 名称) 中输入名称。

    3. 还可选择在 Description (描述) 中添加简短描述。

    4. 选择 Create API (创建 API)

    在本教程中,请使用 ProxyResourceForPetStore 作为 API 名称。

  3. 要创建子资源,请选择 Resources (资源) 树下的父资源项目,然后从 Actions (操作) 下拉菜单中选择 Create Resource (创建资源)。接下来,在 New Child Resource (新子资源) 窗格中执行以下操作。

    1. 选择 Configure as proxy resource (配置为代理资源) 选项以创建代理资源。否则,将其保持未选中状态。

    2. Resource Name* (资源名称*) 输入文本字段中,键入一个名称。

    3. Resource Path* (资源路径*) 输入文本字段中,键入一个新名称或使用默认名称。

    4. 选择 Create Resource (创建资源)

    5. 如果需要,则选择 Enable API Gateway CORS (启用 API Gateway CORS)

    在本教程中,请选择 Configure as proxy resource (作为代理资源进行配置)。对于资源名称,使用默认值 proxy。对于 Resource Path (资源路径),使用 /{proxy+}。选择启用 API Gateway CORS

  4. 要设置与 HTTP 后端集成的 ANY 方法,请执行以下操作:

    1. 选择刚刚创建的资源,然后从 Actions (操作) 下拉菜单中选择 Create Method (创建方法)

    2. 从 HTTP 方法下拉列表中选择 ANY,然后选择复选标记图标以保存选择。

    3. Integration type (集成类型) 选择 HTTP Proxy (HTTP 代理)

    4. Endpoint URL (终端节点 URL) 中键入 HTTP 后端资源 URL。

    5. 为其他字段使用默认设置。

    6. 选择 Save (保存),完成 ANY 方法的配置。

    在本教程中,请使用 http://petstore-demo-endpoint.execute-api.com/{proxy} 作为 Endpoint URL (终端节点 URL)

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

使用 HTTP 代理集成测试 API

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

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

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

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

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

通过代理资源使用 HTTP 代理集成测试与 PetStore 网站集成的 API
  1. 要使用 API Gateway 控制台测试 API 的调用,请执行以下操作。

    1. 资源树中对代理资源选择任意

    2. Method Execution (方法执行) 窗格中选择 Test (测试)

    3. Method (方法) 下拉列表中,选择后端支持的 HTTP 谓词。

    4. 路径 下,键入支持所选操作的代理资源的特定路径。

    5. 如果需要,在 Query Strings (查询字符串) 标题下键入所选操作支持的查询表达式。

    6. 如果需要,在 Headers (标头) 标题下键入所选操作支持的一个或多个标题表达式。

    7. 如果已配置,请在 Stage Variables (阶段变量) 标题下为所选操作设置所需的阶段变量值。

    8. 如果出现提示并要求您这么做,请选择客户端证书标题下的 API Gateway 生成的客户端证书,以便由后端对操作进行身份验证。

    9. 如果出现提示,请在文本编辑器中的 Request Body (请求正文) 标题下键入适当的请求正文。

    10. 选择 Test (测试) 以测试方法的调用。

    在本教程中,将 GET 用作 Method (方法) 来取代 ANY,将 petstore/pets 用作 Path (路径) 来取代代理资源路径 ({proxy}),将 type=fish 用作 Query Strings (查询字符串)

    由于后端网站支持 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 }
  2. 要使用浏览器对 API 的特定资源调用 GET 方法,请执行以下操作。

    1. 从您创建的 API 的 Actions (操作) 下拉菜单中选择 Deploy API (部署 API)(如果您尚未这样做)。按照说明将 API 部署到特定阶段。请注意显示在生成的 Stage Editor (阶段编辑器) 页面上的 Invoke URL (调用 URL)。这是 API 的基本 URL。

    2. 要在特定资源上提交 GET 请求,请将资源路径(包括可能的查询字符串表达式)附加到上一步中获取的 Invoke URL (调用 URL) 值,将完整 URL 复制到浏览器的地址栏中,然后按 Enter。

    在本教程中,请将 API 部署到 test 阶段,将 petstore/pets?type=fish 附加到 API 的调用 URL。这将生成一个 URL https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/petstore/pets?type=fish

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