AWS Command Line Interface
使用者指南

組態與登入資料檔案設定

您可以將常用的組態設定和登入資料儲存在 AWS CLI 維護的檔案中。系統會將檔案分割成幾個區段,您可依名稱來參考這些區段。這些稱為「描述檔」。除非您另行指定,否則 CLI 會使用名為 default 的描述檔中找到的設定。若要使用替代設定,您可以建立和參考額外的描述檔。您也可以設定其中一個支援的環境變數,或使用命令列參數,以覆寫個別設定。

組態設定存放在何處?

AWS CLI 會將您使用 aws configure 指定的登入資料,存放在主目錄中名為的 .aws 的資料夾中名為 credentials 的本機檔案。您使用 aws configure 指定的其他組態選項存放在名為 config 的本機檔案中,而此檔案也是存放在主目錄中的 .aws 資料夾。主目錄的位置根據作業系統而不同,但在 Windows 中是使用環境變數 %UserProfile% 來參考,而在 Unix 系統中是使用 $HOME~ (波狀符號) 來參考。

例如,下列命令列出 .aws 資料夾的內容。

Linux, macOS, or Unix

$ ls ~/.aws

Windows

C:\> dir "%UserProfile%\.aws"

AWS CLI 使用兩個檔案來將敏感的登入資料資訊 (在 ~/.aws/credentials 中),與較不敏感的組態選項分開存放 (在 ~/.aws/config 中)。

您可以將 AWS_CONFIG_FILE 環境變數設為其他本機路徑,以指定 config 檔案的非預設位置。如需詳細資訊,請參閱「環境變數」。

將登入資料存放到組態檔中

AWS CLI 也可以從 config 檔案中讀取登入資料。您可以將所有的設定檔設置保存在單一檔案中。如果針對一個設定檔的兩個位置都有登入資料 (假如您使用 aws configure 來更新設定檔的金鑰),則登入資料檔案中的金鑰具有優先順序。

各種語言軟體開發套件 (SDK) 也使用這些檔案。如果您除了 AWS CLI 之外還使用其中一個開發套件,則若登入資料不是儲存在其自己的檔案中,您可能會收到額外的警告。

CLI 為上一部分中設定的設定檔產生之檔案如下所示。

~/.aws/credentials

[default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

~/.aws/config

[default] region=us-west-2 output=json

注意

上述範例顯示的檔案含有單一預設描述檔。關於含有多個具名設定檔的檔案範例,請參閱命名設定檔

當您使用指定 IAM 角色的共用描述檔時,AWS CLI 會呼叫 AWS STS AssumeRole 操作來擷取臨時登入資料。然後會存放這些登入資料 (在 ~/.aws/cli/cache 中)。後續的 AWS CLI 命令會使用快取的臨時登入資料,直到過期為止,此時 AWS CLI 會自動重新整理登入資料。

支援的 config 檔案設定

config 檔案中支援下列設定。將會使用指定的 (或預設) 描述檔中列出的值,除非因為有相同名稱的環境變數或相同名稱的命令列選項而被覆寫。

您可以使用文字編輯器直接編輯組態檔,或使用 aws configure set 命令,以進行這些設定。使用 --profile 設定來指定您想要修改的描述檔。例如,以下命令會在名為 integ 的描述檔中進行 region 設定。

aws configure set region us-west-2 --profile integ

您也可以使用 get 子命令擷取任何設定的值。

$ aws configure get region --profile default us-west-2

如果輸出是空的,則設定未明確設定,將會使用預設值。

全域設定

api_versions

有些 AWS 服務會維護多個 API 版本,以支援回溯相容性。在預設情況下,CLI 命令會使用最新可用的 API 版本。您可以在 config 檔案中包含 api_versions 設定,以指定要用於描述檔的 API 版本。

這是「巢狀」設定,後面接著一或多行縮排,每一行識別一個 AWS 服務和要使用的 API 版本。請參閱每個服務的文件,以了解可用的 API 版本。

以下範例說明如何指定兩個 AWS 服務的 API 版本。這些 API 版本僅適用於在包含這些設定的描述檔下執行的命令。

api_versions = ec2 = 2015-03-01 cloudfront = 2015-09-017

此設定沒有對等環境變數或命令列參數。

aws_access_key_id

指定登入資料中使用的 AWS 存取金鑰來驗證命令請求。雖然這可以存放在 config 檔案中,但建議您存放在 credentials 檔案中。

可由 AWS_ACCESS_KEY_ID 環境變數所覆寫。您不能將存取金鑰 ID 指定為命令列選項。

aws_access_key_id = 123456789012
aws_secret_access_key

指定登入資料中使用的 AWS 私密金鑰來驗證命令請求。雖然這可以存放在 config 檔案中,但建議您存放在 credentials 檔案中。

可由 AWS_SECRET_ACCESS_KEY 環境變數所覆寫。您不能將私密存取金鑰指定為命令列選項。

aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token

指定 AWS 工作階段字符。只有當您手動指定臨時的安全登入資料時,才需要工作階段字符。雖然這可以存放在 config 檔案中,但建議您存放在 credentials 檔案中。

可由 AWS_SESSION_TOKEN 環境變數所覆寫。您不能將工作階段字符指定為命令列選項。

aws_session_token = AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
ca_bundle

指定用於驗證 SSL 憑證的 CA 憑證套件 (副檔名為 .pem 的檔案)。

可由 AWS_CA_BUNDLE 環境變數或 --ca-bundle 命令列選項所覆寫。

ca_bundle = dev/apps/ca-certs/cabundle-2019mar05.pem
cli_follow_urlparam

指定 CLI 在以 http://https:// 開頭的命令列參數中是否嘗試跟隨 URL 連結。啟用時,擷取的內容會作為參數值,而不是 URL。

  • true:這是預設值。設定時,將擷取以 http://https:// 開頭的任何字串參數,而任何下載的內容會作為命令的參數值。

  • false:CLI 不會將開頭為 http://https:// 的參數字串值和其他字串視為不同。

此項目沒有同等環境變數或命令列選項。

cli_follow_urlparam = false
cli_timestamp_format

指定輸出包含的時間戳記值格式。您可以指定下列任一值:

  • iso8601:這是 AWS CLI 第 2 版 的預設值。AWS CLI 會根據 ISO 8601 將所有時間戳記重新格式化。

  • wire:這是 AWS CLI 第 1 版 的預設值。AWS CLI 會確切顯示 HTTP 查詢回應中所接收的所有時間戳記值。

此項目沒有同等環境變數或命令列選項。

cli_timestamp_format = iso8601
credential_process

指定外部命令,供 CLI 執行來產生或擷取此命令所用的身份驗證登入資料。命令必須以特定格式傳回登入資料。如需如何使用此設定的詳細資訊,請參閱透過外部程序取得登入資料

此項目沒有同等環境變數或命令列選項。

credential_process = /opt/bin/awscreds-retriever --username susan
credential_source

在 EC2 執行個體或 EC2 容器中使用,以指定 AWS CLI 可以找到用於擔任您使用 role_arn 參數所指定角色的登入資料。您無法在同一個描述檔中同時指定 source_profilecredential_source

此參數可以有下列三個值中的一個:

  • Environment:從環境變數擷取來源登入資料。

  • Ec2InstanceMetadata:使用連接至 EC2 執行個體描述檔的 IAM 角色做為來源登入資料。

  • EcsContainer:使用連接至 ECS 容器的 IAM 角色做為來源登入資料。

credential_source = Ec2InstanceMetadata
duration_seconds

指定角色工作階段的最大持續時間 (以秒為單位)。此值的範圍可以從 900 秒 (15 分鐘) 到角色的最大工作階段持續時間設定的值 (其最大值為 43200)。這是選用參數,並且依預設,此值會設為 3600 秒。

external_id

唯一識別符,第三方用來在其客戶帳戶擔任角色。這對應到 ExternalId 操作的 AssumeRole 參數。此參數為選用,除非角色的信任政策指定 ExternalId 必須是特定值。

mfa_serial

擔任角色時使用的 MFA 裝置識別碼。只有在所擔任角色的信任政策包含要求 MFA 身份驗證的條件時才具強制性。此值可以是硬體裝置的序號 (例如 GAHT12345678) 或虛擬 MFA 裝置的 Amazon Resource Name (ARN) (例如 arn:aws:iam::123456789012:mfa/user)。

output

對於請求使用此描述檔的命令,指定預設輸出格式。您可以指定下列任何值:

  • json:這是預設值。輸出的格式為 JSON 字串。

  • text:輸出的格式為多行 Tab 鍵分隔字串值,如果您要將輸出傳遞至文字處理器 (例如 grepsedawk),這會很有用。

  • table:輸出的格式為使用字元 +|- 形成儲存格框線的表格。它通常以「方便人類使用」的格式來呈現資訊,這種格式比其他格式更容易閱讀,但在編寫程式方面較不有用。

可由 AWS_DEFAULT_OUTPUT 環境變數或 --output 命令列選項所覆寫。

output = table
parameter_validation

指定 CLI 用戶端在將參數傳送到 AWS 服務端點之前,是否嘗試驗證參數。

  • true:這是預設值。設定時,CLI 會執行命令列參數的本機驗證。

  • false:設定時,CLI 在將命令列參數傳送到 AWS 服務端點之前,不會驗證參數。

此項目沒有同等環境變數或命令列選項。

parameter_validation = false
region

對於請求使用此描述檔的命令,指定要將請求傳送到其中的預設 AWS 區域。您可以指定所選服務可用的任何區域代碼,如 Amazon Web Services General Reference中的 AWS 區域和端點所列。

可由 AWS_DEFAULT_REGION 環境變數或 --region 命令列選項所覆寫。

region = us-west-2
role_arn

指定您要用來執行 AWS CLI 命令之 IAM 角色的 Amazon Resource Name (ARN)。您還必須指定下列其中一個參數,以識別具有許可能擔任此角色的登入資料:

  • source_profile

  • credential_source

role_arn = arn:aws:iam::123456789012:role/role-name
role_session_name

指定要連接到角色工作階段的名稱。此值會在 AWS CLI 呼叫 AssumeRole 操作時提供給 RoleSessionName 參數,並成為所擔任角色使用者 ARN 的一部分: arn:aws:sts::123456789012:assumed-role/role_name/role_session_name。這是選擇性的參數。若您未提供此值,將會自動產生工作階段名稱。此名稱會出現在與此工作階段相關聯之項目的 AWS CloudTrail 日誌中。

role_session_name = maria_garcia_role
source_profile

指定具有長期登入資料、AWS CLI 可用來擔任您使用 role_arn 參數所指定角色的具名描述檔。您無法在同一個描述檔中同時指定 source_profilecredential_source

source_profile = production-profile
sso_account_id

包含的 IAM 角色具有您要授與給關聯 AWS SSO 使用者權限的 AWS 帳戶 ID。

此設定沒有環境變數或命令列選項。

sso_account_id = 123456789012
sso_region

包含 AWS SSO 入口網站主機的 AWS 區域。這與預設的 CLI region 參數不同,且可以是與其不同的區域。

此設定沒有環境變數或命令列選項。

aws_sso_region = us_west-2
sso_role_name

使用此設定檔時,定義使用者權限的 IAM 角色的易記名稱。

此設定沒有環境變數或命令列選項。

sso_role_name = ReadAccess
sso_start_url

指向組織 AWS SSO 使用者入口網站的 URL。AWS CLI 使用此 URL 與 AWS SSO 服務建立工作階段,以驗證其使用者。

此設定沒有環境變數或命令列選項。

sso_start_url = https://my-sso-portal.awsapps.com/start
sts_regional_endpoints

指定 AWS CLI 用戶端用於與 AWS Security Token Service (AWS STS) 通訊的 AWS 服務端點。您可以指定下列兩個值中的一個值:

  • regional:AWS CLI 使用對應於已設定區域的 AWS STS 端點。例如,如果用戶端設為使用 us-west-2,則會對端點 sts.us-west-2.amazonaws.com 區域端點 (而非全域 sts.amazonaws.com 端點) 進行 AWS STS 的所有呼叫。

  • legacy:下列區域使用全域 STS 端點 sts.amazonaws.comap-northeast-1ap-south-1ap-southeast-1ap-southeast-2aws-globalca-central-1eu-central-1eu-north-1eu-west-1eu-west-2eu-west-3sa-east-1us-east-1us-east-2us-west-1us-west-2。所有其他區域使用其各自的區域端點。

web_identity_token_file

指定檔案的路徑,該檔案包含由身分供應商提供的 OAuth 2.0 存取字符或 OpenID Connect ID 字符。AWS CLI 會載入此檔案的內容,並將其做為 WebIdentityToken 引數傳遞至 AssumeRoleWithWebIdentity 操作。

tcp_keepalive

指定 CLI 用戶端是否使用 TCP 持續連線封包。

此項目沒有同等環境變數或命令列選項。

tcp_keepalive = false

S3 自訂命令設定

Amazon S3 支援多種設定來設定 CLI 如何執行 S3 操作。有些適用於 s3apis3 命名空間中的所有 S3 命令。其他則專用於 S3「自訂」命令,這些命令摘錄常見的操作,而不僅止於一對一映射到 API 操作。aws s3 傳輸命令 cpsyncmvrm 有額外設定,供您用來控制 S3 傳輸。

您可以在 config 檔案中指定 s3 巢狀設定,以設定所有這些選項。每個設定都各自一行縮排。

注意

這些設定完全是選用。您無需設定任何這些設定,就應該能夠成功使用 aws s3 傳輸命令。提供這些設定可讓您基於效能而調整,或控制您執行這些 aws s3 命令的特定環境。

以下設定適用於 s3s3api 命名空間中的任何 S3 命令。

addressing_style

指定要使用的定址樣式。這控制儲存貯體名稱位於主機名稱還是 URL 的一部分。有效值為 pathvirtualauto。預設值為 auto

建構 S3 端點有兩種樣式。第一種稱為 virtual,並且在主機名稱中包含儲存貯體名稱。例如:https://bucketname.s3.amazonaws.com。或者,如果使用 path 樣式,則儲存貯體名稱就如同 URI 中的路徑。例如:https://s3.amazonaws.com/bucketname。CLI 中的預設值是使用 auto,將會儘可能嘗試使用 virtual 樣式,但在需要時會回復為 path 樣式。例如,如果您的儲存貯體名稱與 DNS 不相容,則儲存貯體名稱不能做為主機名稱的一部分,而必須在路徑中。使用 auto 時,CLI 會偵測到這個情況,並自動切換到 path 樣式。如果您將定址樣式設為 path,則必須確保您在 AWS CLI 中設定的 AWS 區域符合儲存貯體的區域。

payload_sigining_enabled

指定是否以 SHA256 簽署 sigv4 承載。在預設情況下,使用 https 來串流上傳時 (UploadPartPutObject) 會停用此參數。根據預設,在串流上傳時 (UploadPartPutObject),這會設定為 false,但僅限於 ContentMD5 存在 (依預設會產生) 且端點使用 HTTPS 的情況。

如果設定為 true,S3 請求會收到 SHA256 檢查總和形式的額外內容驗證,這是為您計算並且包含在請求簽章中。如果設定為 false,則不計算檢查總和。停用此參數有助於降低檢查總和計算所造成的效能負荷。

use_dualstack_endpoint

對所有 s3s3api 命令使用 Amazon S3 雙重 IPv4 / IPv6 端點。預設值為 false。這與 use_accelerate_endpoint 設定互斥。

如果設定為 true,CLI 會將所有 Amazon S3 請求導引至所設定區域的雙重 IPv4/IPv6 端點。

use_accelerate_endpoint

對所有 s3s3api 命令使用 Amazon S3 加速端點。預設值為 false。這與 use_dualstack_endpoint 設定互斥。

如果設定為 true,CLI 會將所有 Amazon S3 請求引導至位於 s3-accelerate.amazonaws.com 的 S3 加速端點。若要使用這個端點,您必須啟用儲存貯體來使用 S3 加速。所有請求都是使用虛擬樣式的儲存貯體定址所傳送:my-bucket.s3-accelerate.amazonaws.com。不會將任何 ListBucketsCreateBucketDeleteBucket 請求傳送至加速端點,因為該端點不支援這些操作。如果將任何 s3s3api 命令的 --endpoint-url 參數設為 https://s3-accelerate.amazonaws.comhttp://s3-accelerate.amazonaws.com,也可以設定此行為。

以下設定只適用於 s3 命名空間命令集的命令:

max_bandwidth

指定往返於 Amazon S3 上傳和下載資料時可消耗的最大頻寬。預設值是無限制。

這限制 S3 命令在往返於 S3 傳輸資料時可使用的最大頻寬。這個值僅適用於上傳和下載,不適用於複製或刪除。值以每秒位元組數為單位。值可以指定為:

  • 整數。例如,1048576 將最大頻寬使用量設定為每秒 1 百萬位元組。

  • 整數加上速率尾碼。您可以使用 KB/sMB/sGB/s 指定速率尾碼。例如:300KB/s10MB/s

一般而言,我們建議您先降低 max_concurrent_requests,以嘗試降低頻寬耗用量。如果這還無法將限制頻寬耗用量調到所需的速率,則您可以使用 max_bandwidth 設定來進一步限制頻寬耗用量。這是因為 max_concurrent_requests 控制目前執行多少個執行緒。如果您先降低 max_bandwidth,但 max_concurrent_requests 設定還是很高,則會導致執行緒不必要地等待,結果是消耗過多的資源和連線逾時。

max_concurrent_requests

指定並行請求數量上限。預設值為 10。

aws s3 傳輸命令是多執行緒。隨時可以有多個 Amazon S3 請求在執行。例如,當您使用命令 aws s3 cp localdir s3://bucket/ --recursive 將檔案上傳到 S3 儲存貯體時,AWS CLI 可以同時上傳檔案 localdir/file1localdir/file2localdir/file3。設定 max_concurrent_requests 會指定可同時執行的傳輸操作數量上限。

由於幾個原因,您可能需要變更這個值:

  • 降低這個值 – 在某些環境中,10 個並行請求的預設值可能拖垮系統。這可能導致連線逾時,或使系統的回應能力變慢。降低這個值可讓 S3 傳輸命令耗用較少的資源。缺點是 S3 傳輸可能需要更久才會完成。如果您使用工具來限制頻寬,則可能需要降低這個值。

  • 提高這個值 – 在某些情況下,您可能希望 S3 傳輸依需要儘量使用網路頻寬,以儘快完成。在這種情況下,預設的並行請求數量可能還不足以利用所有可用的網路頻寬。提高此值可以縮短完成 S3 傳輸所花的時間。

max_queue_size

指定任務佇列中的任務數量上限。預設值為 1000。

AWS CLI 在內部採用一種模型將 S3 任務排入佇列,然後由消費者執行,而其數量受限於 max_concurrent_requests。任務通常會映射到單一 S3 操作。例如,任務可能是 PutObjectTaskGetObjectTaskUploadPartTask。任務新增到佇列的速率可比消費者完成任務的速率快很多。為了避免無限制成長,任務佇列大小會受限於特定大小。這個設定會變更該數量上限的值。

您通常不需要變更此設定。此設定也對應到 CLI 知道需要執行的任務數量。這表示根據預設,CLI 只能看到前 1000 個任務。在 S3 命令知道執行的任務總數之前,進度列會顯示總計 ...。提高此值表示 CLI 可以更快知道所需的任務總數 (假設佇列速率比任務完成速率更快)。缺點是較大的佇列大小上限需要更多記憶體。

multipart_chunksize

指定 CLI 在分段傳輸個別檔案時使用的區塊大小。預設值為 8 MB,至少 5 MB。

當檔案傳輸超過 multipart_threshold 時,CLI 會將檔案分割成此大小的區塊。指定這個值所使用的語法與 multipart_threshold 相同,包括以整數指定位元組數量,或使用大小和尾碼。

multipart_threshold

指定 CLI 在分段傳輸個別檔案時使用的大小閾值。預設值為 8MB。

當上傳、下載或複製檔案時,如果檔案超過該大小,S3 命令會切換到分段操作。您有兩種方式可以指定此值:

  • 以位元組為單位的檔案大小。例如,1048576

  • 附上大小尾碼的檔案大小。您可以使用 KBMBGBTB。例如:10MB1GB

    注意

    對於可用於分段操作的有效值,S3 可以施加限制。如需詳細資訊,請參閱 Amazon Simple Storage Service Developer Guide中的 S3 分段上傳文件

這些設定全部都在 config 檔案中的最上層 s3 索引鍵之下設定,如以下 development 描述檔的範例所示:

[profile development] s3 = max_concurrent_requests = 20 max_queue_size = 10000 multipart_threshold = 64MB multipart_chunksize = 16MB max_bandwidth = 50MB/s use_accelerate_endpoint = true addressing_style = path