教程:使用 HTTP 非代理集成构建 REST API - Amazon API Gateway

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

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

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

使用 HTTP 自定义集成创建 API

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

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

创建 API
  1. 通过以下网址登录到 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 名称),请输入 HTTPNonProxyAPI

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

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

  6. 选择创建 API

Resources (资源) 树显示了不带任何方法的根资源 (/)。在本练习中,我们将使用 PetStore 网站的 HTTP 自定义集成构建 API(http://petstore-demo-endpoint.execute-api.com/petstore/pets。) 为了说明起见,我们将创建一个/pets资源作为根目录的子资源,并在此资源上公开一个 GET 方法,供客户从 PetStore 网站上检索可用 Pets 物品的列表。

创建 /pets 资源
  1. 选择 / 资源,然后选择创建资源

  2. 代理资源保持为关闭状态。

  3. 资源路径保持为 /

  4. 对于资源名称,输入 pets

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

  6. 选择创建资源

在此步骤中,您将在 /pets 资源上创建 GET 方法。该 GET 方法已与 http://petstore-demo-endpoint.execute-api.com/petstore/pets 网站集成。适用于 API 方法的其他选项包括以下这些:

  • POST,主要用于创建子资源。

  • PUT,主要用于更新现有资源(也可用于创建子资源,但我们不建议这样做)。

  • DELETE,用于删除资源。

  • PATCH,用于更新资源。

  • HEAD,主要用在测试场景中。它与 GET 相同,但不能返回资源表示。

  • OPTIONS,可供调用方用于获取目标服务的可用通信选项相关信息。

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

/pets 资源上创建 GET 方法
  1. 选择 /pets 资源。

  2. 选择创建方法

  3. 对于方法类型,选择 GET

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

  5. HTTP 代理集成保持为关闭状态。

  6. 对于 HTTP 方法,选择 GET

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

  8. 对于内容处理,选择传递

  9. 默认超时保持为开启状态。

  10. 选择创建方法

该 PetStore 网站允许您在给定页面上按宠物类型(例如 “狗” 或 “猫”)检索Pet物品清单。它使用 typepage 查询字符串参数来接受此类输入。因此,我们必须将查询字符串参数添加到方法请求中,并将其映射到集成请求的相应查询字符串中。

GET 方法添加查询字符串参数
  1. 方法请求选项卡上的方法请求设置下,选择编辑

  2. 选择 URL 查询字符串参数,然后执行以下操作:

    1. 选择 Add query string (添加查询字符串)

    2. 对于名称,输入 type

    3. 保持必填缓存为已关闭状态。

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

  3. 选择保存

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

将输入参数映射到集成请求
  1. 集成请求选项卡的集成请求设置下,选择编辑

  2. 选择 URL 查询字符串参数,然后执行以下操作:

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

    2. 对于名称,请输入 type

    3. 对于映射自,输入 method.request.querystring.type

    4. 缓存保持为关闭状态。

    5. 选择添加查询字符串参数

    6. 对于名称,请输入 page

    7. 对于映射自,输入 method.request.querystring.page

    8. 缓存保持为关闭状态。

  3. 选择保存

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

  2. 对于查询字符串,输入 type=Dog&page=2

  3. 选择测试

    结果类似于以下内容:

    
            GET on Pets 方法的调用测试结果

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

  4. 选择部署 API

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

  6. 对于阶段名称,输入 Prod

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

  8. 选择部署

  9. (可选)在阶段详细信息下,对于调用 URL,您可以选择复制图标以复制您 API 的调用 URL。您可以将此值与 PostmancURL 等工具结合使用来测试您的 API。

如果您使用开发工具包创建客户端,您可以调用开发工具包公开的方法来对请求签名。有关具体实施方式,请参阅您选择的AWS 开发工具包

注意

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

(可选)映射请求参数

API Gateway API 的映射请求参数

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

注意

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

步骤 1:创建资源

在此步骤中,您将使用路径参数 {petId} 创建资源。

创建 {petId} 资源
  1. 选择 /pets 资源,然后选择创建资源

  2. 代理资源保持为关闭状态。

  3. 对于资源路径,选择 /pets/

  4. 对于资源名称,输入 {petId}

    petId 两边使用大括号 ({ }),以便显示为 /pets/{petId}

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

  6. 选择创建资源

步骤 2:创建和测试方法

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

设置 GET 方法
  1. 选择 /{petId} 资源,然后选择创建方法

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

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

  4. HTTP 代理集成保持为关闭状态。

  5. 对于 HTTP 方法,选择 GET

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

  7. 对于内容处理,选择传递

  8. 默认超时保持为开启状态。

  9. 选择创建方法

现在,将 {petId} 路径参数映射到 HTTP 端点中的 {id} 路径参数。

映射 {petId} 路径参数
  1. 集成请求选项卡的集成请求设置下,选择编辑

  2. 选择 URL 路径参数

  3. API Gateway 将为名为 petId 的集成请求创建路径参数。这不适用于你的后端。HTTP 端点使用 {id} 作为路径参数。将 petId 重命名为 id

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

  4. 选择保存

现在测试该方法。

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

  2. petId路径下,输入 4

  3. 选择 Test (测试)

    如果成功,响应正文将显示以下内容:

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

步骤 3:部署 API

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

部署 API
  1. 选择部署 API

  2. 对于阶段,选择 Prod

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

  4. 选择 Deploy (部署)

步骤 4:测试 API

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

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

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

    它应该如下所示:

    https://my-api-id.execute-api.region-id.amazonaws.com/prod
  3. 将此 URL 输入到新浏览器标签页的地址框中并在提交请求前将 /pets/4 附加到该 URL。

  4. 浏览器将返回以下内容:

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

后续步骤

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

要探索更多自定义 API 的方法,请参阅以下教程: