API Gateway 中 REST API 的二進位媒體類型 - Amazon API Gateway
AWS Lambda 代理整合非代理伺服器整合

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

API Gateway 中 REST API 的二進位媒體類型

在 API Gateway 中，API 請求與回應可以有文字或二進位承載。文字承載是 UTF-8 編碼的 JSON 字串。二進位承載是文字承載以外的任何項目。例如，二進位承載可以是 JPEG 檔案、GZip 檔案或 XML 檔案。支援二進位媒體所需的 API 組態取決於您的 API 是否使用代理或非代理整合。

如果您使用代理整合與承載回應串流，則不需要設定二進位媒體類型。如需詳細資訊，請參閱在 API Gateway 中串流代理整合的整合回應。

AWS Lambda 代理整合

若要處理 AWS Lambda 代理整合的二進位承載，您必須對函數的回應進行 base64 編碼。您也必須為 API 配置 binaryMediaTypes。您的 API binaryMediaTypes 組態是 API 視為二進位資料的內容類型列表。範例二進位媒體類型包括 image/png 或 application/octet-stream。您可以使用萬用字元 (*) 來涵蓋多種媒體類型。

API Gateway 會使用來自用戶端的第一個 Accept 標頭來判斷回應是否應該傳回二進位媒體。若要在無法控制 Accept 標頭值的順序 (例如來自瀏覽器的請求) 時傳回二進位媒體，請將 API 的二進位媒體類型設定為 */*。

如需範例程式碼，請參閱 在 API Gateway 中從 Lambda 代理整合傳回二進位媒體。

如果您使用 Lambda 代理整合與承載回應串流，則不需要設定二進位媒體類型。如需詳細資訊，請參閱在 API Gateway 中設定 Lambda 代理整合與承載回應串流。

非代理伺服器整合

若要處理非代理整合的二進位承載，您可以將媒體類型新增至 RestApi 資源的 binaryMediaTypes 清單。您的 API binaryMediaTypes 組態是 API 視為二進位資料的內容類型列表。或者，您可以在 Integration 與 IntegrationResponse 資源上設定 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 資源上的 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 中的內容類型轉換。