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 启用传递行为。
