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

# 使用 API Gateway REST API 啟用二進位支援
<a name="api-gateway-payload-encodings-configure-with-control-service-api"></a>

下列作業示範如何使用 API Gateway REST API 呼叫來啟用二進位支援。

**Topics**
+ [將支援的二進位媒體類型新增與更新至 API](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [設定請求承載轉換](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [設定回應承載轉換](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [將二進位資料轉換成文字資料](#api-gateway-payload-encodings-convert-binary-to-string)
+ [將文字資料轉換成二進位承載](#api-gateway-payload-encodings-convert-string-to-binary)
+ [傳遞二進位承載](#api-gateway-payload-encodings-pass-binary-as-is)

## 將支援的二進位媒體類型新增與更新至 API
<a name="api-gateway-payload-encodings-setup-with-api-set-encodings-map"></a>

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

```
PATCH /restapis/<restapi_id>

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

`image/jpeg` 的 MIME 類型規格是 `path` 屬性值的一部分，因此會逸出為 `image~1jpeg`。

若要更新支援的二進位媒體類型，請從 `binaryMediaTypes` 資源的 `RestApi` 清單中取代或移除媒體類型。例如，若要將二進位支援從 JPEG 檔案變更為原始位元組，請對 `PATCH` 資源提交 `RestApi` 請求，如下所示。

```
PATCH /restapis/<restapi_id>

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

## 設定請求承載轉換
<a name="api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding"></a>

如果端點需要二進位輸入，請將 `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"
  }]
}
```

## 設定回應承載轉換
<a name="api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding"></a>

如果用戶端接受二進位 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"
  }]
}
```

## 將二進位資料轉換成文字資料
<a name="api-gateway-payload-encodings-convert-binary-to-string"></a>

若要透過 API Gateway 將二進位資料做為輸入 AWS Lambda 或 Kinesis 的 JSON 屬性傳送，請執行下列動作：

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

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

1. 在 `CONVERT_TO_TEXT` 資源的 `contentHandling` 屬性上設定 `Integration`，並提供對應範本，以將二進位資料的 Base64 編碼字串指派給 JSON 屬性。在下列範例中，JSON 屬性是持有 Base64 編碼字串的 `body` 與 `$input.body`。

   ```
   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\"}"
       }
     ]
   }
   ```

## 將文字資料轉換成二進位承載
<a name="api-gateway-payload-encodings-convert-string-to-binary"></a>

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

1. 新增 `binaryMediaTypes` 的二進位媒體類型 (如果尚未在清單中)，以更新 API 的 `application/octet-stream` 清單。

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

1.  將 `contentHandling` 資源上的 `Integration` 屬性設定為 `CONVERT_TO_BINARY`。請勿定義對應範本。如果您未定義映射範本，API Gateway 可呼叫傳遞範本，將 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"
       }
     ]
   }
   ```

## 傳遞二進位承載
<a name="api-gateway-payload-encodings-pass-binary-as-is"></a>

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

1. 新增 `binaryMediaTypes` 的二進位媒體類型 (如果尚未在清單中)，以更新 API 的 `application/octet-stream` 清單。

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

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

   ```
   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"
       }
     ]
   }
   ```