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

API 集成请求的基本任务

集成请求是 API Gateway 提交到后端的 HTTP 请求,与客户端提交的请求数据一起传递,并在需要时转换数据。HTTP 方法 (或动词) 和集成请求的 URI 由后端 (即,集成终端节点) 决定。它们分别可以与方法请求的 HTTP 方法和 URI 相同或不同。例如,当 Lambda 函数返回从 Amazon S3 提取的文件时,您可以直观地公开此操作,作为对客户端的 GET 方法请求,即使对应的集成请求需要使用 POST 请求来调用 Lambda 函数。对于 HTTP 中断请求,有可能方法请求和对应的集成请求均使用相同的 HTTP 动词。但这不是必需的。您可以集成以下方法请求:

GET /{var}?query=value Host: api.domain.net

使用以下集成请求:

POST / Host: service.domain.com Content-Type: application/json Content-Length: ... { path: "{var}'s value", type: "value" }

作为 API 开发人员,您可以为方法请求使用任意满足需求的 HTTP 动词和 URI。但是,您必须遵守集成终端节点的要求。当方法请求数据不同于集成请求数据时,您可以通过提供从方法请求数据到集成请求数据的映射来协调差异。在前面的示例中,映射将 GET 方法请求的路径变量 ({var}) 和查询参数 (query) 值转换为集成请求的负载属性 pathtype 的值。其他可映射请求数据包含请求标头和正文。使用 API Gateway 控制台设置请求和响应数据映射 中介绍了这些内容。

设置 HTTP 或 HTTP 代理集成请求时,您分配后端 HTTP 终端节点 URL 作为集成请求 URI 值。例如,在 PetStore API 中,用于获取一页宠物的方法请求具有以下集成请求 URI:

http://petstore-demo-endpoint.execute-api.com/petstore/pets

在设置 Lambda 或 Lambda 代理集成时,您分配 Amazon 资源名称 (ARN) 用于调用 Lambda 函数作为集成请求 URI 值。此 ARN 具有以下格式:

arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations

arn:aws:apigateway:api-region:lambda:path/ 之后的部分,即 /2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations,是 Lambda 调用操作的 REST API URI 路径。如果您使用 API Gateway 控制台来设置 Lambda 集成,API Gateway 会在提示您从区域选择 lambda-function-name 之后,创建 ARN 并将其分配给集成 URI。

使用其他 AWS 服务操作设置集成请求时,集成请求 URI 也是 ARN,类似于使用 Lambda Invoke 操作的集成。例如,对于具有 Amazon S3 的 GetBucket 操作的集成,集成请求 URI 是以下格式的 ARN:

arn:aws:apigateway:api-region:s3:path/{bucket}

集成请求 URI 是用于指定操作的路径约定,其中 {bucket} 是存储桶名称的占位符。此外,AWS 服务操作可以按其名称引用。使用操作名称,Amazon S3 的 GetBucket 操作的集成请求 URI 成为以下:

arn:aws:apigateway:api-region:s3:action/GetBucket

使用基于操作的集成请求 URI,存储桶名称 ({bucket}) 必须在集成请求正文中指定 ({ Bucket: "{bucket}" }),按照 GetBucket 操作的输入格式。

对于 AWS 集成,您还必须配置凭证以允许 API Gateway 调用集成操作。您可以为 API Gateway 创建新的或选择现有 IAM 角色以调用操作,然后使用其 ARN 指定角色。下面显示了此 ARN 的示例:

arn:aws:iam::account-id:role/iam-role-name

此 IAM 角色必须包含策略以允许执行操作。它还必须将 API Gateway 声明 (在角色的信任关系中) 作为可信实体以代入角色。此类权限可以在操作本身上授予。他们被称为基于资源的权限。对于 Lambda 集成,您可以调用 Lambda 的 addPermission 操作来设置基于资源的权限,然后在 API Gateway 集成请求中将 credentials 设置为 null。

我们讨论了基本集成设置。高级设置涉及到将方法请求数据映射到集成请求数据。讨论集成响应的基本设置之后,我们将介绍 使用 API Gateway 控制台设置请求和响应数据映射 中的高级主题,其中还会介绍传递负载和处理内容编码。