coreHTTP 基础 S3 下载演示

• 本页内容：
  • 单线程 VS 多线程
  • 简介
  • 源代码组织
  • 构建说明
  • 配置
  • 配置 AWS S3 HTTP 服务器连接
  • 功能
  • 连接到 AWS S3 HTTP 服务器
  • 创建范围请求
  • 发送范围请求和接收响应

单线程 VS 多线程

coreHTTP 有两种使用模式，一种是单线程式的，另一种是多线程式的 （多任务）。虽然此页面上的演示在线程中运行 HTTP 库，但它实际上是在演示如何在单线程环境（只有一个任务在演示中使用 HTTP API ）中使用 coreHTTP。单线程应用程序必须重复调用 HTTP 库，而多线程应用程序则可以在 agent（或守护进程）任务的后台执行发送 HTTP 请求。
 

简介

本演示展示如何使用范围请求从 AWS S3 http 服务器下载文件。使用 HTTPClient_AddRangeHeader() 创建 HTTP 请求时，coreHTTP API 原生支持范围请求。对于微控制器环境， 强烈建议使用范围请求——使用方法是以不同范围下载大文件，而不是在单个请求中下载，这样可以在不阻塞网络套接字的情况下处理文件的每个部分。范围请求降低了出现丢弃数据包的风险，这些数据包需要在 TCP 连接上重新传输，因此这有助于优化设备的功耗。

此示例使用网络传输接口，该接口使用 mbedTLS 在运行 coreHTTP 的 IoT 设备客户端和 AWS S3 HTTP 服务器之间建立相互身份验证的连接。

core HTTP S3 下载演示项目使用 FreeRTOS Windows 移植，因此 您可以利用 Windows上的 免费社区版 Visual Studios 来构建和评估此移植，无需使用任何特定的 MCU 硬件。
 

源代码组织

演示项目名为 http_s3_download_demo.sln， 位于 FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/HTTP_S3_Download （在 FreeRTOS 主下载中）（也可在 GitHub 上的 coreHTTP_Windows_Simulator 存储库中找到）。
 

构建演示项目

此演示项目 使用 Visual Studio 免费社区版本。要构建演示，请执行如下操作：

1. 从 Visual Studio IDE 中打开 Visual Studio 解决方案文件 http_s3_download_demo.sln。
2. 在 IDE 的 Build 菜单中选择 Build Solution。

注意：如果您使用的是 Microsoft Visual Studio 2017 或更早版本，则必须选择与您的版本兼容的 “Platform Toolset”："Project -> RTOSDemos Properties -> Platform Toolset"。
 

配置演示项目

此演示使用 FreeRTOS-Plus-TCP TCP/IP 堆栈，因此请遵照 TCP/IP 入门项目的说明以确保您：

1. 安装必备 组件（例如 WinPCap）。
2. 设置静态或 动态 IP 地址、网关地址和网络掩码（可选）。
3. 设置了 MAC 地址（可选）。
4. 在主机上选择了 以太网网络接口。
5. 最重要的是 ， 请先测试您的网络连接，然后再尝试运行 HTTP 演示。

交付时， TCP/IP 堆栈被配置为使用动态 IP 地址。
 

配置 AWS S3 HTTP 服务器连接

此演示使用预设 URL 连接到 AWS S3 HTTP 服务器并授权访问要下载的对象。 AWS S3 HTTP 服务器的 TLS 连接仅使用服务器身份验证。在应用程序级别， 使用预签名 URL 查询中的参数对对象访问进行身份验证。请按照以下步骤配置 与 AWS 的连接。

1. 设置 Amazon Web Services (AWS) 帐户：
   • 如果您还没有账户， 请创建并激活 AWS 帐户（其中包括一个免费层级）。
   • 使用 AWS 身份和访问管理 (IAM) 设置帐户和权限。使用 IAM， 可管理帐户中每个用户的权限。默认情况下，获得根所有者的授权 才具有权限。
     1. 要将 IAM 用户添加到您的 AWS 帐户，请参阅《IAM 用户指南》。
     2. 通过添加以下策略，授予您的 AWS 帐户访问 FreeRTOS 和 AWS IoT 的权限：
        • AmazonS3FullAccess
2. 按照 “How do I create an S3 Bucket?” 中的步骤在 S3 中创建存 储桶（请参阅 《Amazon Simple Storage User Guide》。
3. 按照 “How do I upload files and folders to an S3 bucket?”中的步骤将文件上传到 S3。
4. 使用位于 FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/presigned_urls_gen.py 的脚本生成预签名 URL。 有关使用说明，请参阅 FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generato/README.md。

功能

演示首先检索文件的大小。然后在循环中依次请求每个字节范围，范围大小为 democonfigRANGE_REQUEST_LENGTH。

演示的源代码可以 在 GitHub 上的 S3DownloadHTTPExample.c 中下载。
 

连接到 AWS S3 HTTP 服务器

函数 connectToServerWithBackoffRetries() 试图与 HTTP 服务器建立 TCP 连接。如果 连接失败，则会在超时后重试。超时值将呈指数增长， 直到达到最大尝试次数或达到最大超时值。如果在配置的尝试次数后无法建立与服务器的 TCP 连接，则 connectToServerWithBackoffRetries() 会返回失败状态。

connectToServerWithBackoffRetries()的源代码可以 在 GitHub 上的 http_demo_utils.c 中下载。

函数 prvConnectToServer() 演示了如何仅使用服务器身份验证与 AWS S3 HTTP 服务器建立连接 。该函数使用基于 mbedTLS 的传输接口， 该接口在文件 FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/using_mbedtls/using_mbedtls.c 中实现。

prvConnectToServer() 可 在 GitHub 上的 S3DownloadHTTPExample.c 中下载。
 

创建范围请求

API 函数 HTTPClient_AddRangeHeader() 支持将字节范围序列化到 HTTP 请求 标头中以形成范围请求。在此演示中，使用范围请求来检索文件大小 并请求文件的每个部分。

函数 prvGetS3ObjectFileSize() 用于检索 S3 存储桶中文件的大小。描述符 在对 S3 的第一个请求中添加 "Connection: keep-alive" 标头， 以在发送响应后保持连接打开。S3 HTTP 服务器当前不支持使用预签名 URL 的标头请求，因此请求第 0 个 字节。文件的大小包含在响应的 Content-Range 标头字段中。预计服务器 会发出 206 Partial Conten 响应； 接收到的任何其他响应状态代码均为错误。

prvGetS3ObjectFileSize() 的源代码可以 在 GitHub 上的 S3DownloadHTTPExample.c 中下载。

检索文件大小后，此演示将为要下载的文件的每个字节范围创建一个 新的范围请求。对文件的每个部分使用 HTTPClient_AddRangeHeader()。

源代码可以 在 GitHub 上的 S3DownloadHTTPExample.c 中下载。
 

发送范围请求和接收响应

函数 prvDownloadS3ObjectFile() 循环发送范围请求， 直到整个文件下载完毕。API 函数 HTTPClient_Send() 发送请求并同步接收响应。 函数返回时，在 xResponse 中接收响应。然后验证状态码 为 206 Partial Content，并且到目前为止下载的字节数 由 Content-Length 标头值递增。

prvDownloadS3ObjectFile() 的源代码可以 在 GitHub 上的 S3DownloadHTTPExample.c 中下载。