如何通过 API Gateway 将图像或 PDF 文件上传到 Amazon S3？

简短描述

要使用 API Gateway 将图像或 PDF 作为二进制文件上传到 Amazon S3 存储桶，请激活二进制支持。

要授予 API Gateway 访问您的 S3 存储桶的权限，请创建 AWS Identity and Access Management (IAM) 角色。该 IAM 角色必须包含 API Gateway 在您的 S3 存储桶上执行 PutObject 和 GetObject 操作的权限。

解决方法

**注意：**如果您在运行 AWS 命令行界面 (AWS CLI) 命令时收到错误，请参阅 AWS CLI 错误故障排除。此外，请确保您使用的是最新版本的 AWS CLI。

为 API Gateway 创建 IAM 角色

完成以下步骤：

1. 打开 IAM 控制台。
2. 在导航窗格中，选择 Roles（角色）。
3. 选择 Create role（创建角色）。
4. 对于 Trusted entity type（可信实体类型），选择 AWS service（AWS 服务）。
5. 对于 Service or use case（服务或使用案例），选择 API Gateway。
6. 对于 Use case（使用案例），选择 API Gateway。
7. 选择 Next（下一步）。然后，再次选择 Next（下一步）。
8. 对于 Role name（角色名称），输入您的策略的名称。例如，输入 api-gateway-upload-to-s3。
9. （可选）要向 IAM 角色添加标签，请选择 Add new tag（添加新标签）。
10. 选择 Create role（创建角色）。

创建 IAM 策略并将其附加到 API Gateway 角色

完成以下步骤：

1. 打开 IAM 控制台。
2. 在导航窗格中，选择 Roles（角色）。
3. 在搜索框中，输入 API Gateway 的 IAM 角色的名称，然后从 Role name（角色名称）列中选择该角色。
4. 在 Permissions policies（权限策略）部分中，选择 Add permissions（添加权限），然后选择 Create inline policy（创建内联策略）。
5. 在 Visual editor（可视化编辑器）选项卡的 Select a service（选择服务）部分中，选择 Choose a service（选择服务）。
6. 输入 S3，然后选择 S3。
7. 在 Actions allowed（允许的操作）下，输入 PutObject，然后选择 PutObject。输入 GetObject，然后选择 GetObject。
8. 展开 Resources（资源），然后选择 Specific（特定）。
9. 选择 Add ARN（添加 ARN）。
10. 对于 Resource bucket name（资源存储桶名称），输入您的存储桶的名称。包含前缀（如果适用）。
11. 对于 Resource object name（资源对象名称），输入对象名称。
    **注意：**存储桶名称指定上传文件的位置。对象名称指定该对象必须遵循的策略调整模式。有关详细信息，请参阅通用存储桶命名规则和 Amazon S3 对象概述。
12. 选择 Add ARNs（添加 ARN）。
13. 选择 Next（下一步）。
14. 对于 Name（名称），输入您的策略的名称。
15. 选择 Create policy（创建策略）。

创建 API Gateway REST API

要创建 API 来发送您的请求，请完成以下步骤：

1. 打开 API Gateway 控制台。
2. 在导航窗格中，选择 APIs。
3. 选择 Create API（创建 API）。
4. 在 Choose an API type（选择 API 类型）页面上，对于 REST API，选择 Build（构建）。
5. 对于 API Name（API 名称），输入您的 API 的名称，然后选择 Create API（创建 API）。

要为您的 API 创建资源，请完成以下步骤：

1. 在 API 页面的 Resources（资源）面板中，选择 /。
2. 选择 Create resource（创建资源）。
3. 对于 Resource path（资源路径），选择 /。
4. 对于 Resource name（资源名称），输入 {bucket}。
   注意： Bucket 是用户可以更改的变量名称。
5. 选择 Create resource（创建资源）。
6. 在 Resources（资源）面板中，选择 /{bucket} 资源。
7. 选择 Create resource（创建资源）。
8. 对于 Resource path（资源路径），选择 /{bucket}/。
9. 对于 Resource name（资源名称），输入 {proxy+}。
10. 选择 Create resource（创建资源）。

要为您的 API 创建 PUT 方法来上传图像或 PDF 文件，请完成以下步骤：

1. 在 Methods（方法）部分中，选择 Create method（创建方法）。
2. 对于 Method type（方法类型），选择 PUT。
3. 在 Integration type（集成类型）下，选择 AWS service（AWS 服务）。
4. 对于 AWS Region（AWS 区域），选择 us-east-1，或 Bucket properties（存储桶属性）页面上的 AWS 区域。
5. 对于 AWS service（AWS 服务），选择 Simple Storage Service (S3)。
6. 保持 AWS subdomain（AWS 子域）为空。
7. 对于 HTTP method（HTTP 方法），选择 PUT。
8. 对于 Action type（操作类型），选择 Use path override（使用路径覆盖）。
9. 对于 Path override（路径覆盖），输入 {bucket}/{proxy}。
10. 对于 Execution role（执行角色），输入 IAM 角色的 Amazon 资源名称 (ARN)。
11. 对于 Content handling（内容处理），选择 Passthrough（直通）。
12. 选择 Create method（创建方法）。

为 PUT 方法配置参数映射

完成以下步骤：

1. 在 API 页面的 Resources（资源）面板中，选择 PUT。
2. 选择 Integration request（集成请求），然后选择 Edit（编辑）。
3. 展开 URL path parameters（URL 路径参数）。
4. 选择 Add path parameter（添加路径参数）。
5. 对于 Name（名称），输入 bucket。
6. 对于 Mapped from（映射自），输入 method.request.path.bucket。
7. 重复步骤 4–6，但在步骤 5 中，将 Name（名称）设置为 key。在步骤 6 中，将 Mapped from（映射自）设置为 method.request.path.proxy。
8. 选择 Save（保存）。

为您的 API 创建 GET 方法来检索图像

完成以下步骤：

1. 在 API 页面的 Resources（资源）面板中，选择 /{object}。
2. 在 Methods（方法）部分中，选择 Create method（创建方法）。
3. 对于 Method type（方法类型），选择 GET。
4. 在 Integration type（集成类型）下，选择 AWS service（AWS 服务）。
5. 对于 AWS Region（AWS 区域），选择 us-east-1，或 Bucket properties（存储桶属性）页面上的区域。
6. 对于 AWS service（AWS 服务），选择 Simple Storage Service (S3)。
7. 保持 AWS subdomain（AWS 子域）为空。
8. 对于 HTTP method（HTTP 方法），选择 GET。
9. 对于 Action type（操作类型），选择 Use path override（使用路径覆盖）。
10. 对于 Path override（路径覆盖），输入 {bucket}/{key}。
11. 对于 Execution role（执行角色），输入 IAM 角色的 ARN。
12. 对于 Content handling（内容处理），选择 Passthrough（直通）。
13. 选择 Create method（创建方法）。

为 GET 方法配置参数映射

完成以下步骤：

1. 在 API 页面的 Resources（资源）面板中，选择 GET。
2. 选择 Integration request（集成请求），然后选择 Edit（编辑）。
3. 展开 URL path parameters（URL 路径参数）。
4. 选择 Add path parameters（添加路径参数）。
5. 对于 Name（名称），输入 bucket。
6. 对于 Mapped from（映射自），输入 method.request.path.folder。
7. 重复步骤 4–6，但在步骤 5 中，将 Name（名称）设置为 key。在步骤 6 中，将 Mapped from（映射自）设置为 method.request.path.object。
8. 选择 Save（保存）。

设置响应映射以在浏览器中查看图像或 PDF

完成以下步骤：

1. 在 API 页面的 Resources（资源）面板中，选择 GET。
2. 选择 Method response（方法响应）。
3. 对于 Response 200（响应 200），选择 Edit（编辑）。
4. 在 Response body（响应正文）下，删除 application/json。
5. 在 Header name（标头名称）下，选择 Add header（添加标头）。
6. 对于 Name（名称），输入 content-type。
7. 选择 Save（保存）。
8. 选择 Integration response（集成响应），然后选择 Edit（编辑）。
9. 对于 Method response status code（方法响应状态代码）200，对于图像文件，输入 image/jpeg，对于 PDF 文件，输入 application/pdf。
10. 选择 Save（保存）。

为 API 设置二进制媒体类型

完成以下步骤：

1. 在 API 页面的导航窗格中，选择 API settings（API 设置）。
2. 在 Binary media types（二进制媒体类型）部分中，选择 Manage media types（管理媒体类型）。
3. 选择 Add binary media type（添加二进制媒体类型），然后在文本框中添加 / 字符串。
   **注意：**不要给这个字符串加上引号。您可以将通配符替换为特定的多用途互联网邮件扩展 (MIME) 类型，以将其作为二进制媒体类型进行管理。例如，要让 API Gateway 将 JPEG 图像作为二进制媒体类型进行管理，请选择 image/jpeg。如果您添加 */*，则 API Gateway 会将所有媒体类型都作为二进制媒体类型进行管理。
4. 选择 Save changes（保存更改）。

使用 API 的二进制设置解决 CORS 错误

**注意：**如果您在 Web 应用程序中使用 PUT 和 GET API，则可能会收到跨源资源共享 (CORS) 错误。有关详细信息，请参阅 Mozilla 网站上的 CORS 错误。

要在启用二进制设置的情况下解决 CORS 错误，请完成以下步骤：

1. 打开 API Gateway 控制台。
2. 选择您的 API。
3. 在 API 页面的 Resources（资源）面板中，选择 /{object}。
4. 选择 Enable CORS（启用 CORS）。
5. 对于 Gateway responses（网关响应），选择 Default 4xx（默认 4xx）、Default 5xx（默认 5xx）。
6. 对于 Access-Control-Allow-Methods，选择 GET 和 PUT。
7. 选择 Save（保存）。
8. 运行 update-integration AWS CLI 命令：

   aws apigateway update-integration --rest-api-id API_ID --resource-id RESOURCE_id --http-method OPTIONS --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' --region AWS_REGION

   **注意：**请将 rest-api-id 替换为您的 REST API ID，将 RESOURCE_id 替换为您的资源 ID，将 AWS_REGION 替换为您的区域。
9. 运行 update-integration-response 命令：

   aws apigateway update-integration-response --rest-api-id API_ID --resource-id RESOURCE_id --http-method OPTIONS --status-code 200 --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' --region AWS_REGION

   **注意：**请将 rest-api-id 替换为您的 REST API ID，将 RESOURCE_id 替换为您的资源 ID，将 AWS_REGION 替换为您的区域。要让 API Gateway 运行选项请求，必须依次运行 update-integration 和 update-integration-response 命令。

部署 API

完成以下步骤：

1. 在 API 页面的导航窗格中，选择 Resources（资源）。
2. 选择 Deploy API（部署 API）。
3. 在 Deploy API（部署 API）窗口中，对于 Stage（阶段），选择 *New stage*。
4. 对于 Stage name（阶段名称），输入 v1。
5. 选择 Deploy（部署）。
6. 在导航窗格中，选择 Stages（阶段）。
7. 选择 v1 阶段。
8. 记下出现的调用 URL。

有关详细信息，请参阅在 API Gateway 中部署 REST API。

调用 REST API 以将图像文件上传到 Amazon S3

完成以下步骤：

1. 将存储桶名称和对象的文件名添加到 API 的调用 URL 中。
2. 使用您的首选客户端发出 PUT HTTP 请求。例如，您可以下载和使用 Postman。有关详细信息，请参阅 Postman 网站上的 Download Postman（下载 Postman）。
3. 选择 Body（正文），然后选择 binary（二进制）。出现 Select file 按钮时，选择要上传的本地文件。

以下是一个 curl 命令示例，您可以运行该命令来发出 PUT HTTP 请求，以上传图像或 PDF：

curl -i --location --request PUT 'https://abc12345.execute-api.us-west-2.amazonaws.com/v1/testfolder/testimage.jpeg' --header 'Content-Type: text/plain' --data-binary '@/Path/to/file/image.jpeg'

**注意：**请将 abc12345 替换为您的 API ID，将 testfolder 替换为您的 S3 存储桶，将 testimage.jpeg 替换为您上传的本地文件。

如果您在二进制媒体类型列表中包含 */*，则可以通过发出 PUT 请求来上传文件。如果您在二进制媒体类型列表中包含 image.jpeg，请在 PUT 请求中添加 Content-Type 标头，并将其设置为 image/jpeg。因为 Web 浏览器会发出 GET 请求，所以您可以使用相同的 URL 在 Web 浏览器中查看图像或 PDF。

相关信息

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

使用 API Gateway 控制台对资源启用 CORS