API Gateway 中的内容类型转换 - Amazon API Gateway

API Gateway 中的内容类型转换

API 的 binaryMediaTypes、客户端请求中的标头和集成 contentHandling 属性的组合决定了 API Gateway 对负载编码的方式。

下表显示了 API Gateway 如何转换某个请求的 Content-Type 标头的特定配置的请求负载、RestApi 资源的 binaryMediaTypes 列表以及 Integration 资源的 contentHandling 属性值。

方法请求负载 请求 Content-Type 标头 binaryMediaTypes contentHandling 集成请求负载
文本数据 任意数据类型 未定义 未定义 UTF8 编码的字符串
文本数据 任意数据类型 未定义 CONVERT_TO_BINARY Base64 解码的二进制 blob
文本数据 任意数据类型 未定义 CONVERT_TO_TEXT UTF8 编码的字符串
文本数据 文本数据类型 包含匹配的媒体类型的集合 未定义 文本数据
文本数据 文本数据类型 包含匹配的媒体类型的集合 CONVERT_TO_BINARY Base64 解码的二进制 blob
文本数据 文本数据类型 包含匹配的媒体类型的集合 CONVERT_TO_TEXT 文本数据
二进制数据 二进制数据类型 包含匹配的媒体类型的集合 未定义 二进制数据
二进制数据 二进制数据类型 包含匹配的媒体类型的集合 CONVERT_TO_BINARY 二进制数据
二进制数据 二进制数据类型 包含匹配的媒体类型的集合 CONVERT_TO_TEXT Base64 编码的字符串

下表显示了 API Gateway 如何转换某个请求的 Accept 标头的特定配置的响应负载、RestApi 资源的 binaryMediaTypes 列表以及 IntegrationResponse 资源的 contentHandling 属性值。

重要

如果某个请求在其 Accept 标头中包含多个媒体类型,API Gateway 将只接受第一个 Accept 媒体类型。如果无法控制 Accept 媒体类型的顺序并且二进制内容的媒体类型不是列表中的第一个,则添加 API 的 binaryMediaTypes 列表中的第一个 Accept 媒体类型。API Gateway 将以二进制形式处理此列表中的所有内容类型。

例如,要在浏览器中使用 <img> 元素发送 JPEG 文件,该浏览器可能会在请求中发送 Accept:image/webp,image/*,*/*;q=0.8。将 image/webp 添加到 binaryMediaTypes 列表后,终端节点将收到二进制形式的 JPEG 文件。

集成响应负载 请求 Accept 标头 binaryMediaTypes contentHandling 方法响应负载
文本或二进制数据 文本类型 未定义 未定义 UTF8 编码的字符串
文本或二进制数据 文本类型 未定义 CONVERT_TO_BINARY Base64 解码的 blob
文本或二进制数据 文本类型 未定义 CONVERT_TO_TEXT UTF8 编码的字符串
文本数据 文本类型 包含匹配的媒体类型的集合 未定义 文本数据
文本数据 文本类型 包含匹配的媒体类型的集合 CONVERT_TO_BINARY Base64 解码的 blob
文本数据 文本类型 包含匹配的媒体类型的集合 CONVERT_TO_TEXT UTF8 编码的字符串
文本数据 二进制类型 包含匹配的媒体类型的集合 未定义 Base64 解码的 blob
文本数据 二进制类型 包含匹配的媒体类型的集合 CONVERT_TO_BINARY Base64 解码的 blob
文本数据 二进制类型 包含匹配的媒体类型的集合 CONVERT_TO_TEXT UTF8 编码的字符串
二进制数据 文本类型 包含匹配的媒体类型的集合 未定义 Base64 编码的字符串
二进制数据 文本类型 包含匹配的媒体类型的集合 CONVERT_TO_BINARY 二进制数据
二进制数据 文本类型 包含匹配的媒体类型的集合 CONVERT_TO_TEXT Base64 编码的字符串
二进制数据 二进制类型 包含匹配的媒体类型的集合 未定义 二进制数据
二进制数据 二进制类型 包含匹配的媒体类型的集合 CONVERT_TO_BINARY 二进制数据
二进制数据 二进制类型 包含匹配的媒体类型的集合 CONVERT_TO_TEXT Base64 编码的字符串

将文本负载转换为二进制 blob 时,API Gateway 假定文本数据是 Base64 编码的字符串,并将二进制数据作为 Base64 解码的 blob 输出。如果转换失败,它将返回一个 500 响应,指示出现 API 配置错误。尽管必须对 API 启用传递行为,但您不用提供此类转换的映射模板。

将二进制负载转换为文本字符串时,API Gateway 始终对二进制数据应用 Base64 编码。您可以定义此类负载的映射模板,但只能通过 $input.body 访问映射模板中的 Base64 编码字符串,如映射模板示例的以下摘录中所示。

{ "data": "$input.body" }

要直接传递二进制负载而不作修改,必须对 API 启用传递行为