Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon 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 标头中指定的类型。