本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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 的 `binaryMediaTypes` 清單中新增第一個 `Accept` 媒體類型。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)。