使用 API Gateway REST API 启用二进制支持 - Amazon API Gateway
向 API 添加和更新受支持的二进制媒体类型配置请求负载转换配置响应负载转换将二进制数据转换为文本数据将文本数据转换为二进制负载传递二进制负载

使用 API Gateway REST API 启用二进制支持

以下任务演示如何使用 API Gateway REST API 调用来启用二进制支持。

向 API 添加和更新受支持的二进制媒体类型

要允许 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 文件更改为原始字节，请向 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 Gateway 将二进制数据作为输入的 JSON 属性发送到 AWS Lambda 或 Kinesis，请执行以下操作：

  1. 通过将新的二进制媒体类型 application/octet-stream 添加到 API 的 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 (如果该类型尚不在列表中) 来更新 API 的 application/octet-stream 列表。

    PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/application~1octet-stream",
  }]
}

  2. 将 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"
    }
  ]
}

传递二进制负载

要使用 API Gateway 将图像存储在 Amazon S3 存储桶中，请执行以下操作：

  1. 通过添加二进制媒体类型 binaryMediaTypes（如果该类型尚不在列表中）来更新 API 的 application/octet-stream 列表。

    PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/application~1octet-stream"
  }
 ]
}

  2. 在 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"
    }
  ]
}