针对 API Gateway 中的 REST API 的二进制媒体类型
在 API Gateway 中,API 请求和响应具有文本或二进制负载。文本负载是 UTF-8
编码的 JSON 字符串。二进制负载是文本负载以外的负载。例如,二进制负载可以是 JPEG 文件、GZip 文件或 XML 文件。支持二进制媒体所需的 API 配置取决于 API 是使用代理集成还是非代理集成。
Amazon Lambda 代理集成
要处理 Amazon Lambda 代理集成的二进制负载,您必须对函数的响应进行 base64 编码。还必须为 API 配置 binaryMediaTypes。API 的 binaryMediaTypes
配置是 API 视为二进制数据的内容类型的列表。示例二进制媒体类型包括 image/png
或 application/octet-stream
。您可以使用通配符 (*
) 来涵盖多种媒体类型。例如,*/*
包括所有内容类型。
有关代码示例,请参阅 从 API Gateway 中的 Lambda 代理集成返回二进制媒体。
非代理集成
要处理非代理集成的二进制负载,请将媒体类型添加到 RestApi
资源的 binaryMediaTypes 列表中。API 的 binaryMediaTypes
配置是 API 视为二进制数据的内容类型的列表。或者,您可以设置 Integration 和 IntegrationResponse 资源上的 contentHandling 属性。contentHandling
值可以是 CONVERT_TO_BINARY
、CONVERT_TO_TEXT
或未定义。
根据 contentHandling
值,以及响应的 Content-Type
标头或传入请求的 Accept
标头是否匹配 binaryMediaTypes
列表中的某个条目,API Gateway 可以将原始二进制字节编码为 Base64 编码的字符串,将 Base64 编码的字符串解码回其原始字节,或者直接传递正文而不作修改。
您必须按如下方式配置 API,以对 API Gateway 中 API 的二进制负载提供支持:
-
将所需的二进制媒体类型添加到 RestApi 资源的
binaryMediaTypes
列表中。如果未定义此属性和contentHandling
属性,会将负载作为 UTF-8 编码的 JSON 字符串进行处理。 -
解决 Integration 资源的
contentHandling
属性。-
要将请求负载从 base64 编码的字符串转换为其二进制 blob,请将此属性设置为
CONVERT_TO_BINARY
。 -
要将请求负载从二进制 blob 转换为 base64 编码的字符串,请将此属性设置为
CONVERT_TO_TEXT
。 -
要在不修改的情况下传递负载,请将此属性保留为未定义。要在不修改的情况下传递二进制负载,还必须确保
Content-Type
与其中一个binaryMediaTypes
条目匹配,并且已为 API 启用传递行为。
-
-
设置 IntegrationResponse 资源的
contentHandling
属性。contentHandling
属性、客户端请求中的Accept
标头以及 API 的binaryMediaTypes
组合决定了 API Gateway 如何处理内容类型转换。有关详细信息,请参阅API Gateway 中的内容类型转换。
重要
如果某个请求在其 Accept
标头中包含多个媒体类型,API Gateway 将只接受第一个 Accept
媒体类型。如果无法控制 Accept
媒体类型的顺序并且二进制内容的媒体类型不是列表中的第一个,则添加 API 的 binaryMediaTypes
列表中的第一个 Accept
媒体类型。API Gateway 将以二进制形式处理此列表中的所有内容类型。
例如,要在浏览器中使用 <img>
元素发送 JPEG 文件,该浏览器可能会在请求中发送 Accept:image/webp,image/*,*/*;q=0.8
。将 image/webp
添加到 binaryMediaTypes
列表后,终端节点将收到二进制形式的 JPEG 文件。
有关 API Gateway 如何处理文本和二进制负载的详细信息,请参阅 API Gateway 中的内容类型转换。