使用API閘道啟用二進位支援 REST API

下列工作顯示如何使用API閘道RESTAPI呼叫啟用二進位支援。

將支援的二進位媒體類型新增並更新至 API

若要讓 API Gateway 支援新的二進位媒體類型，您必須將二進位媒體類型新增至RestApi資源binaryMediaTypes清單。例如，若要讓 API Gateway 處理JPEG影像，請向RestApi資源提交PATCH要求：

PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/image~1jpeg"
  } 
 ]
}

屬於path屬性值image/jpeg一部分的MIME類型規範被轉義為image~1jpeg。

若要更新支援的二進位媒體類型，請從 binaryMediaTypes 資源的 RestApi 清單中取代或移除媒體類型。例如，要將二進制支持從JPEG文件更改為原始字節，請向RestApi資源提交PATCH請求，如下所示：

PATCH /restapis/<restapi_id>

{
  "patchOperations" : [{
    "op" : "replace",
    "path" : "/binaryMediaTypes/image~1jpeg",
    "value" : "application/octet-stream"
  },
  {
    "op" : "remove",
    "path" : "/binaryMediaTypes/image~1jpeg"
  }]
}

設定請求承載轉換

如果端點需要二進位輸入，請將 contentHandling 資源的 Integration 屬性設定為 CONVERT_TO_BINARY。若要執行這項操作，請提交 PATCH 請求，如下所示：

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration

{
  "patchOperations" : [ {
    "op" : "replace",
    "path" : "/contentHandling",
    "value" : "CONVERT_TO_BINARY"
  }]
}

設定回應承載轉換

如果用戶端接受二進位 Blob 格式的結果，而不是從端點傳回的 Base64 編碼承載，將 IntegrationResponse 資源的 contentHandling 屬性設定為 CONVERT_TO_BINARY。若要這樣做，請提交 PATCH 請求，如下所示：

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code>

{
  "patchOperations" : [ {
    "op" : "replace",
    "path" : "/contentHandling",
    "value" : "CONVERT_TO_BINARY"
  }]
}

將二進位資料轉換成文字資料

若要透過API閘道將二進位資料作為輸入的JSON內容傳送給 AWS Lambda Kinesis，請執行下列動作：

1. 將的新二進位媒體類型新API增application/octet-stream至的binaryMediaTypes清單，以啟用的二進位裝載支援。API

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream"
     } 
    ]
   }
   

2. 在Integration資源的contentHandling屬性CONVERT_TO_TEXT上進行設定，並提供對應範本，以將 Base64 編碼的二進位資料字串指派給屬性。JSON在下列範例中，JSON屬性為body並$input.body包含 base64 編碼的字串。

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_TEXT"
       },
       {
         "op" : "add",
         "path" : "/requestTemplates/application~1octet-stream",
         "value" : "{\"body\": \"$input.body\"}"
       }
     ]
   }

將文字資料轉換成二進位承載

假設 Lambda 函數會傳回 Base64 編碼字串格式的影像檔。若要透過 API Gateway 將此二進位輸出傳遞給用戶端，請執行下列動作：

1. 如果清單中尚未binaryMediaTypes列出的二進位媒體類型application/octet-stream，請加入的二進位媒體類型來更新清單。API

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream",
     }]
   }
   

2. 將 contentHandling 資源上的 Integration 屬性設定為 CONVERT_TO_BINARY。請勿定義對應範本。如果您未定義對應範本，API閘道會叫用傳遞範本，將 base64 解碼的二進位 blob 作為映像檔傳回給用戶端。

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code>
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_BINARY"
       }
     ]
   }

傳遞二進位承載

若要使用API閘道將映像存放在 Amazon S3 儲存貯體中，請執行下列動作：

1. 如果binaryMediaTypes清單中尚未出現的二進位媒體類型application/octet-stream，請加入的二進位媒體類型來更新清單。API

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream"
     }
    ]
   }
   

2. 在 contentHandling 資源的 Integration 屬性上設定 CONVERT_TO_BINARY。將 WHEN_NO_MATCH 設定為 passthroughBehavior 屬性值，而不需要定義對應範本。這可讓API閘道呼叫傳遞範本。

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_BINARY"
       },
       {
         "op" : "replace",
         "path" : "/passthroughBehaviors",
         "value" : "WHEN_NO_MATCH"
       }
     ]
   }