Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

使用 API Gateway REST API 设置边缘优化的 API

使用 API Gateway REST API 设置 API 涉及配合使用 RestApiResourceMethodMethodResponseIntegrationIntegrationResponse 类型的 API Gateway 资源。以下过程将带您逐步了解配合使用这些 API Gateway 资源来设置简单 PetStore API 的基本步骤。

创建简单 PetStore API

  1. 要设置边缘优化的 API,请调用 API Gateway 的 restapi:create 链接关系,以将 RestApi 的 API Gateway 资源添加到所选区域中您的账户:

    POST /restapis HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170511T214723Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170511/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=d0abd98a2a06199531c2916b162ede9f63a247032cdc8e4d077216446d13103c Cache-Control: no-cache Postman-Token: 0889d2b5-e507-6aab-f222-ab9548dbacaa { "name": "Simple PetStore (REST API)", "description": "A sample API Gateway API created using the REST API." }

    成功的请求会返回一个包含 201 Created 状态代码以及与以下输出类似的负载的响应:

    { "createdDate": "2017-05-11T21:47:24Z", "description": "A sample API Gateway API created using the REST API.", "endpointConfiguration": { "types": "EDGE" }, "id": "x7hyqq0ik7", "name": "Simple PetStore (REST API)" }

    记下新创建的 RestApiid 值。您会在对此 API 的后续操作中使用这个 id 值。新创建的 RestApi 带有 API 的根资源 (/)。您需要指定这个根资源的 id 值以便附加子资源,并在根资源上添加方法。要获取此 API 标识符,请获取 API 的 resources 集合,然后解析结果以获取 path 值为 / 的条目的 id 属性值。

  2. 要获取 API 根资源标识符,请调用 restapi:resources 链接关系:

    GET /restapis/x7hyqq0ik7/resources HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170511T215738Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170511/us-west-2/apigateway/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=76c24ef91d835b85313142bf75545c4ac4c212067e8188ee6a127c21dae09e29

    该请求会返回一个包含 200 OK 状态代码以及与以下输出类似的负载的响应:

    { "_embedded": { "item": { "_links": { "self": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd" }, "method:by-http-method": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/{http_method}", "templated": true }, "method:put": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/{http_method}", "templated": true }, "resource:create-child": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd" }, "resource:update": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd" } }, "id": "0f72nvvnkd", "path": "/" } } }

    根资源标识符是与 "/"path 值相关的 id 值。在本例中,它是 0f72nvvnkd

  3. 要在根资源 (0f72nvvnkd) 下添加 pets 资源,以表示 PetStore 的宠物集合,请调用 resource:create 链接关系 API Gateway。

    POST /restapis/x7hyqq0ik7/resources/0f72nvvnkd HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T000729Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=8a7093411c97b0aa90f4b1890475d93cf20aa3732089da61e6deb410fbc6037d Cache-Control: no-cache Postman-Token: 48abcd2f-c357-9e44-669e-d8d813f876ca { "pathPart": "pets" }

    成功响应中包含新创建的子资源 (47rxl6pets/pets) 及其父级 (0f72nvvnkd)。

    { ..., "id": "47rxl6", "parentId": "0f72nvvnkd", "path": "/pets", "pathPart": "pets" }

    同样,要在 pets 集合下添加单个宠物 (按照 47rxl6 的资源 ID 进行引用),请调用以下 resource:create 链接关系:

    POST /restapis/x7hyqq0ik7/resources/47rxl6 HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T000729Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=8a7093411c97b0aa90f4b1890475d93cf20aa3732089da61e6deb410fbc6037d Cache-Control: no-cache Postman-Token: 48abcd2f-c357-9e44-669e-d8d813f876ca { "pathPart": "{petId}" }

    生成的响应类似于以下示例:

    { ..., "id": "ab34fgd", "parentId": "47rxl6", "path": "/pets/{petId}", "pathPart": "{petsId}" }
  4. 要将 GET 方法添加到 API 的 /pets 资源 (47rxl6),请调用 API Gateway 的以下 method:put 链接关系:

    PUT /restapis/x7hyqq0ik7/resources/47rxl6/methods/GET HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T000729Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=8a7093411c97b0aa90f4b1890475d93cf20aa3732089da61e6deb410fbc6037d Cache-Control: no-cache Postman-Token: 48abcd2f-c357-9e44-669e-d8d813f876ca { "authorizationType": "NONE" }

    此方法支持开放式访问,因为 authorization-type 设置为 NONE。要仅允许已验证身份的用户调用此方法,您可以使用 IAM 角色和策略、自定义授权方或者 Amazon Cognito 用户池。有关更多信息,请参阅 在 API Gateway 中控制对 API 的访问

    成功的请求会返回一个 201 Created 响应,其负载与以下类似:

    { ..., "apiKeyRequired": false, "authorizationType": "NONE", "httpMethod": "GET" }

    要将 GET 方法添加到 API 的 /pets/{petId} 资源 (ab34fgd),请调用 API Gateway 的以下 method:put 链接关系:

    PUT /restapis/x7hyqq0ik7/resources/ab34fgd/methods/GET HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T000729Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=8a7093411c97b0aa90f4b1890475d93cf20aa3732089da61e6deb410fbc6037d Cache-Control: no-cache Postman-Token: 48abcd2f-c357-9e44-669e-d8d813f876ca { "authorizationType": "NONE", "requestParameters": { "method.request.path.petId": true } }

    您必须声明 petId 的方法请求路径参数,以便 API Gateway 将其动态设置值映射到相应的集成请求参数,然后将其传递到后端。您必须始终根据需要设置路径参数。另外,根据 API 要求,您可以在方法请求上设置标头和查询参数。对于 POSTPUTPATCH 或带有负载的任何其他方法,您可以在方法请求中为负载定义一个模型。有关这些设置的更多信息,请参阅在 API Gateway 中设置 API 方法

    成功的响应包含 201 Created 状态代码以及与以下类似的负载:

    { "apiKeyRequired": false, "authorizationType": "NONE", "httpMethod": "GET", "requestParameters": { "method.request.path.petId": true } }
  5. 要为 API 的 GET /pets 方法添加包含 200 状态代码的方法响应,请调用 methodresponse:put 链接关系,并指定 47rxl6 以引用公开此方法的资源:

    PUT /restapis/x7hyqq0ik7/resources/47rxl6/methods/GET/responses/200 HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T003943Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=229ef4cfba4bbe41132f36c027f0ae4449bb741671875075a4b216e9b778233e Cache-Control: no-cache Postman-Token: 268fcf18-92e4-dfea-821a-ebf4e1d0edfd {}

    成功的请求会返回一个包含 201 Created 状态代码以及与以下输出类似的负载的响应:

    { ..., "statusCode": "200" }

    同样,要将 200 响应添加到 GET /pets/{petId} 方法,请调用以下 methodresponse:put 链接关系,并通过其 ID (ab34fgd) 引用所需的 /pets/{petId} 资源:

    PUT /restapis/x7hyqq0ik7/resources/ab34fgd/methods/GET/responses/200 HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T003943Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=229ef4cfba4bbe41132f36c027f0ae4449bb741671875075a4b216e9b778233e Cache-Control: no-cache Postman-Token: 268fcf18-92e4-dfea-821a-ebf4e1d0edfd {}

    您刚才设置的 MethodMethodRepsonse 的 API Gateway 资源定义了 API 面向客户端的接口。对于非代理集成,您必须添加并配置 IntegrationIntegrationResponse 的 API Gateway 资源,以封装提交到后端的集成请求和后端返回的集成响应。对于代理集成,无需设置 IntegrationIntegrationResponse

  6. 要为 GET /pets 方法设置 Integration,请调用 API Gateway 的 integration:put 链接关系,并通过其 ID 值 (47rxl6) 引用 /pets 资源:

    PUT /restapis/x7hyqq0ik7/resources/47rxl6/methods/GET/integration HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T002249Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=10359971a8c54862a47e39d6a6e4b6e62c263e9a2b785b47b40c426c0aa61c19 { "type" : "HTTP", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets" }

    在请求负载中,uri 指向与方法相关联的后端终端节点。type 指的是集成类型。对于指定的 HTTP 终端节点 http://petstore-demo-endpoint.execute-api.com/petstore/pets,集成类型必须为 HTTPhttpMethod 属性根据后端需要引用 HTTP 动词,该动词可能不同于调用 method:put 链接关系时设置的方法请求 HTTP 动词。

    成功的请求会返回一个包含 201 Created 状态代码以及与以下输出类似的负载的响应:

    { ..., "cacheKeyParameters": [], "cacheNamespace": "47rxl6", "httpMethod": "GET", "passthroughBehavior": "WHEN_NO_MATCH", "type": "HTTP", "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets" }

    同样,要为 GET /pets/{petId} 方法设置集成,请调用 API Gateway 的以下 integration:put 链接关系,并通过其 ab34fgd 值引用 /pets/{petId} 资源,添加从 {petId}{id} 的请求参数映射:

    PUT /restapis/x7hyqq0ik7/resources/ab34fgd/methods/GET/integration HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T002249Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=10359971a8c54862a47e39d6a6e4b6e62c263e9a2b785b47b40c426c0aa61c19 { "type" : "HTTP", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}", "requestParameters": { "integration.request.path.id": "method.request.path.petId" } }

    integration:put 请求的成功响应如下所示:

    { ..., "cacheKeyParameters": [], "cacheNamespace": "ab34fgd", "httpMethod": "GET", "passthroughBehavior": "WHEN_NO_MATCH", "type": "HTTP", "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}", "requestParameters": { "integration.request.path.id": "method.request.path.petId" } }
  7. 要为 GET /pets 方法设置 200 OK IntegrationResponse,请调用 API Gateway 的以下 integrationresponse:put 链接关系:

    PUT /restapis/x7hyqq0ik7/resources/47rxl6/methods/GET/integration/responses/200 HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T004542Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=545ab6ea151f72c52161ee856ee621f136d717e40a02743cd8fe3638895794b1 Cache-Control: no-cache Postman-Token: d29cabea-5232-7021-88ad-f1e950f55a99 {}

    成功的请求会返回一个包含 201 Created 状态代码以及与以下输出类似的负载的响应:

    { ..., "statusCode": "200" }

    要为 GET /pets/{petId} (资源 idab34fgd) 方法设置 200 OK IntegrationResponse,请调用 API Gateway 的以下 integrationresponse:put 链接关系:

    PUT /restapis/x7hyqq0ik7/resources/ab34fgd/methods/GET/integration/responses/200 HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T004542Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=545ab6ea151f72c52161ee856ee621f136d717e40a02743cd8fe3638895794b1 {}

    现在,我们已成功创建包含集成类型为 HTTPGET /petsGET /pets/{petId} 方法的简单 PetStore API。

  8. 要打开 API 供您的客户调用,请通过调用 API Gateway 的 deployment:create 链接关系将 API 部署到 test 阶段。

    POST /restapis/x7hyqq0ik7/deployments HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T004542Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=545ab6ea151f72c52161ee856ee621f136d717e40a02743cd8fe3638895794b1 { "stageName" : "test", "stageDescription" : "First stage", "description" : "First deployment" }

    成功的响应包含 201 Created 状态代码以及与以下类似的负载:

    { ..., "createdDate": "2017-10-13T20:28:56Z", "description": "First deployment", "id": "s7ja1r" }

    现在,您可以通过在浏览器中为 GET /pets 方法键入 https://x7hyqq0ik7.execute-api.us-west-2.amazonaws.com/test/pets URL 来测试部署的 API。请将 RestApi 标识符 (x7hyqq0ik7) 替换为您的 API 的标识符。预期的输出应如下所示:

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

    要测试 GET /pets/{petId} 方法,请在浏览器中键入 https://x7hyqq0ik7.execute-api.us-west-2.amazonaws.com/test/pets/3 URL,并将 RestApi 标识符替换为 API 的标识符。预期的输出应如下所示:

    { "id": 3, "type": "fish", "price": 0.99 }