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

# coreHTTP 基本 S3 下載示範
<a name="core-http-s3-download-demo"></a>

**重要**  <a name="deprecation-message-demo"></a>
此示範託管在已棄用的 Amazon-FreeRTOS 儲存庫上。我們建議您在建立新專案時從[這裡開始](freertos-getting-started-modular.md)。如果您已經有以現在已棄用的 Amazon-FreeRTOS 儲存庫為基礎的現有 FreeRTOS 專案，請參閱 [Amazon-FreeRTOS Github 儲存庫遷移指南](github-repo-migration.md)。 FreeRTOS 

## 簡介
<a name="core-http-s3-download-demo-intro"></a>

此示範示範如何使用[範圍請求](https://tools.ietf.org/html/rfc7233)從 Amazon S3 HTTP 伺服器下載檔案。當您使用 `HTTPClient_AddRangeHeader`建立 HTTP 請求時，coreHTTP API 原生支援範圍請求。對於微型控制器環境，強烈建議提出範圍請求。透過下載不同範圍的大型檔案，而不是單一請求，可以在不封鎖網路通訊端的情況下處理檔案的每個區段。範圍請求可降低捨棄封包的風險，這需要在 TCP 連線上重新傳輸，因此可改善裝置的耗電量。

此範例使用使用 mbedTLS [的網路傳輸界面](https://freertos.org/network-interface.html)，在執行 coreHTTP 的 IoT 裝置用戶端與 Amazon S3 HTTP 伺服器之間建立相互驗證的連線。

**注意**  
若要設定和執行 FreeRTOS 示範，請遵循中的步驟[FreeRTOS 入門](freertos-getting-started.md)。

### 單一執行緒與多執行緒
<a name="core-http-s3-download-demo-threads"></a>

有兩種 coreHTTP 使用模式：*單一執行緒*和*多執行緒 *（多工）。雖然本節中的示範在執行緒中執行 HTTP 程式庫，但實際上示範如何在單一執行緒環境中使用 coreHTTP （示範中只有一個任務使用 HTTP API)。雖然單一執行緒應用程式必須重複呼叫 HTTP 程式庫，但多執行緒應用程式可以改為在代理程式 （或協助程式） 任務的背景中傳送 HTTP 請求。

## 原始碼組織
<a name="core-http-s3-download-demo-source-code"></a>

示範專案名為 `http_demo_s3_download.c`，可在 `freertos/demos/coreHTTP/`目錄和 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_download.c) 網站上找到。

## 設定 Amazon S3 HTTP 伺服器連線
<a name="core-http-s3-download-demo-configure-server"></a>

此示範使用預先簽章的 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 ，並新增這些政策：
         + AmazonS3FullAccess

1. 遵循S3*Amazon Simple Storage Service 主控台使用者指南*》中的[如何建立 S3 儲存貯體？中的步驟，在 S3 ](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) 中建立儲存貯體。

1. 遵循如何將檔案和資料夾上傳至 S3 儲存貯體中的步驟，將檔案上傳至 S3？。 [ S3 ](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html)

1. 使用位於 的指令碼產生預先簽章的 URL`FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/presigned_urls_gen.py`。如需使用說明，請參閱 `FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/README.md`。

## 功能
<a name="core-http-s3-download-demo-functionality"></a>

示範會先擷取檔案大小。然後，它會在迴圈中依序請求每個位元組範圍，範圍大小為 `democonfigRANGE_REQUEST_LENGTH`。

您可以在 [GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_download.c) 網站上找到示範的原始程式碼。

### 連線至 Amazon S3 HTTP 伺服器
<a name="core-http-s3-download-demo-connecting"></a>

函數 [ 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\$1transport/freertos\$1plus\$1tcp/using\$1mbedtls/using\$1mbedtls.c](https://github.com/FreeRTOS/FreeRTOS/blob/202012.00/FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/using_mbedtls/using_mbedtls.c) 檔案中實作的 mbedTLS 型傳輸界面。

您可以在 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_download.c#L273-L333) 上`prvConnectToServer()`找到 的原始碼。

### 建立範圍請求
<a name="core-http-s3-download-demo-creating-range-request"></a>

API 函數`HTTPClient_AddRangeHeader()`支援將位元組範圍序列化為 HTTP 請求標頭，以形成範圍請求。此示範會使用範圍請求來擷取檔案大小，並請求檔案的每個區段。

函數會`prvGetS3ObjectFileSize()`擷取 S3 儲存貯體中檔案大小。`Connection: keep-alive` 標頭會新增到 Amazon S3 的第一個請求中，以在傳送回應後保持連線開啟。S3 HTTP 伺服器目前不支援使用預先簽章 URL 的 HEAD 請求，因此請求第 0 個位元組。檔案的大小包含在回應的`Content-Range`標頭欄位中。預期來自伺服器的`206 Partial Content`回應；收到的任何其他回應狀態碼都是錯誤。

您可以在 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_download.c#L337-L502) 上`prvGetS3ObjectFileSize()`找到 的原始碼。

擷取檔案大小後，此示範會為要下載檔案的每個位元組範圍建立新的範圍請求。它會`HTTPClient_AddRangeHeader()`針對 檔案的每個區段使用 。

### 傳送範圍請求和接收回應
<a name="core-http-s3-download-demo-send-request"></a>

函數會在迴圈中`prvDownloadS3ObjectFile()`傳送範圍請求，直到下載整個檔案為止。API 函數`HTTPClient_Send()`會傳送請求並同步接收回應。當函數傳回時，回應會在 中收到`xResponse`。然後，狀態碼會驗證為 ，`206 Partial Content`而且到目前為止下載的位元組數會以`Content-Length`標頭值遞增。

您可以在 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_download.c#L506-L651) 上`prvDownloadS3ObjectFile()`找到 的原始碼。