本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 開始使用 適用於 C\$1\$1 的 AWS SDK 適用於 C\$1\$1 的 AWS SDK 是模組化、跨平台的開放原始碼程式庫，可用來連線至 Amazon Web Services。 適用於 C\$1\$1 的 AWS SDK 使用 [CMake](https://cmake.org/) 支援多個網域上的多個平台，包括視訊遊戲、系統、行動裝置和內嵌裝置。CMake 是一種建置工具，可用來管理應用程式的相依性，以及建立適用於您正在建置之平台的 makefile。CMake 會移除您平台或應用程式未使用的組建部分。 在執行程式碼以存取 AWS 資源之前，您必須建立程式碼的驗證方式 AWS。 + [AWS 使用適用於 C\$1\$1 的 AWS SDK 透過 驗證](credentials.md) 若要在程式碼 適用於 C\$1\$1 的 AWS SDK 中使用 ，請直接建置 SDK 來源或使用套件管理員來取得 SDK 可執行檔。 + [適用於 C\$1\$1 的 AWS SDK 從原始程式碼取得](sdk-from-source.md) + [適用於 C\$1\$1 的 AWS SDK 從套件管理員取得](sdk-from-pm.md) 如果您遇到有關 CMake 的建置問題，請參閱 [針對適用於 C\$1\$1 組建問題的 AWS SDK 進行故障診斷](troubleshooting-cmake.md)。 # AWS 使用適用於 C\$1\$1 的 AWS SDK 透過 驗證 使用 進行開發 AWS 時，您必須建立程式碼向 進行身分驗證的方式 AWS 服務。您可以根據環境和您可用的存取權，以不同的方式設定 AWS 資源的程式設計 AWS 存取。如需所有主要身分驗證方法的選擇，以及針對 SDK 進行設定的指引，請參閱 *AWS SDKs和工具參考指南中的*[身分驗證和存取](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)。 ## 使用主控台登入資料 針對本機開發，我們建議新使用者使用現有的 AWS 管理主控台登入憑證，以程式設計方式存取 AWS 服務。在瀏覽器型身分驗證流程之後， AWS會產生臨時登入資料，可用於 CLI AWS Tools for PowerShell 和 AWS SDKs AWS 等本機開發工具。此功能可簡化設定和管理 AWS CLI 登入資料的程序，尤其是如果您偏好互動式身分驗證，而不是管理長期存取金鑰。 如果您選擇此方法，請依照指示使用 CLI AWS 以主控台登入資料登入。如需詳細資訊，請參閱[使用主控台登入資料進行 AWS 本機開發](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)。 使用 AWS CLI 設定後，[預設登入資料提供者鏈](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credproviders.html#credproviders-default-credentials-provider-chain)會自動開始使用 CLI AWS 快取的登入字符來提出請求。 ## 使用 IAM Identity Center 此方法包括安裝 AWS CLI 以簡化組態，以及定期登入 AWS 存取入口網站。 如果您選擇此方法，請完成 *AWS SDKs 和工具參考指南*中的 [IAM Identity Center 身分驗證](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html)程序。之後，您的環境應該包含下列元素： + 在執行應用程式之前 AWS CLI，您用來啟動 AWS 存取入口網站工作階段的 。 + 具有`[default]`設定檔的[共用 AWS`config`檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)，其中包含一組可從 SDK 參考的組態值。若要尋找此檔案的位置，請參閱 *AWS SDK 和工具參考指南*中的[共用檔案位置](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)。 + 共用`config`檔案會設定 [https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)設定。這會設定軟體開發套件用於 AWS 請求 AWS 區域 的預設值。此區域用於未指定使用 區域的 SDK 服務請求。 + 開發套件使用描述檔的 [SSO 字符提供者組態](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile)，在傳送請求至 之前取得登入資料 AWS。此`sso_role_name`值是連接至 IAM Identity Center 許可集的 IAM 角色，應允許存取您應用程式中 AWS 服務 使用的 。 下列範例`config`檔案顯示使用 SSO 字符提供者組態設定的預設設定檔。設定檔`sso_session`的設定是指具名[`sso-session`區段](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#section-session)。`sso-session` 區段包含啟動 AWS 存取入口網站工作階段的設定。 ``` [default] sso_session = my-sso sso_account_id = 111122223333 sso_role_name = SampleRole region = us-east-1 output = json [sso-session my-sso] sso_region = us-east-1 sso_start_url = https://provided-domain.awsapps.com/start sso_registration_scopes = sso:account:access ``` 適用於 C\$1\$1 的 AWS SDK 不需要將其他套件 （例如 `SSO`和 `SSOOIDC`) 新增至您的應用程式，即可使用 IAM Identity Center 身分驗證。 ### 啟動 AWS 存取入口網站工作階段 在執行存取的應用程式之前 AWS 服務，您需要 SDK 的作用中 AWS 存取入口網站工作階段，才能使用 IAM Identity Center 身分驗證來解析登入資料。視您設定的工作階段長度而定，您的存取最終會過期，而且 SDK 會遇到身分驗證錯誤。若要登入 AWS 存取入口網站，請在 中執行下列命令 AWS CLI。 ``` aws sso login ``` 由於您有預設的設定檔設定，因此您不需要使用 `--profile` 選項呼叫指令。如果您的 SSO 權杖提供者組態使用已命名的設定檔，則命令為 `aws sso login --profile named-profile`。 若要測試您是否已經有作用中的工作階段，請執行下列 AWS CLI 命令。 ``` aws sts get-caller-identity ``` 對此命令的回應，應報告共用 `config` 檔案中設定的 IAM Identity Center 帳戶和許可集合。 **注意** 如果您已有作用中的 AWS 存取入口網站工作階段並執行 `aws sso login`，則不需要提供登入資料。 登入程序可能會提示您允許 AWS CLI 存取您的資料。由於 AWS CLI 建置在適用於 Python 的 SDK 之上，因此許可訊息可能包含`botocore`名稱的變化。 ## 更多身分驗證資訊 人類使用者具有*人類身分*，是應用程式的相關人員、管理員、開發人員、操作員和消費者。它們必須具有身分才能存取您的 AWS 環境和應用程式。身為組織成員的人類使用者也稱為*人力身分*，這表示您是開發人員。存取時使用臨時登入資料 AWS。您可以為您的人類使用者使用身分提供者，透過擔任提供臨時登入資料的角色來提供 AWS 帳戶的聯合存取。對於集中式存取管理，我們建議您使用 AWS IAM Identity Center (IAM Identity Center) 來管理對帳戶和這些帳戶中許可的存取。如需更多替代方案，請參閱下列內容： + 如需了解有關最佳實務的資訊，請參閱 *IAM 使用者指南*中的 [IAM 安全最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。 + 若要建立短期 AWS 登入資料，請參閱《*IAM 使用者指南*》中的[暫時安全登入](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)資料。 + 若要了解其他 適用於 C\$1\$1 的 AWS SDK 登入資料提供者，請參閱 *AWS SDKs和工具參考指南*中的[標準化登入資料提供者](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)。 # 適用於 C\$1\$1 的 AWS SDK 從原始程式碼取得 您可以從 適用於 C\$1\$1 的 AWS SDK 程式碼使用 ，方法是先從來源建置軟體開發套件，然後在本機安裝。 **程序概觀** | 一般程序 | 詳細程序 | | --- | --- | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-cpp/v1/developer-guide/sdk-from-source.html) | 首先從來源建置並安裝軟體開發套件。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-cpp/v1/developer-guide/sdk-from-source.html) | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-cpp/v1/developer-guide/sdk-from-source.html) | 然後使用 SDK 開發您自己的應用程式。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-cpp/v1/developer-guide/sdk-from-source.html) | # 在 Windows 適用於 C\$1\$1 的 AWS SDK 上建置 若要設定 適用於 C\$1\$1 的 AWS SDK，您可以直接從來源自行建置 SDK，或使用套件管理員下載程式庫。 SDK 來源會依服務分成個別套件。安裝整個 SDK 最多可能需要一小時。僅安裝您的程式使用的特定服務子集可減少安裝時間，並減少磁碟上的大小。若要選擇要安裝的服務，您需要知道程式使用的每個服務的套件名稱。您可以在 GitHub [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp)上查看 的套件目錄清單。套件名稱是 服務的目錄名稱尾碼。 ``` aws-sdk-cpp\aws-cpp-sdk- # Repo directory name and packageName aws-sdk-cpp\aws-cpp-sdk-s3 # Example: Package name is s3 ``` ## 先決條件 您需要至少 4 GB 的 RAM，才能建置一些較大的 AWS 用戶端。由於記憶體不足，開發套件可能無法在 Amazon EC2 執行個體類型 *t2.micro*、*t2.small* 和其他小型執行個體類型上建置。 若要使用 適用於 C\$1\$1 的 AWS SDK，您需要下列其中一項： + Microsoft Visual Studio 2015 或更新版本， + GNU 編譯器集合 (GCC) 4.9 或更新版本，或 + Clang 3.3 或更新版本。 ## 使用 curl 建置適用於 Windows 的 SDK 在 Windows 上，軟體開發套件是以 [WinHTTP](https://msdn.microsoft.com/en-us/library/windows/desktop/aa382925%28v=vs.85%29.aspx) 做為預設 HTTP 用戶端建置。不過，WinHTTP 1.0 不支援 HTTP/2 雙向串流，這是 Amazon Transcribe 和 Amazon Lex AWS 服務 等部分的必要串流。因此，有時需要使用 SDK 建置 curl 支援。若要檢視所有可用的 curl 下載選項，請參閱 [curl 版本和下載](https://curl.se/download.html)。使用 curl 支援建置 SDK 的一種方法如下： **建置包含 curl 程式庫支援的 SDK** 1. 導覽至適用於 [Windows 的 curl](https://curl.se/windows/) 並下載適用於 Microsoft Windows 的 curl 二進位套件。 1. 將套件解壓縮至電腦上的資料夾，例如 `C:\curl`。 1. 導覽至[從 Mozilla 擷取的 CA 憑證](http://curl.haxx.se/docs/caextract.html)，然後下載 `cacert.pem` 檔案。此隱私權增強型郵件 (PEM) 檔案包含一組有效的數位憑證，用於驗證安全網站的真實性。憑證由憑證授權機構 (CA) 公司分發，例如 GlobalSign 和 Verisign。 1. 將`cacert.pem`檔案移至您在上一個步驟中解壓縮的`bin`子資料夾，例如 `C:\curl\bin`。將檔案重新命名為 `curl-ca-bundle.crt`。 此外，Microsoft Build Engine (MSBuild) 必須能夠在下列`dll`程序中找到 curl。因此，您應該將 curl `bin` 資料夾路徑新增至 Windows `PATH`環境變數，例如 `set PATH=%PATH%;C:\curl\bin`。每次開啟新的命令提示以建置 SDK 時，都必須新增此項目。或者，您可以在 Windows 系統設定中全域設定環境變數，以便記住設定。 在下列程序中*從來源建置 SDK* 時，請參閱步驟 5 （產生建置檔案） 以取得在 SDK 中建置 curl 所需的命令語法。 撰寫程式碼時，您必須在 `caFile`中將 [在程式碼中設定適用於 C\$1\$1 服務用戶端的 AWS SDK](client-config.md) 設定為憑證檔案的位置。如需使用 Amazon Transcribe 的範例，請參閱 GitHub 上*AWS 程式碼範例儲存庫*[https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/transcribe-streaming](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/transcribe-streaming)中的 。 ## 從來源建置 SDK 您可以使用命令列工具從來源建置 SDK。使用此方法，您可以自訂 SDK 組建。如需可用選項的詳細資訊，請參閱 [CMake 參數](cmake-params.md)。有三個主要步驟。首先，您使用 CMake 建置檔案。其次，您會使用 MSBuild 來建置可搭配您的作業系統和建置工具鏈使用的 SDK 二進位檔。第三，您會將二進位檔安裝或複製到開發機器上的正確位置。 **從來源建置 SDK** 1. 安裝 [CMake](https://cmake.org/) （最低版本 3.13) 和平台的相關建置工具。建議將 `cmake`新增至您的 `PATH`。若要檢查您的 CMake 版本，請開啟命令提示字元並執行命令 **cmake --version** 1. 在命令提示字元中，導覽至您要存放 SDK 的資料夾。 1. 取得最新的原始程式碼。 1.11 版使用 git 子模組來包裝外部相依性。這包括 *AWS SDK 和工具參考指南中所述SDKs * [CRT 程式庫](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)。 從 GitHub [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) 上的 下載或複製 SDK 來源： + 使用 Git 複製：HTTPS ``` git clone --recurse-submodules https://github.com/aws/aws-sdk-cpp ``` + 使用 Git 複製：SSH ``` git clone --recurse-submodules git@github.com:aws/aws-sdk-cpp.git ``` 1. 我們建議您將產生的建置檔案存放在 SDK 來源目錄之外。建立新的目錄以將建置檔案存放在 中，並導覽至該資料夾。 ``` mkdir sdk_build cd sdk_build ``` 1. 透過執行 產生建置檔案`cmake`。在`cmake`命令列指定 是要建置*偵錯*或*發行*版本。選擇`Debug`整個此程序，以執行應用程式程式碼的偵錯組態。選擇`Release`整個此程序，以執行應用程式程式碼的發行版本組態。對於 Windows，軟體開發套件安裝位置通常為 `\Program Files (x86)\aws-cpp-sdk-all\`。命令語法： `{path to cmake if not in PATH} {path to source location of aws-sdk-cpp} -DCMAKE_BUILD_TYPE=[Debug | Release] -DCMAKE_PREFIX_PATH={path to install destination}` 如需修改建置輸出的更多方式，請參閱 [CMake 參數](cmake-params.md)。 若要產生建置檔案，請執行下列其中一項操作： + **產生建置檔案 （全部 AWS 服務)**：若要建置整個 SDK，請執行 cmake，指定要建置*偵錯*或*發行*版本。例如： ``` cmake "..\aws-sdk-cpp" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH="C:\Program Files (x86)\aws-cpp-sdk-all" ``` + **產生建置檔案 （子集 AWS 服務)**：若要僅建置 SDK 的特定服務或 （服務套件），請新增 CMake [BUILD\$1ONLY](cmake-params.md#cmake-build-only) 參數，並將服務名稱以分號分隔。下列範例只會建置 Amazon S3 服務套件： ``` cmake ..\aws-sdk-cpp -DCMAKE_BUILD_TYPE=Debug -DBUILD_ONLY="s3" -DCMAKE_PREFIX_PATH="C:\Program Files (x86)\aws-cpp-sdk-all" ``` + **產生組建檔案 （使用 curl)**：完成 curl 先決條件後，需要三個額外的 cmake 命令列選項，才能在 SDK 中包含 curl 支援：[FORCE\$1CURL](cmake-params.md#cmake-force-curl)、 [CURL\$1INCLUDE\$1DIR](cmake-params.md#cmake-curl-include-dir)和 [CURL\$1LIBRARY](cmake-params.md#cmake-curl-library)。例如： ``` cmake ..\aws-sdk-cpp -DCMAKE_BUILD_TYPE=Debug -DFORCE_CURL=ON -DCURL_INCLUDE_DIR='C:/curl/include' -DCURL_LIBRARY='C:/curl/lib/libcurl.dll.a' -DCMAKE_PREFIX_PATH="C:\Program Files (x86)\aws-cpp-sdk-all" ``` **注意** 如果您收到錯誤 無法建置第三方程式庫，請執行 檢查您的 CMake 版本**cmake --version**。您必須使用 CMake 最低版本 3.13。 1. 建置 SDK 二進位檔。如果您要建置整個 SDK，此步驟可能需要一小時或更長的時間。命令語法： `{path to cmake if not in PATH} --build . --config=[Debug | Release]` ``` cmake --build . --config=Debug ``` **注意** 如果您遇到錯誤 程式碼執行無法繼續 ... 找不到 dll。重新安裝程式可能會修正此問題。」，請重試 `cmake`命令。 1. 開啟具有**管理員**權限的命令提示，以使用 `CMAKE_PREFIX_PATH` 參數在先前指定的位置安裝 SDK。命令語法： `{path to cmake if not in PATH} --install . --config=[Debug | Release]` ``` cmake --install . --config=Debug ``` ## 在 Windows 上為 Android 建置 若要建置 Android 版，請將 `-DTARGET_ARCH=ANDROID`新增至`cmake`命令列。 適用於 C\$1\$1 的 AWS SDK 包含 CMake 工具鏈檔案，其中包含您參考適當環境變數 () 所需的內容`ANDROID_NDK`。 若要在 Windows 上建置適用於 Android 的 SDK，您需要`cmake`從 Visual Studio (2015 或更新版本） 開發人員命令提示字元執行 。您也需要在路徑**`patch`**中安裝 NMAKE [NMAKE](https://docs.microsoft.com/en-us/cpp/build/reference/nmake-reference?view=msvc-160) 和命令 **`git`**和 。如果您已在 Windows 系統上安裝 git，則最有可能**`patch`**在同級目錄中找到 (`.../Git/usr/bin/`)。驗證這些需求後，您的`cmake`命令列會稍微變更以使用 NMAKE。 ``` cmake -G "NMake Makefiles" `-DTARGET_ARCH=ANDROID` .. ``` NMAKE 會以序列方式建置。若要更快速地建置，我們建議您安裝 JOM 做為 NMAKE 的替代方案，然後變更`cmake`呼叫，如下所示： ``` cmake -G "NMake Makefiles JOM" `-DTARGET_ARCH=ANDROID` .. ``` 如需範例應用程式，請參閱[使用 設定 Android 應用程式 適用於 C\$1\$1 的 AWS SDK](https://aws.amazon.com/blogs/developer/setting-up-an-android-application-with-aws-sdk-for-c/) # 在 Linux/macOS 適用於 C\$1\$1 的 AWS SDK 上建置 若要設定 適用於 C\$1\$1 的 AWS SDK，您可以直接從來源自行建置 SDK，或使用套件管理員下載程式庫。 SDK 來源會依服務分成個別套件。安裝整個 SDK 最多可能需要一小時。僅安裝您的程式使用的特定服務子集可減少安裝時間，並減少磁碟上的大小。若要選擇要安裝的服務，您需要知道程式使用的每個服務的套件名稱。您可以在 GitHub [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp)上查看 的套件目錄清單。套件名稱是 服務的目錄名稱尾碼。 ``` aws-sdk-cpp\aws-cpp-sdk- # Repo directory name and packageName aws-sdk-cpp\aws-cpp-sdk-s3 # Example: Package name is s3 ``` ## 先決條件 您需要至少 4 GB 的 RAM，才能建置一些較大的 AWS 用戶端。由於記憶體不足，開發套件可能無法在 Amazon EC2 執行個體類型 *t2.micro*、*t2.small* 和其他小型執行個體類型上建置。 若要使用 適用於 C\$1\$1 的 AWS SDK，您需要下列其中一項： + GNU 編譯器集合 (GCC) 4.9 或更新版本，或 + Clang 3.3 或更新版本。 ## Linux 系統的其他需求 您必須擁有 `libcurl`、`libopenssl`、`zlib`、 `libuuid`和 的標頭檔案 (`-dev` 套件），`libpulse`可選擇是否支援 Amazon Polly。您可以使用系統的套件管理員來尋找套件。 **在以 *Debian/Ubuntu 為基礎的系統上*安裝套件** + ``` sudo apt-get install libcurl4-openssl-dev libssl-dev uuid-dev zlib1g-dev libpulse-dev ``` **在以 *Amazon Linux/Redhat/Fedora/CentOS 為基礎的系統上*安裝套件** + ``` sudo yum install libcurl-devel openssl-devel libuuid-devel pulseaudio-libs-devel ``` ## 從來源建置 SDK 您可以使用命令列工具從來源建置軟體開發套件，作為使用 vcpkg 的替代方案。使用此方法，您可以自訂 SDK 組建。如需可用選項的詳細資訊，請參閱 [CMake 參數](cmake-params.md)。 **從來源建置 SDK** 1. 安裝 [CMake](https://cmake.org/) （最低版本 3.13) 和平台的相關建置工具。建議將 `cmake`新增至您的 `PATH`。若要檢查您的 CMake 版本，請開啟命令提示字元並執行命令 **cmake --version** 1. 在命令提示字元中，導覽至您要存放 SDK 的資料夾。 1. 取得最新的原始程式碼。 1.11 版使用 git 子模組來包裝外部相依性。這包括 *AWS SDK 和工具參考指南中所述SDKs * [CRT 程式庫](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)。 從 GitHub [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) 上的 下載或複製 SDK 來源： + 使用 Git 複製：HTTPS ``` git clone --recurse-submodules https://github.com/aws/aws-sdk-cpp ``` + 使用 Git 複製：SSH ``` git clone --recurse-submodules git@github.com:aws/aws-sdk-cpp.git ``` 1. 我們建議您將產生的建置檔案存放在 SDK 來源目錄之外。建立新的目錄以將建置檔案存放在 中，並導覽至該資料夾。 ``` mkdir sdk_build cd sdk_build ``` 1. 透過執行 產生建置檔案`cmake`。在`cmake`命令列指定 是要建置*偵錯*或*發行*版本。選擇`Debug`整個此程序，以執行應用程式程式碼的偵錯組態。選擇`Release`整個此程序，以執行應用程式程式碼的發行版本組態。命令語法： `{path to cmake if not in PATH} {path to source location of aws-sdk-cpp} -DCMAKE_BUILD_TYPE=[Debug | Release] -DCMAKE_PREFIX_PATH={path to install} -DCMAKE_INSTALL_PREFIX={path to install}` 如需修改建置輸出的更多方式，請參閱 [CMake 參數](cmake-params.md)。 **注意** 使用不區分大小寫的檔案系統在 Mac 上建置 時，請檢查執行建置之目錄中 `pwd`命令的輸出。確定`pwd`輸出對目錄名稱使用混合大小寫，例如 `/Users`和 `Documents`。 若要產生建置檔案，請執行下列其中一項操作： + **產生建置檔案 （全部 AWS 服務)**：若要建置整個 SDK，請執行 cmake，指定要建置*偵錯*或*發行*版本。例如： ``` cmake ../aws-sdk-cpp -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=/usr/local/ -DCMAKE_INSTALL_PREFIX=/usr/local/ ``` + **產生建置檔案 （子集 AWS 服務)**：若要僅建置 SDK 的特定服務或 （服務套件），請新增 CMake [BUILD\$1ONLY](cmake-params.md#cmake-build-only) 參數，並將服務名稱以分號分隔。下列範例只會建置 Amazon S3 服務套件： ``` cmake ../aws-sdk-cpp -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=/usr/local/ -DCMAKE_INSTALL_PREFIX=/usr/local/ -DBUILD_ONLY="s3" ``` **注意** 如果您收到錯誤 無法建置第三方程式庫，請執行 檢查您的 CMake 版本**cmake --version**。您必須使用 CMake 最低版本 3.13。 1. 建置 SDK 二進位檔。如果您要建置整個 SDK，操作可能需要一小時或更長的時間。 ``` cmake --build . --config=Debug ``` 1. 安裝 SDK。視您選擇安裝的位置而定，您可能需要提升權限。 ``` cmake --install . --config=Debug ``` ## 在 Linux 上為 Android 建置 若要建置 Android 版，請將 `-DTARGET_ARCH=ANDROID`新增至`cmake`命令列。 適用於 C\$1\$1 的 AWS SDK 包含 CMake 工具鏈檔案，其中包含您參考適當環境變數 () 所需的內容`ANDROID_NDK`。如需範例應用程式，請參閱[使用 設定 Android 應用程式 適用於 C\$1\$1 的 AWS SDK](https://aws.amazon.com/blogs/developer/setting-up-an-android-application-with-aws-sdk-for-c/) # 使用適用於 C\$1\$1 的 AWS SDK 建立簡單的應用程式 [CMake](https://cmake.org/) 是一種建置工具，可用來管理應用程式的相依性，以及建立適合您建置平台的 makefile。您可以使用 CMake 來建立和建置使用 的專案 適用於 C\$1\$1 的 AWS SDK。 此範例會報告您擁有的 Amazon S3 儲存貯體。此範例不需要在您的 AWS 帳戶中擁有 Amazon S3 儲存貯體，但如果您至少有一個儲存貯體，則會更有趣。如果您還沒有[儲存貯體，請參閱《Amazon Simple Storage Service 使用者指南》中的建立](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html)儲存貯體。 ** ## 步驟 1：撰寫程式碼 此範例包含一個資料夾，其中包含一個來源檔案 (`hello_s3.cpp`) 和一個`CMakeLists.txt`檔案。程式使用 Amazon S3 報告儲存貯體資訊。此程式碼也可在 GitHub 上的[AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/s3/hello_s3)中使用。 您可以在`CMakeLists.txt`建置組態檔案中設定許多選項。如需詳細資訊，請參閱 [CMake 網站上的 CMake 教學](https://cmake.org/cmake-tutorial/)課程。 CMake **注意** Deep Dive：設定 `CMAKE_PREFIX_PATH` 根據預設，macOS、Linux、Android 和其他非 Windows 平台上 適用於 C\$1\$1 的 AWS SDK 的 會安裝到 `/usr/local`，Windows 也會安裝到 `\Program Files (x86)\aws-cpp-sdk-all`。 當您將 AWS 開發套件安裝到這些標準位置時，CMake 會自動尋找必要的資源。不過，如果您將 AWS 軟體開發套件安裝到自訂位置，您必須告知 CMake 在何處可以找到建置軟體開發套件所產生的下列資源： `AWSSDKConfig.cmake`：組態檔案，告知 CMake 如何在專案中尋找和使用 AWS SDK 程式庫。如果沒有此檔案，CMake 就找不到 AWS SDK 標頭檔案、連結至 AWS SDK 程式庫，或設定適當的編譯器旗標。 （適用於 1.8 版和更早版本） 相依性的位置：`aws-c-event-stream`、`aws-c-common`、 `aws-checksums` 若要設定自訂安裝路徑： ``` cmake -DCMAKE_PREFIX_PATH=/path/to/your/aws-sdk-installation /path/to/project/you/are/building ``` 如果您未`CMAKE_PREFIX_PATH`設定自訂安裝，當 CMake 嘗試在 `find_package(AWSSDK)`中處理 時，您的建置將會失敗，並出現「找不到 AWSSDK」等錯誤`CMakeLists.txt`。 **注意** Deep Dive：Windows Runtime 程式庫 若要執行您的程式，您的程式可執行檔位置需要數個 DLLs：`aws-c-common.dll`、`aws-c-event-stream.dll``aws-checksums.dll``aws-cpp-sdk-core.dll`、、 以及任何根據您程式元件的特定 DLLs （此範例也需要 ，`aws-cpp-sdk-s3`因為它使用 Amazon S3)。`CMakeLists.txt` 檔案中的第二個`if`陳述式會將這些程式庫從安裝位置複製到可執行檔位置，以滿足此需求。 `AWSSDK_CPY_DYN_LIBS` 是由 定義的巨集 適用於 C\$1\$1 的 AWS SDK ，可將開發套件的 DLLs 從安裝位置複製到您程式的可執行檔位置。如果這些 DLLs 不在可執行檔位置，則會發生「找不到檔案」的執行時間例外狀況。如果您遇到這些錯誤，請檢閱`CMakeLists.txt`檔案的此部分，了解唯一環境的必要變更。 **建立資料夾和來源檔案** 1. 建立`hello_s3`目錄和/或專案來保存您的來源檔案。 **注意** 若要在 Visual Studio 中完成此範例：選擇**建立新專案**，然後選擇 **CMake 專案**。命名專案 `hello_s3`。此專案名稱用於 `CMakeLists.txt` 檔案。 1. 在該資料夾中，新增包含下列程式碼`hello_s3.cpp`的檔案，該程式碼會報告您擁有的 Amazon S3 儲存貯體。 ``` #include #include #include #include using namespace Aws; using namespace Aws::Auth; /* * A "Hello S3" starter application which initializes an Amazon Simple Storage Service (Amazon S3) client * and lists the Amazon S3 buckets in the selected region. * * main function * * Usage: 'hello_s3' * */ int main(int argc, char **argv) { Aws::SDKOptions options; // Optionally change the log level for debugging. // options.loggingOptions.logLevel = Utils::Logging::LogLevel::Debug; Aws::InitAPI(options); // Should only be called once. int result = 0; { Aws::Client::ClientConfiguration clientConfig; // Optional: Set to the AWS Region (overrides config file). // clientConfig.region = "us-east-1"; // You don't normally have to test that you are authenticated. But the S3 service permits anonymous requests, thus the s3Client will return "success" and 0 buckets even if you are unauthenticated, which can be confusing to a new user. auto provider = Aws::MakeShared("alloc-tag"); auto creds = provider->GetAWSCredentials(); if (creds.IsEmpty()) { std::cerr << "Failed authentication" << std::endl; } Aws::S3::S3Client s3Client(clientConfig); auto outcome = s3Client.ListBuckets(); if (!outcome.IsSuccess()) { std::cerr << "Failed with error: " << outcome.GetError() << std::endl; result = 1; } else { std::cout << "Found " << outcome.GetResult().GetBuckets().size() << " buckets\n"; for (auto &bucket: outcome.GetResult().GetBuckets()) { std::cout << bucket.GetName() << std::endl; } } } Aws::ShutdownAPI(options); // Should only be called once. return result; } ``` 1. 新增`CMakeLists.txt`指定專案名稱、可執行檔、來源檔案和連結程式庫的檔案。 ``` # Set the minimum required version of CMake for this project. cmake_minimum_required(VERSION 3.13) # Set the AWS service components used by this project. set(SERVICE_COMPONENTS s3) # Set this project's name. project("hello_s3") # Set the C++ standard to use to build this target. # At least C++ 11 is required for the AWS SDK for C++. set(CMAKE_CXX_STANDARD 11) # Use the MSVC variable to determine if this is a Windows build. set(WINDOWS_BUILD ${MSVC}) if (WINDOWS_BUILD) # Set the location where CMake can find the installed libraries for the AWS SDK. string(REPLACE ";" "/aws-cpp-sdk-all;" SYSTEM_MODULE_PATH "${CMAKE_SYSTEM_PREFIX_PATH}/aws-cpp-sdk-all") list(APPEND CMAKE_PREFIX_PATH ${SYSTEM_MODULE_PATH}) endif () # Find the AWS SDK for C++ package. find_package(AWSSDK REQUIRED COMPONENTS ${SERVICE_COMPONENTS}) if (WINDOWS_BUILD AND AWSSDK_INSTALL_AS_SHARED_LIBS) # Copy relevant AWS SDK for C++ libraries into the current binary directory for running and debugging. # set(BIN_SUB_DIR "/Debug") # if you are building from the command line you may need to uncomment this # and set the proper subdirectory to the executables' location. AWSSDK_CPY_DYN_LIBS(SERVICE_COMPONENTS "" ${CMAKE_CURRENT_BINARY_DIR}${BIN_SUB_DIR}) endif () add_executable(${PROJECT_NAME} hello_s3.cpp) target_link_libraries(${PROJECT_NAME} ${AWSSDK_LINK_LIBRARIES}) ``` ## 步驟 2：使用 CMake 建置 CMake 會使用 中的資訊`CMakeLists.txt`來建置可執行程式。 建議您依照 IDE 的標準實務建置應用程式。 **從命令列建置應用程式** 1. 建立 目錄，其中 **`cmake`**將建置您的應用程式。 ``` mkdir my_project_build ``` 1. 變更為建置目錄，並使用專案來源目錄的**`cmake`**路徑執行 。 ``` cd my_project_build cmake ../ ``` 1. 在 **`cmake`**產生建置目錄後，您可以使用 **`make`**（或在 Windows **`nmake`**上） 或 MSBUILD (`msbuild ALL_BUILD.vcxproj` 或 `cmake --build . --config=Debug`) 來建置應用程式。 ## 步驟 3：執行 當您執行此應用程式時，它會顯示主控台輸出，其中列出 Amazon S3 儲存貯體的總數和每個儲存貯體的名稱。 我們建議您遵循 IDE 的標準實務來執行應用程式。 **注意** 請記得登入！如果您使用 IAM Identity Center 進行身分驗證，請記得使用 AWS CLI `aws sso login`命令登入。 **透過命令列執行程式** 1. 變更為產生建置結果的偵錯目錄。 1. 使用可執行檔的名稱執行程式。 ``` hello_s3 ``` 如需使用 的其他範例 適用於 C\$1\$1 的 AWS SDK，請參閱 [AWS 服務 使用適用於 C\$1\$1 的 AWS SDK 呼叫 的引導範例](programming-services.md)。 # 適用於 C\$1\$1 的 AWS SDK 從套件管理員取得 **重要** 如果您使用的是套件管理員，例如 homebrew 或 vcpkg： 將適用於 C\$1\$1 的 SDK 更新為新版本之後，您必須重新編譯任何依賴 SDK 的程式庫或可執行檔。 若要設定 適用於 C\$1\$1 的 AWS SDK，您可以直接從來源自行建置 SDK，或使用套件管理員下載程式庫。 SDK 來源會依服務分成個別套件。安裝整個 SDK 最多可能需要一小時。僅安裝您的程式使用的特定服務子集可減少安裝時間，並減少磁碟上的大小。若要選擇要安裝的服務，您需要知道程式使用的每個服務的套件名稱。您可以在 GitHub [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp)上查看 的套件目錄清單。套件名稱是 服務的目錄名稱尾碼。 ``` aws-sdk-cpp\aws-cpp-sdk- # Repo directory name and packageName aws-sdk-cpp\aws-cpp-sdk-s3 # Example: Package name is s3 ``` ## 先決條件 您需要至少 4 GB 的 RAM，才能建置一些較大的 AWS 用戶端。由於記憶體不足，開發套件可能無法在 Amazon EC2 執行個體類型 *t2.micro*、*t2.small* 和其他小型執行個體類型上建置。 ------ #### [ Linux/macOS ] 若要 適用於 C\$1\$1 的 AWS SDK 在 Linux/macOS 上使用 ，您需要下列其中一項： + GNU 編譯器集合 (GCC) 4.9 或更新版本，或 + Clang 3.3 或更新版本。 ------ #### [ Windows ] 若要 適用於 C\$1\$1 的 AWS SDK 在 Windows 上使用 ，您需要下列其中一項： + Microsoft Visual Studio 2015 或更新版本， + GNU 編譯器集合 (GCC) 4.9 或更新版本，或 + Clang 3.3 或更新版本。 ------ ## 使用 vcpkg 取得 SDK **重要** 可用的 vcpkg 分佈由外部參與者支援，而非透過 提供 AWS。透過[從來源安裝](sdk-from-source.md) ，一律可使用最新版本。 [vcpkg](https://github.com/Microsoft/vcpkg) 是由外部參與者更新和維護的套件管理員。請注意，此套件管理員不是透過 提供 AWS ，而且可能不會反映 的最新可用版本 適用於 C\$1\$1 的 AWS SDK。當版本由 發行 AWS 和透過外部套件管理員提供時，會發生延遲。透過[從來源安裝](sdk-from-source.md) ，一律可使用最新版本。 您必須在系統上安裝 [vcpkg](https://github.com/Microsoft/vcpkg)。 + 按照 [vcpkg](https://github.com/Microsoft/vcpkg) GitHub Readme 上的指示下載和引導 vcpkg，並在出現提示時替換下列選項： + 在這些指示中，系統會引導您輸入： ``` .\vcpkg\vcpkg install [packages to install] ``` 若要安裝整個開發套件，請在括號中附加套件名稱，輸入`.\vcpkg\vcpkg install "aws-sdk-cpp[*]" --recurse`或僅指出要安裝的開發套件特定服務，例如： `.\vcpkg\vcpkg install "aws-sdk-cpp[s3, ec2]" --recurse` 輸出會顯示訊息，包括下列項目： ``` CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/vcpkg/scripts/buildsystems/vcpkg.cmake" ``` + 複製完整的`-DCMAKE_TOOLCHAIN_FILE`命令以供稍後用於 CMake。vcpkg GitHub 讀我檔案也會指示您的工具集應在何處使用此項目。 + 您可能還需要記下您透過 vcpkg 安裝的建置組態類型。主控台輸出會顯示建置組態和 SDK 的版本。下列範例輸出指出建置組態是 "x86-windows"，而安裝的 適用於 C\$1\$1 的 AWS SDK 版本是 1.8。 ``` The following packages will be built and installed: aws-sdk-cpp[core,dynamodb,kinesis,s3]:x86-windows -> 1.8.126#6 ``` 安裝 之後 適用於 C\$1\$1 的 AWS SDK，您可以使用 SDK 開發自己的應用程式。中顯示的範例會[建立簡單的應用程式](build-cmake.md)報告您擁有的 Amazon S3 儲存貯體。 # 針對適用於 C\$1\$1 組建問題的 AWS SDK 進行故障診斷 適用於 C\$1\$1 的 AWS SDK 從來源建置 時，可能會出現下列一些常見的建置問題。 **Topics** + [CMake 錯誤：找不到「AWSSDK」提供的套件組態檔案](#could-not-find-package) + [CMake 錯誤：找不到載入檔案 （且您使用的是 SDK 1.8 版）](#could-not-load-file) + [CMake 錯誤：找不到載入檔案](#could-not-load-file2) + [執行時間錯誤：無法繼續，因為`aws-*.dll`找不到](#dll-was-not-found) ## CMake 錯誤：找不到「AWSSDK」提供的套件組態檔案 如果找不到安裝的 SDK，CMake 會引發下列錯誤。 ``` 1> [CMake] CMake Error at C:\CodeRepos\CMakeProject1\CMakeLists.txt:4 (find_package): 1> [CMake] Could not find a package configuration file provided by "AWSSDK" with any 1> [CMake] of the following names: 1> [CMake] 1> [CMake] AWSSDKConfig.cmake 1> [CMake] awssdk-config.cmake 1> [CMake] 1> [CMake] Add the installation prefix of "AWSSDK" to CMAKE_PREFIX_PATH or set 1> [CMake] "AWSSDK_DIR" to a directory containing one of the above files. If "AWSSDK" 1> [CMake] provides a separate development package or SDK, be sure it has been 1> [CMake] installed. ``` 若要解決此錯誤，請告訴 CMake 在何處尋找安裝的 SDK （例如，由於安裝 SDK 而產生的資料夾 ([Windows](setup-windows.md)、[Linux/macOS](setup-linux.md))。將下列命令插入 檔案`find_package()`，再呼叫 `CMakeLists.txt`。如需範例，請參閱[使用適用於 C\$1\$1 的 AWS SDK 建立簡單的應用程式](build-cmake.md)。 ``` list(APPEND CMAKE_PREFIX_PATH "C:\\Program Files (x86)\\aws-cpp-sdk-all\\lib\\cmake") ``` ## CMake 錯誤：找不到載入檔案 （且您使用的是 SDK 1.8 版） 如果找不到已安裝的程式庫，CMake 會引發下列錯誤。 ``` 1> [CMake] include could not find load file: 1> [CMake] 1> [CMake] C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-c-common/cmake/static/aws-c-common-targets.cmake 1> [CMake] include could not find load file: 1> [CMake] 1> [CMake] C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-checksums/cmake/static/aws-checksums-targets.cmake 1> [CMake] include could not find load file: 1> [CMake] 1> [CMake] C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-checksums/cmake/static/aws-checksums-targets.cmake ``` 若要解決此錯誤，請告訴 CMake 在何處尋找安裝的 SDK （例如，由於安裝 SDK 而產生的資料夾 ([Windows](setup-windows.md)、[Linux/macOS](setup-linux.md))。將下列命令插入 檔案`find_package()`，再呼叫 `CMakeLists.txt`。如需範例，請參閱[使用適用於 C\$1\$1 的 AWS SDK 建立簡單的應用程式](build-cmake.md)。 ``` #Set the location of where Windows can find the installed libraries of the SDK. if(MSVC) string(REPLACE ";" "/aws-cpp-sdk-all;" SYSTEM_MODULE_PATH "${CMAKE_SYSTEM_PREFIX_PATH}/aws-cpp-sdk-all") list(APPEND CMAKE_PREFIX_PATH ${SYSTEM_MODULE_PATH}) endif() ``` 此解決方案僅適用於 SDK 的 v1.8，因為這些相依性在較新版本中的處理方式不同。1.9 版透過在 `aws-sdk-cpp`和 `aws-c-*`程式庫之間引入中繼層來解決這些問題。這個新 layer 稱為 `aws-crt-cpp` ，是適用於 C\$1\$1 的 SDK 的 git 子模組。 `aws-crt-cpp`也有程式`aws-c-*`庫 （包括 `aws-c-common`、 `aws-checksums`` aws-c-event-stream`等） 做為自己的 git 子模組。這可讓適用於 C\$1\$1 的 SDK 以遞迴方式取得所有 CRT 程式庫，並改善建置程序。 ## CMake 錯誤：找不到載入檔案 如果找不到已安裝的程式庫，CMake 會引發下列錯誤。 ``` CMake Error at C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-c-auth/cmake/aws-c-auth-config.cmake:11 (include): include could not find load file: C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-c-auth/cmake/static/aws-c-auth-targets.cmake ``` 若要解決此錯誤，請指示 CMake 建置共用程式庫。將下列命令插入 檔案`find_package()`，再呼叫 `CMakeLists.txt`。如需範例，請參閱[使用適用於 C\$1\$1 的 AWS SDK 建立簡單的應用程式](build-cmake.md)。 ``` set(BUILD_SHARED_LIBS ON CACHE STRING "Link to shared libraries by default.") ``` ## 執行時間錯誤：無法繼續，因為`aws-*.dll`找不到 如果找不到必要的 DLL，CMake 會引發類似下列的錯誤。 ``` The code execution cannot proceed because aws-cpp-sdk-[dynamodb].dll was not found. Reinstalling the program may fix this problem. ``` 發生此錯誤是因為適用於 C\$1\$1 的 SDK 所需的程式庫或可執行檔無法在與應用程式可執行檔相同的資料夾中使用。若要解決此錯誤，請在可執行檔位置複製 SDK 組建輸出。錯誤的特定 DLL 檔案名稱會根據您使用 AWS 的服務而有所不同。執行下列*其中一項*操作： + 將 適用於 C\$1\$1 的 AWS SDK 安裝的 `/bin` 資料夾內容複製到應用程式的建置資料夾。 + 在您的 `CMakeLists.txt`檔案中，使用巨集 AWSSDK\$1CPY\$1DYN\$1LIBS 為您複製這些項目。 將呼叫新增至 `AWSSDK_CPY_DYN_LIBS(SERVICE_LIST "" ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_BUILD_TYPE})` `AWSSDK_CPY_DYN_LIBS(SERVICE_LIST "" ${CMAKE_CURRENT_BINARY_DIR})`或 `CMakeLists.txt` 檔案，以使用此巨集為您執行複製。如需範例，請參閱[使用適用於 C\$1\$1 的 AWS SDK 建立簡單的應用程式](build-cmake.md)。 為您的建置環境選擇正確的複製路徑。透過命令列建置經常將建置輸出放入子資料夾 (`/Debug`)，但 Visual Studio 和其他 IDEs 通常不會。驗證輸出可執行檔的位置，並確保巨集正在複製到該位置。進行這些類型的變更時，最佳實務是刪除組建輸出目錄的內容，以便您取得下一個組建的乾淨起點。