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

在 API Gateway 中设置基本请求验证

您可以在 API 的 OpenAPI 定义文件中设置请求验证程序,然后将 OpenAPI 定义导入到 API Gateway。您也可以在 API Gateway 控制台中设置验证程序,或者通过调用 API Gateway REST API、AWS CLI 或某个 AWS SDK 来进行设置。在这里,我们将介绍如何使用 OpenAPI 文件、控制台和 API Gateway REST API 来实现这一点。

通过导入 OpenAPI 定义来设置基本请求验证

以下步骤介绍如何通过导入 OpenAPI 文件来启用基本请求验证。

通过将 OpenAPI 文件导入 API Gateway 来启用请求验证

  1. 在 OpenAPI 中声明请求验证程序,操作方式为在 API 级别的 x-amazon-apigateway-request-validators 对象 映射中指定一组 x-amazon-apigateway-request-validators.requestValidator 对象 对象。例如,示例 API OpenAPI 文件包含 x-amazon-apigateway-request-validators 映射,用验证程序的名称作为键值。

    OpenAPI 3.0OpenAPI 2.0
    OpenAPI 3.0
    { "openapi": "3.0.0", "info": { "title": "ReqValidation Sample", "version": "1.0.0" }, "servers": [ { "url": "/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "x-amazon-apigateway-request-validators": { "all": { "validateRequestBody": true, "validateRequestParameters": true }, "params-only": { "validateRequestBody": false, "validateRequestParameters": true } } }
    OpenAPI 2.0
    { "swagger": "2.0", "info": { "title": "ReqValidation Sample", "version": "1.0.0" }, "schemes": [ "https" ], "basePath": "/v1", "produces": [ "application/json" ], "x-amazon-apigateway-request-validators" : { "all" : { "validateRequestBody" : true, "validateRequestParameters" : true }, "params-only" : { "validateRequestBody" : false, "validateRequestParameters" : true } }, ... }

    在 API 或方法上启用验证程序时,您需要选择验证程序的名称,如下一步骤所示。

  2. 要在 API 的所有方法上启用请求验证程序,请在 API 级别指定 API OpenAPI 定义文件的 x-amazon-apigateway-request-validator 属性 属性。要在单独的方法上启用请求验证程序,请在方法级别指定 x-amazon-apigateway-request-validator 属性。例如,如果没有被覆盖,则以下 x-amazon-apigateway-request-validator 属性可以在所有 API 方法上启用 params-only 验证程序。

    OpenAPI 3.0OpenAPI 2.0
    OpenAPI 3.0
    { "openapi": "3.0.0", "info": { "title": "ReqValidation Sample", "version": "1.0.0" }, "servers": [ { "url": "/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "x-amazon-apigateway-request-validator": "params-only", ... }
    OpenAPI 2.0
    { "swagger": "2.0", "info": { "title": "ReqValidation Sample", "version": "1.0.0" }, "schemes": [ "https" ], "basePath": "/v1", "produces": [ "application/json" ], ... "x-amazon-apigateway-request-validator" : "params-only", ... }

    要在单独的方法上启用请求验证程序,请在方法级别指定 x-amazon-apigateway-request-validator 属性。例如,以下 x-amazon-apigateway-request-validator 属性可以在 all 方法上启用 POST /validation 验证程序。这会覆盖继承自 API 的 params-only 验证程序。

    OpenAPI 3.0OpenAPI 2.0
    OpenAPI 3.0
    { "openapi": "3.0.0", "info": { "title": "ReqValidation Sample", "version": "1.0.0" }, "servers": [ { "url": "/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "paths": { "/validation": { "post": { "x-amazon-apigateway-request-validator": "all", ... } } } ... }
    OpenAPI 2.0
    { "swagger": "2.0", "info": { "title": "ReqValidation Sample", "version": "1.0.0" }, "schemes": [ "https" ], "basePath": "/v1", "produces": [ "application/json" ], ... "paths": { "/validation": { "post": { "x-amazon-apigateway-request-validator" : "all", ... }, ... } } ... }
  3. 在 API Gateway 中导入此示例 OpenAPI 定义,从而创建启用了请求验证程序的 API:

    POST /restapis?mode=import&failonwarning=true HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20170306T234936Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170306/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash} Copy the JSON object from this sample OpenAPI definition and paste it here.
  4. 将新创建的 API (fjd6crafxc) 部署到指定阶段 (testStage)。

    POST /restapis/fjd6crafxc/deployments HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20170306T234936Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170306/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash} { "stageName" : "testStage", "stageDescription" : "Test stage", "description" : "First deployment", "cacheClusterEnabled" : "false" }

有关如何使用 API Gateway REST API 来测试请求验证功能的说明,请参阅 使用 API Gateway REST API 测试基本请求验证。有关如何使用 API Gateway 控制台进行测试的说明,请参阅 使用 API Gateway 控制台测试基本请求验证

使用 API Gateway REST API 设置请求验证程序

在 API Gateway REST API 中,请求验证程序由 RequestValidator 资源表示。要让某个 API 像示例 API 一样支持请求验证程序,请向 RequestValidators 集合添加一个键值为 params-only 的仅限参数的验证程序,并添加一个键值为 all 的完整验证程序。

使用 API Gateway REST API 启用基本请求验证

假设您有一个与示例 API 类似的 API,但是还没有设置请求验证程序。如果您的 API 已经启用了请求验证程序,请调用相应的 requestvalidator:updatemethod:put 操作,不要调用 requestvalidator:createmethod:put

  1. 要设置 params-only 请求验证程序,请调用 requestvalidator:create 操作,如下所示:

    POST /restapis/restapi-id/requestvalidators HTTP/1.1 Content-Type: application/json Host: apigateway.region.amazonaws.com X-Amz-Date: 20170223T172652Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/region/apigateway/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature={sig4_hash} { "name" : "params-only", "validateRequestBody" : "false", "validateRequestParameters" : "true" }
  2. 要设置 all 请求验证程序,请调用 requestvalidator:create 操作,如下所示:

    POST /restapis/restapi-id/requestvalidators HTTP/1.1 Content-Type: application/json Host: apigateway.region.amazonaws.com X-Amz-Date: 20170223T172652Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/region/apigateway/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature={sig4_hash} { "name" : "all", "validateRequestBody" : "true", "validateRequestParameters" : "true" }

    如果上文所述的验证程序键已存在于 RequestValidators 映射中,请调用 requestvalidator:update 操作,不要重置验证规则。

  3. 要将 all 请求验证程序应用于 POST 方法,请调用 method:put 来启用指定的验证程序(由 requestValidatorId 属性识别),或者调用 method:update 来更新已启用的验证程序。

    PUT /restapis/restapi-id/resources/resource-id/methods/POST HTTP/1.1 Content-Type: application/json Host: apigateway.region.amazonaws.com X-Amz-Date: 20170223T172652Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/region/apigateway/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature={sig4_hash} { "authorizationType" : "NONE", ..., "requestValidatorId" : "all" }

使用 API Gateway 控制台设置基本请求验证

借助 API Gateway 控制台,您可以使用以下三种验证程序之一在方法上设置基本请求验证:

  • Validate body (验证正文):仅限正文的验证程序。

  • Validate query string parameters and headers (验证查询字符串参数和标头):仅限参数的验证程序。

  • Validate body, query string parameters, and headers (验证正文、查询字符串和标头):适用于正文和参数验证的验证程序。

当您选择以上一种验证程序并在某种 API 方法上将其启用时,如果该验证程序尚未添加到 API 的验证程序映射,那么 API Gateway 控制台会向 API 的 RequestValidators 映射添加该验证程序。

在方法上启用请求验证程序

  1. 如果尚未登录,请登录到 API Gateway 控制台。

  2. 创建一个新 API 或选择一个现有 API。

  3. 创建该 API 的新资源或选择该 API 的现有资源。

  4. 创建该资源的新方法或选择该资源的现有方法。

  5. 选择方法请求

  6. 设置下选择 Request Validator (请求验证程序) 的铅笔图标。

  7. Request Validator (请求验证程序) 下拉列表中选择 Validate bodyValidate query string parameters and headersValidate body, query string parameters, and headers,然后选择对勾图标以保存您的选择。

要在控制台中测试和使用请求验证程序,请按照使用 API Gateway 控制台测试基本请求验证中的说明操作。