本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# coreHTTP 基本 Amazon S3 上传演示
**重要**
该演示托管在已弃用的 Amazon-FreeRTOS 存储库中。当您创建新项目时，我们建议[从此处开始](freertos-getting-started-modular.md)。如果您已经有一个基于现已弃用的 Amazon-FreeRTOS 存储库的 FreeRTOS 项目，请参阅 [Amazon-FreeRTOS Github 存储库迁移指南](github-repo-migration.md)。
## 简介
此示例演示如何将 PUT 请求发送到 Amazon Simple Storage Service (Amazon S3) HTTP 服务器以及上传一个小文件。完成上传后，它还会执行 GET 请求来验证文件大小。此示例使用一个[网络传输接口](https://freertos.org/network-interface.html)，该接口使用 mbedTLS 在运行 coreHTTP 的 IoT 设备客户端与 Amazon S3 HTTP 服务器之间建立双向身份验证的连接。
**注意**
要设置和运行 FreeRTOS 演示，请按照[开始使用 FreeRTOS](freertos-getting-started.md)中的步骤操作。
### 单线程与多线程
coreMQTT 有两种使用模式，即*单线程*和*多线程*（多任务处理）。尽管本节中的演示在线程中运行 HTTP 库，但它实际上演示了如何在单线程环境中使用 coreHTTP。此演示中只有一个任务使用 HTTP API。尽管单线程应用程序必须重复调用 HTTP 库，但多线程应用程序可以在后台的代理（或进程守护程序）任务中发送 HTTP 请求。
## 源代码组织
演示源文件已命名`http_demo_s3_upload.c`，可以在`freertos/demos/coreHTTP/`目录和[ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_upload.c)网站上找到。
## 配置 Amazon S3 HTTP 服务器连接
此演示使用预签名 URL 连接到 Amazon S3 HTTP 服务器并授权访问要下载的对象。Amazon S3 HTTP 服务器的 TLS 连接仅使用服务器身份验证。在应用程序级别，使用预签名 URL 查询中的参数对对象的访问进行身份验证。请按照以下步骤配置与 AWS的连接。
1. 设置 AWS 账户：
1. 如果您还没有，[请创建一个 AWS 账户](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/)。
1. 账户和权限是使用 AWS Identity and Access Management (IAM) 设置的。您可以使用 IAM 来管理账户中各用户的权限。默认情况下，用户只有在根所有者授予权限后才拥有权限。
1. 要向您的 AWS 账户添加用户，请参阅 [IAM 用户指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/)。
1. 向您的 AWS 账户授予访问FreeRTOS的权限， AWS IoT 并通过添加此政策：
+ 亚马逊 3 FullAccess
1. 按照*《Amazon Simple Storage Service 用户指南》*的[如何创建 S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html)中的步骤，在 Amazon S3 中创建一个存储桶。
1. 按照[如何将文件和文件夹上传至 S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html)中的步骤，将文件上传到 Amazon S3 存储桶。
1. 使用 `FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/presigned_urls_gen.py` 文件中的脚本生成预签名 URL。
有关使用说明，请参阅 `FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/README.md` 文件。
## 功能
首先，此演示使用 TLS 服务器身份验证连接到 Amazon S3 HTTP 服务器。然后，它会创建一个 HTTP 请求来上传在 `democonfigDEMO_HTTP_UPLOAD_DATA` 中指定的数据。上传文件后，它会通过请求文件的大小来检查文件是否上传成功。该演示的源代码可以在[GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_upload.c)网站上找到。
### 连接到 Amazon S3 HTTP 服务器
该[ connectToServerWithBackoffRetries](https://github.com/aws/amazon-freertos/blob/main/demos/common/http_demo_helpers/http_demo_utils.c#L131-L170)函数尝试与 HTTP 服务器建立 TCP 连接。如果连接失败，则会在超时后重试。超时值呈指数级增长，直到达到最大尝试次数或最大超时值。如果在配置的尝试次数后仍无法建立与服务器的 TCP 连接，则 `connectToServerWithBackoffRetries` 函数将返回失败状态。
`prvConnectToServer` 函数演示如何仅使用服务器身份验证来建立与 Amazon S3 HTTP 服务器的连接。它使用在 `FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/using_mbedtls/using_mbedtls.c` 文件中实现的基于 mbedTLS 的传输接口。的定义`prvConnectToServer`可以在[GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_upload.c#L306-L366)网站上找到。
### 上传数据
`prvUploadS3ObjectFile` 函数演示如何创建 PUT 请求和指定要上传的文件。上传文件的 Amazon S3 存储桶和要上传的文件名在预签名 URL 中指定。为了节省内存，请求标头和接收响应使用相同的缓冲区。使用 `HTTPClient_Send` API 函数同步接收响应。Amazon S3 HTTP 服务器需要一个 `200 OK` 响应状态代码。任何其他状态代码均为错误。
的源代码`prvUploadS3ObjectFile()`可以在[ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_upload.c#L539-L632)网站上找到。
### 验证上传
`prvVerifyS3ObjectFileSize` 函数调用 `prvGetS3ObjectFileSize` 来检索 S3 存储桶中对象的大小。目前，Amazon S3 HTTP 服务器不支持使用预签名 URL 的 HEAD 请求，因此请求第 0 个字节。文件的大小包含在响应的 `Content-Range` 标头字段中。服务器的预期响应为 `206 Partial Content`。任何其他响应状态代码均为错误。
的源代码`prvGetS3ObjectFileSize()`可以在[ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_upload.c#L370-L535)网站上找到。