针对 API Gateway 中的 REST API 的二进制媒体类型 - Amazon API Gateway

针对 API Gateway 中的 REST API 的二进制媒体类型

在 API Gateway 中,API 请求和响应具有文本或二进制负载。文本负载是 UTF-8 编码的 JSON 字符串。二进制负载是文本负载以外的负载。例如,二进制负载可以是 JPEG 文件、GZip 文件或 XML 文件。支持二进制媒体所需的 API 配置取决于 API 是使用代理集成还是非代理集成。

AWS Lambda 代理集成

要处理 AWS Lambda 代理集成的二进制负载,您必须对函数的响应进行 base64 编码。还必须为 API 配置 binaryMediaTypes。API 的 binaryMediaTypes 配置是 API 视为二进制数据的内容类型的列表。示例二进制媒体类型包括 image/pngapplication/octet-stream。您可以使用通配符 (*) 来涵盖多种媒体类型。例如,*/* 包括所有内容类型。

有关代码示例,请参阅 从 API Gateway 中的 Lambda 代理集成返回二进制媒体

非代理集成

要处理非代理集成的二进制负载,请将媒体类型添加到 RestApi 资源的 binaryMediaTypes 列表中。API 的 binaryMediaTypes 配置是 API 视为二进制数据的内容类型的列表。或者,您可以设置 IntegrationIntegrationResponse 资源上的 contentHandling 属性。contentHandling 值可以是 CONVERT_TO_BINARYCONVERT_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 中的内容类型转换