本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# coreHTTP 基本 Amazon S3 上傳示範
**重要**
此示範託管在已棄用的 Amazon-FreeRTOS 儲存庫上。我們建議您在建立新專案時從[這裡開始](freertos-getting-started-modular.md)。如果您已經有以現在已棄用之 Amazon-FreeRTOS 儲存庫為基礎的現有 FreeRTOS 專案，請參閱 [Amazon-FreeRTOS Github 儲存庫遷移指南](github-repo-migration.md)。 FreeRTOS
## 簡介
此範例示範如何將 PUT 請求傳送至 Amazon Simple Storage Service (Amazon S3) HTTP 伺服器並上傳小型檔案。它也會執行 GET 請求，以在上傳後驗證檔案大小。此範例使用使用 mbedTLS [的網路傳輸界面](https://freertos.org/network-interface.html)，在執行 coreHTTP 的 IoT 裝置用戶端與 Amazon S3 HTTP 伺服器之間建立相互驗證的連線。
**注意**
若要設定和執行 FreeRTOS 示範，請遵循中的步驟[FreeRTOS 入門](freertos-getting-started.md)。
### 單一執行緒與多執行緒
有兩種 coreHTTP 使用模式：*單一執行*緒和*多執行緒 *（多工）。雖然本節中的示範會在執行緒中執行 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. 將存取 FreeRTOS 的許可授予 AWS 您的帳戶 AWS IoT ，並新增此政策：
+ AmazonS3FullAccess
1. 遵循《Amazon S3 *Simple Storage Service 使用者指南》中的*[如何建立 S3 儲存貯體？中的步驟，在 Amazon S3 中建立儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html)。
1. 遵循如何將檔案和資料夾上傳至 Amazon S3 儲存貯體中的步驟，將檔案上傳至 Amazon S3？。 [ S3 ](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html)
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 型傳輸界面。您可以在 [GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_upload.c#L306-L366) 網站上`prvConnectToServer`找到 的定義。
### 上傳資料
`prvUploadS3ObjectFile` 函數示範如何建立 PUT 請求並指定要上傳的檔案。上傳檔案的 Amazon S3 儲存貯體和要上傳的檔案名稱會在預先簽章的 URL 中指定。為了節省記憶體，請求標頭和 都會使用相同的緩衝區來接收回應。使用 `HTTPClient_Send` API 函數同步接收回應。回應`200 OK`狀態碼預期來自 Amazon S3 HTTP 伺服器。任何其他狀態碼都是錯誤。
您可以在 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_upload.c#L539-L632) 網站上`prvUploadS3ObjectFile()`找到 的原始碼。
### 驗證上傳
`prvVerifyS3ObjectFileSize` 函數會呼叫 `prvGetS3ObjectFileSize`來擷取 S3 儲存貯體中物件的大小。Amazon S3 HTTP 伺服器目前不支援使用預先簽章 URL 的 HEAD 請求，因此請求第 0 個位元組。檔案的大小包含在回應的`Content-Range`標頭欄位中。預期來自伺服器的`206 Partial Content`回應。任何其他回應狀態碼都是錯誤。
您可以在 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreHTTP/http_demo_s3_upload.c#L370-L535) 網站上`prvGetS3ObjectFileSize()`找到 的原始碼。