使用 API Gateway REST API 启用二进制支持 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

使用 API Gateway REST API 启用二进制支持

以下任务演示如何使用 API Gateway REST API 调用来启用二进制支持。

向 API 添加和更新受支持的二进制媒体类型

要允许 API Gateway 支持新的二进制媒体类型,必须将该二进制媒体类型添加到 RestApi 资源的 binaryMediaTypes 列表中。例如,要让 API Gateway 处理 JPEG 图像,应向 RestApi 资源提交 PATCH 请求:

PATCH /restapis/<restapi_id> { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/image~1jpeg" } ] }

属于 image/jpeg 属性值一部分的 MIME 类型规范 path 将转义为 image~1jpeg

要更新受支持的二进制媒体类型,请替换或删除 binaryMediaTypes 资源的 RestApi 列表中的该媒体类型。例如,要将二进制支持从 JPEG 文件更改为原始字节,请向 RestApi 资源提交 PATCH 请求,如下所示:

PATCH /restapis/<restapi_id> { "patchOperations" : [{ "op" : "replace", "path" : "/binaryMediaTypes/image~1jpeg", "value" : "application/octet-stream" }, { "op" : "remove", "path" : "/binaryMediaTypes/image~1jpeg" }] }

配置请求负载转换

如果终端节点需要二进制输入,则将 contentHandling 资源的 Integration 属性设置为 CONVERT_TO_BINARY。为此,请提交 PATCH 请求,如下所示:

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] }

配置响应负载转换

如果客户端接受二进制 blob 形式的结果而不是从终端节点返回的 Base64 编码的负载,则将 IntegrationResponse 资源的 contentHandling 属性设置为 CONVERT_TO_BINARY。为此,请提交 PATCH 请求,如下所示:

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code> { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] }

将二进制数据转换为文本数据

要通过 API Gateway 将二进制数据作为输入的 JSON 属性发送到 Amazon Lambda 或 Kinesis,请执行以下操作:

  1. 通过将新的二进制媒体类型 application/octet-stream 添加到 API 的 binaryMediaTypes 列表,启用 API 的二进制负载支持。

    PATCH /restapis/<restapi_id> { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] }
  2. Integration 资源的 contentHandling 属性上设置 CONVERT_TO_TEXT,并提供映射模板以将二进制数据的 Base64 编码字符串分配给 JSON 属性。在以下示例中,JSON 属性为 body,并且 $input.body 保存 Base64 编码的字符串。

    PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_TEXT" }, { "op" : "add", "path" : "/requestTemplates/application~1octet-stream", "value" : "{\"body\": \"$input.body\"}" } ] }

将文本数据转换为二进制负载

假设 Lambda 函数返回一个 Base64 编码字符串形式的图像文件。要通过 API Gateway 将此二进制输出传递到客户端,请执行以下操作:

  1. 通过添加二进制媒体类型 binaryMediaTypes (如果该类型尚不在列表中) 来更新 API 的 application/octet-stream 列表。

    PATCH /restapis/<restapi_id> { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream", }] }
  2. contentHandling 资源的 Integration 属性设置为 CONVERT_TO_BINARY。请勿定义映射模板。如果不定义映射模板,API Gateway 会调用传递模板,以将 Base64 解码的二进制 blob 作为图像文件返回给客户端。

    PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code> { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" } ] }

传递二进制负载

要使用 API Gateway 将图像存储在 Amazon S3 存储桶中,请执行以下操作:

  1. 通过添加二进制媒体类型 binaryMediaTypes(如果该类型尚不在列表中)来更新 API 的 application/octet-stream 列表。

    PATCH /restapis/<restapi_id> { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] }
  2. contentHandling 资源的 Integration 属性上,设置 CONVERT_TO_BINARY。将 WHEN_NO_MATCH 设置为 passthroughBehavior 属性值,而不定义映射模板。这使 API Gateway 能够调用传递模板。

    PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }, { "op" : "replace", "path" : "/passthroughBehaviors", "value" : "WHEN_NO_MATCH" } ] }