Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

支持 API Gateway 中的二进制负载

在 API Gateway 中,API 请求和响应可能包含文本或二进制负载。文本负载是 UTF-8 编码的 JSON 字符串,二进制负载是文本负载以外的负载。例如,二进制负载可以是 JPEG 文件、GZip 文件或 XML 文件。

默认情况下,API Gateway 会将消息正文作为文本负载处理并应用任何预配置的映射模板以转换 JSON 字符串。如果未指定映射模板,在 API 方法支持传递行为的前提下,API Gateway 可以将文本负载不作修改地传入或传出集成终端节点。对于二进制负载,API Gateway 只会按原样传递消息。

要使 API Gateway 传递二进制负载,您应将媒体类型添加到 RestApi 资源的 binaryMediaTypes 列表,或者设置 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 属性设置为 CONVERT_TO_BINARY 以将请求负载从 Base64 编码的字符串转换为其二进制 blob,或者将该属性设置为 CONVERT_TO_TEXT 以将请求负载从二进制 blob 转换为 Base64 编码的字符串。如果未定义此属性,API Gateway 将直接传递负载而不作修改。当 Content-Type 标头值匹配其中一个 binaryMediaTypes 条目并且您对 API 启用了传递行为时,会出现这种情况。

  • IntegrationResponse 资源的 contentHandling 属性设置为 CONVERT_TO_BINARY 以将响应负载从 Base64 编码的字符串转换为其二进制 blob,或者将该属性设置为 CONVERT_TO_TEXT 以将响应负载从二进制 blob 转换为 Base64 编码的字符串。如果未定义 contentHandling,并且响应的 Content-Type 标头和原始请求的 Accept 标头与 binaryMediaTypes 列表中的某个条目匹配,则 API Gateway 会直接传递该正文。当 Content-Type 标头与 Accept 标头相同时会出现这种情况;否则,API Gateway 将响应正文转换为在 Accept 标头中指定的类型。

提示

如果某个请求的 Accept 标头包含多个媒体类型,API Gateway 将只接受第一个 Accept 媒体类型。如果无法控制 Accept 媒体类型的顺序并且二进制内容的媒体类型不是列表中的第一个,您可以添加 API 的 binaryMediaTypes 列表中的第一个 Accept 媒体类型,API Gateway 将您的内容以二进制形式返回。例如,要在浏览器中使用 <img> 元素发送 JPEG 文件,该浏览器可能会在请求中发送 Accept:image/webp,image/*,*/*;q=0.8。将 image/webp 添加到 binaryMediaTypes 列表后,终端节点将收到二进制形式的 JPEG 文件。