# 针对 API Gateway 中的 REST API 的二进制媒体类型
<a name="api-gateway-payload-encodings"></a>

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

如果您使用带有效载荷响应流式传输的代理集成，则无需配置二进制媒体类型。有关更多信息，请参阅 [在 API Gateway 中流式传输代理集成的集成响应](response-transfer-mode.md)。

## AWS Lambda 代理集成
<a name="api-gateway-payload-encodings-proxy"></a>

要处理 AWS Lambda 代理集成的二进制负载，您必须对函数的响应进行 base64 编码。还必须为 API 配置 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)。API 的 `binaryMediaTypes` 配置是 API 视为二进制数据的内容类型的列表。示例二进制媒体类型包括 `image/png` 或 `application/octet-stream`。您可以使用通配符 (`*`) 来涵盖多种媒体类型。

API Gateway 使用来自客户端的第一个 `Accept` 标头来确定响应是否应返回二进制媒体。要在无法控制 `Accept` 标头值（如浏览器中的请求）的顺序时返回二进制媒体，请将 API 的二进制媒体类型设置为 `*/*`。

有关代码示例，请参阅 [从 API Gateway 中的 Lambda 代理集成返回二进制媒体](lambda-proxy-binary-media.md)。

如果您使用带有效载荷响应流式传输的 Lambda 代理集成，则无需配置二进制媒体类型。有关更多信息，请参阅 [在 API Gateway 中设置采用有效载荷响应流式传输的 Lambda 代理集成](response-transfer-mode-lambda.md)。

## 非代理集成
<a name="api-gateway-payload-encodings-non-proxy"></a>

要处理非代理集成的二进制负载，请将媒体类型添加到 `RestApi` 资源的 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) 列表中。API 的 `binaryMediaTypes` 配置是 API 视为二进制数据的内容类型的列表。或者，您可以设置 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 和 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 资源上的 [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) 属性。`contentHandling` 值可以是 `CONVERT_TO_BINARY`、`CONVERT_TO_TEXT` 或未定义。

**注意**  
对于 `MOCK` 或私有集成，AWS 管理控制台中不支持设置 `contentHandling` 属性。您必须使用 AWS CLI、CloudFormation 或 SDK 来设置 `contentHandling` 属性。

根据 `contentHandling` 值，以及响应的 `Content-Type` 标头或传入请求的 `Accept` 标头是否匹配 `binaryMediaTypes` 列表中的某个条目，API Gateway 可以将原始二进制字节编码为 Base64 编码的字符串，将 Base64 编码的字符串解码回其原始字节，或者直接传递正文而不作修改。

您必须按如下方式配置 API，以对 API Gateway 中 API 的二进制负载提供支持：
+ 将所需的二进制媒体类型添加到 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 资源的 `binaryMediaTypes` 列表中。如果未定义此属性和 `contentHandling` 属性，会将负载作为 UTF-8 编码的 JSON 字符串进行处理。
+ 解决 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 资源的 `contentHandling` 属性。
  + 要将请求负载从 base64 编码的字符串转换为其二进制 blob，请将此属性设置为 `CONVERT_TO_BINARY`。
  + 要将请求负载从二进制 blob 转换为 base64 编码的字符串，请将此属性设置为 `CONVERT_TO_TEXT`。
  + 要在不修改的情况下传递负载，请将此属性保留为未定义。要在不修改的情况下传递二进制负载，还必须确保 `Content-Type` 与其中一个 `binaryMediaTypes` 条目匹配，并且已为 API 启用[传递行为](integration-passthrough-behaviors.md)。
+ 设置 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 资源的 `contentHandling` 属性。`contentHandling` 属性、客户端请求中的 `Accept` 标头以及 API 的 `binaryMediaTypes` 组合决定了 API Gateway 如何处理内容类型转换。有关详细信息，请参阅[API Gateway 中的内容类型转换](api-gateway-payload-encodings-workflow.md)。

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

有关 API Gateway 如何处理文本和二进制负载的详细信息，请参阅 [API Gateway 中的内容类型转换](api-gateway-payload-encodings-workflow.md)。