教程:通过导入示例创建 REST API - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

教程:通过导入示例创建 REST API

您可以使用 Amazon API Gateway 控制台,借助 PetStore 网站的 HTTP 集成来创建并测试简单的 REST API。API 定义预配置为 OpenAPI 2.0 文件。在将 API 定义加载到 API Gateway 中后,您可以使用 API Gateway 控制台来检查 API 的基本结构或直接部署并测试 API。

PetStore 示例 API 支持客户端使用以下方法来访问 HTTP 后端网站 http://petstore-demo-endpoint.execute-api.com/petstore/pets

注意

本教程以 HTTP 端点为例。在创建自己的 API 时,建议您使用 HTTPS 端点进行 HTTP 集成。

  • GET /:用于对未与任何后端终端节点集成的 API 根资源进行读取访问。API Gateway 会使用 PetStore 网站的概述进行响应。这是 MOCK 集成类型的示例。

  • GET /pets:用于对已与名称相同的后端 /pets 资源集成的 API /pets 资源进行读取访问。后端会返回 PetStore 中的可用宠物的页面。这是 HTTP 集成类型的示例。集成终端节点的 URL 为 http://petstore-demo-endpoint.execute-api.com/petstore/pets

  • POST /pets:用于对已与后端 /pets 资源集成的 API /petstore/pets 资源进行写入访问。收到正确请求后,后端会将指定的宠物添加到 PetStore 中并将结果返回给调用方。该集成也是 HTTP 集成。

  • GET /pets/{petId}:用于对指定为传入请求 URL 的路径变量的 petId 值标识的宠物进行读取访问。此方法也具有 HTTP 集成类型。后端会返回在 PetStore 中找到的指定宠物。后端 HTTP 终端节点的 URL 是 http://petstore-demo-endpoint.execute-api.com/petstore/pets/n,其中 n 是一个用作所查询宠物的标识符的整数。

API 支持通过 OPTIONS 集成类型的 MOCK 方法进行 CORS 访问。API Gateway 会返回支持 CORS 访问所需的标头。

以下过程将指导您完成在 API Gateway 控制台中根据示例创建一个 API 并进行测试的步骤。

导入、构建并测试示例 API
  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 请执行以下操作之一:

    • 要创建第一个 API,对于 REST API,请选择构建

    • 如果您之前已经创建了 API,请选择创建 API,然后为 REST API 选择构建

  3. 创建 REST API 下,选择示例 API,然后选择创建 API 以创建示例 API。

    在选择创建 API 之前,您可以向下滚动 OpenAPI 定义以了解此示例 API 的详细信息。

  4. 在主导航窗格中,选择资源。新创建的 API 如下所示:

    Resources (资源) 窗格将所创建 API 的结构显示为节点树。在每个资源上定义的 API 方法均位于节点树的边缘。当选中某个资源时,其所有方法都会在右侧的方法表中列出。与每种方法一起显示的是方法类型、集成类型、授权类型和 API 密钥要求。

  5. 要查看某一方法的详细信息以修改其设置或测试方法调用,请从方法列表或资源树中选择相应的方法名称。在这里,我们选择 POST /pets 方法作为说明示例:

    生成的方法执行窗格显示所选(POST /pets)方法的结构和行为的逻辑视图。

    方法请求方法响应表示 API 与前端的接口,集成请求集成响应表示 API 与后端的接口。

    客户端可以使用 API 通过方法请求访问后端特征。如有必要,API Gateway 会先将客户端请求转换为集成请求中后端可接受的形式,然后再将该传入请求转发至后端。转换后的请求被称为集成请求。同样,后端在集成响应中向 API Gateway 返回响应。API Gateway 随后将其路由至方法响应,然后再将其发送到客户端。API Gateway 也会在必要时将后端响应数据映射为客户端所需的形式。

    对于 API 资源上的 POST 方法,如果该方法请求负载的格式与集成请求负载的格式相同,则无需修改该方法请求负载即可将其传递到集成请求。

    GET / 方法请求使用 MOCK 集成类型,且不与任何真实后端终端节点相关联。相应的集成响应设置为返回静态 HTML 页面。调用该方法时,API Gateway 只需接受该请求,并立即通过方法响应将配置的集成响应返回给客户端。您可以使用模拟集成来测试 API,无需后端终端节点。您也可以将其用于处理本地响应,即从正文映射模板生成的响应。

    作为 API 开发人员,您可以通过配置方法请求和方法响应来控制 API 的前端交互行为,通过设置集成请求和集成响应来控制 API 的后端交互行为。这些涉及到方法和它的相应集成之间的数据映射。目前,我们的侧重点是测试 API 以提供端到端的用户体验。

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

  7. 例如,要测试 POST /pets 方法,请在请求正文中输入以下 {"type": "dog","price": 249.99} 负载,然后选择测试

    该输入可指定我们要添加到 PetStore 网站上的宠物列表中的宠物的属性。

  8. 结果显示如下:

    该输出的日志条目显示了从方法请求到集成请求以及从集成响应到方法响应的状态更改。这可用于对导致请求失败的任何映射错误进行故障排除。此示例中没有应用任何映射:方法请求负载通过集成请求传递到后端;同样地,后端响应通过集成响应传递到方法响应。

    要使用客户端而非 API Gateway 的 test-invoke-request 特征来测试 API,您必须先将 API 部署至一个阶段。

  9. 要部署示例 API,请选择部署 API

  10. 对于阶段,选择新建阶段,然后输入 test

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

  12. 选择部署

  13. 在生成的阶段窗格中的阶段详细信息下,调用 URL 将显示用于调用 API 的 GET / 方法请求的 URL。

  14. 选择复制图标以复制 API 的调用 URL,然后在 Web 浏览器中输入您 API 的调用 URL。成功的响应会返回由集成响应中的映射模板生成的结果。

  15. Stages(阶段)导航窗格中,展开 test(测试)阶段,选择 /pets/{petId} 上的 GET,然后复制 https://api-id.execute-api.region.amazonaws.com/test/pets/{petId}Invoke URL(调用 URL)值。{petId} 代表路径变量。

    Invoke URL (调用 URL) 值(在上一步中获取)粘贴到浏览器的地址栏中,将 {petId} 替换为 1(举例来说),然后按 Enter 键提交请求。系统应返回一个包含以下 JSON 负载的 200 OK 响应:

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

    按上图所示来调用 API 方法是可行的,因为其 Authorization (授权) 类型设置为 NONE。如果使用了 AWS_IAM 授权,那么您需要使用签名版本 4 (SigV4) 协议对请求进行签名。有关此类请求的示例,请参阅教程:使用 HTTP 非代理集成创建 REST API