快速入門AWS CLI與AWS PowerShell

因工作所需，且沒有測試區可以玩，就自己註冊了一個 AWS 免費帳戶，需要有 Email、手機、信用卡三項。基本上都是填完資料後按「下一步」，不過，最後驗證手機門號時，我只有按「撥打電話」才成功，其他 SMS 之類的我都沒有成功。

AWS CLI

由於工作是需要解 AWS 自動化作業，所以不適用網頁操作，這一步需要瞭解 AWS CLI(Command Line Interface)。

目前有 Version 1, Version 2。如果你是要用在 Production 環境，撰文當下是建議採用 Version 1 版本。透過安裝網頁進行下載安裝檔，在 cmd.exe 驗證：

C:\>aws --version
aws-cli/1.16.309 Python/3.6.0 Windows/10 botocore/1.13.45

可定期查詢更新：https://github.com/aws/aws-cli/releases

Profile

組態與登入資料檔案設定

我們利用 aws configure 進行組態，會把組態設定和登入資料儲存在 AWS CLI 維護的檔案中。這些稱為「Profile(描述檔)」。

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

這面會有兩個檔案，都是明碼儲存。

~/.aws/credentials 儲存憑證資訊

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

~/.aws/config 儲存組態資料

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

未指定 --profile 預設儲存至 [default]。由於是明碼，也可以手動編輯。我們可以同時儲存多組 Profile。再依不同服務選擇 Profile 來連接使用。

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

[user1]
aws_access_key_id=AKIAI44QH8DHBEXAMPLE
aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

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

[profile user1]
region=us-east-1
output=text

看成程式裡「連線字串」或許好懂一些了。credentials 憑證的 key 是由 IAM(AWS Identity and Access Management) 取得。舉例來說，透過 IAM 建立一個 kkbruce 使用者，並且授權存取 S3 服務的權限。那麼除了 S3 服務之外，kkbruce 並無法使用其他 AWS 服務。

支援的 configure 檔案設定

C:\>aws configure set region us-west-2 --profile integ
C:\>aws configure get region --profile default

可以用 set 設定 Profile，用 get 取得 Profile。

使用 AWS CLI

C:\>aws help
C:\>aws s3 help
C:\>aws s3 cp help

help 可以取得說明。可以一層一層往下取得。

AWS CLI 命令結構：

aws <command> <subcommand> [options and parameters]

<command> 通常對應 AWS 的服務，例如：s3, ec2 等。可由 aws help 取得。
<subcommand> 對此服務進行哪些操作。例如對 s3 服務可以進行 cp、mv、rm 等基本操作。
[options and parameters] 操作所需的選項或參數。

選項與參數的部份，可以輸入完整 JSON，也支援速記語法：

結構速記：--option "key1=value1,key2=value2,key3=value3"
清單速記：--option value1 value2 value3

在 AWS CLI 執行之後，可以執行以下指令來取得回傳碼，0 代表成功。

# powershell
PS C:\>echo $lastexitcode
# cmd
C:\>echo %errorlevel%

如果有非 0 回傳碼，那麼加上 --debug 參數可以產生詳細執行步驟的輸出。完整回傳碼文件請參考：AWS CLI 的傳回碼。

AWS Identity and Access Management

前面提到，Profile 裡 Key 是由 IAM 提供。建立 IAM 使用者，可以參考此篇建立您的第一個 IAM 管理員使用者和群組來快速瞭解。建立之後，就能取得 Key 來設定 Profile。

例如，使用我建立的 kkbruce profile 來進行查詢 IAM 使用者：

C:\>aws iam list-users --profile kkbruce
{
    "Users": [
        {
            "Path": "/",
            "UserName": "Administrator",
            "UserId": "UserId",
            "Arn": "arn:aws:iam::<Number>:user/Administrator",
            "CreateDate": "2019-12-25T08:46:27Z"
        },
        {
            "Path": "/",
            "UserName": "AWS_Admin",
            "UserId": "UserId",
            "Arn": "arn:aws:iam::<Number>:user/AWS_Admin",
            "CreateDate": "2019-12-25T09:55:05Z"
        }
    ]
}

Amazon CLI for S3

瞭解 AWS CLI 與 IAM 之後，我們就能開始在 CLI 之下來完成工作。

記得，沒有特別設定 --profile，預設讀取 [default] 來連線服務。

S3 儲存貯體命名必須是全域唯一。如果有同名，會得到 BucketAlreadyExists 錯誤。

例如：aws s3 mb s3://my-first-backup-bucket

C:\>aws s3 mb s3://kkbruce
C:\>aws s3 ls s3://kkbruce

aws s3 mb 是建立儲存體，aws s3 ls 是列出清單。目前為空。

C:\>aws s3 cp "d:\Downloads\demo.txt" s3://kkbruce
upload: .\demo.txt to s3://kkbruce/demo.txt

C:\>aws s3 ls s3://kkbruce
2019-12-30 16:04:36          0 demo.txt

aws s3 cp 是複製，cp <source> <dest> 從來源複製至目的地。把上面範例路徑對調就變成下載了：

C:\>aws s3 cp s3://kkbruce/demo.txt .\demo2.txt
download: s3://kkbruce/demo.txt to .\demo2.txt

要刪除檔案，請使用 s3 rm：

C:\>aws s3 rm s3://kkbruce/demo.txt
delete: s3://kkbruce/demo.txt

要刪除整個儲存體：

C:\>aws s3 ls

C:\>aws s3 rb s3://kkbruce
remove_bucket: kkbruce

先列出所有儲存體，進行刪除 kkbruce 儲存體。如果非空的，會不能刪除，加上 --force 強制刪除。

如果你在儲存體裡建立目錄：

C:\>aws s3 ls s3://kkbruce
                           PRE test/

看起來會是像這樣 PRE FolderName/。而最簡單的建立方式，是在一開始的 s3 路徑就指定好完整路徑，s3 會動自建立階層關係：

C:\>aws s3 cp "d:\Downloads\demo.txt" s3://kkbruce/test/demo.txt

AWS Tools for PowerShell

由於 AWS CLI 要整合寫成腳本不是那麼容易，AWS 也另外有提供 PowerShell 版本。

首先是要安裝 AWS Tools for PowerShell on Windows，你會看到三套 AWS Tools 工具：

AWS.Tools：模組化的 PowerShell，每個 AWS 服務可獨立安裝使用。
AWSPowerShell.NetCore：單一 PowerShell 安裝檔，含所有 AWS 服務模組，當然，使用磁碟容量比模組化大上很多。
AWSPowerShell：傳統 Windows 使用的版本，所有 AWS 服務均支援此版本。

AWS.Tools 與 AWSPowerShell.NetCore 可跨平台安裝使用。我喜歡小巧應用，而且又是 PowerShell Core 支援，模組化的 AWS.Tools 是不錯的選擇。

PS C:\>Install-Module -Name AWS.Tools.Installer -Force
PS C:\>Import-Module AWS.Tools.Installer
PS C:\>Install-AWSToolsModule AWS.Tools.Common -CleanUp
PS C:\>Import-Module AWS.Tools.Common
PS C:\>Install-AWSToolsModule AWS.Tools.S3 -CleanUp
PS C:\>Import-Module AWS.Tools.S3
PS C:\>Get-Command -Noun *S3*

先安裝 AWS.Tools.Installer 之後，就可以執行 Install-AWSToolsModule 來安裝相關 PowerShell 模式。AWS.Tools.Common 主要包含開發或管理相關 cmdlet。為測試 AWS S3 服務，所以我們也安裝 AWS S3 模組。所有模組都可以在 PowerShell Gallery 搜尋後進行安裝。安裝成功後，可以簡單查詢一下含"S3"關鍵字的指令。AWS.Tools 有提供PowerShell 線上文件，在查詢相關 cmdlet 的用法上方便許多。

我在內部主機，因無法連網，所以下載 AWSPowerShell 並進行安裝。就 Common、S3 的指令與參數，使用起來沒有不同。

Common cmdlet

PS C:\>Get-AWSCredential -ListProfile

WARNING: The ListProfile switch is deprecated and will be removed from a future release.  Please use ListProfileDetail instead.

kkbruce
default

PS C:\>Get-AWSCredential -ListProfileDetail

ProfileName    StoreTypeName         ProfileLocation
-----------    -------------         ---------------
kkbruce        SharedCredentialsFile C:\Users\BruceChen\.aws\credentials
default        SharedCredentialsFile C:\Users\BruceChen\.aws\credentials

列舉目前的 Profile，注意第一個 -ListProfile 未來會被移除。再提醒，預設指令未指定 Profile 會使用 default 憑證。

PS C:\>Get-AWSRegion

Region         Name                      IsShellDefault
------         ----                      --------------
ap-east-1      Asia Pacific (Hong Kong)           False
ap-northeast-1 Asia Pacific (Tokyo)               False
ap-northeast-2 Asia Pacific (Seoul)               False
ap-south-1     Asia Pacific (Mumbai)              False
ap-southeast-1 Asia Pacific (Singapore)           False
ap-southeast-2 Asia Pacific (Sydney)              False
ca-central-1   Canada (Central)                   False
eu-central-1   EU Central (Frankfurt)             False
eu-north-1     EU North (Stockholm)               False
eu-west-1      EU West (Ireland)                  False
eu-west-2      EU West (London)                   False
eu-west-3      EU West (Paris)                    False
me-south-1     Middle East (Bahrain)              False
sa-east-1      South America (Sao Paulo)          False
us-east-1      US East (Virginia)                 False
us-east-2      US East (Ohio)                     False
us-west-1      US West (N. California)            False
us-west-2      US West (Oregon)                   False
us-iso-east-1  US ISO East                        False
us-isob-east-1 US ISOB East (Ohio)                False

在 AWS CLI 設定憑證時，會詢問區域，如果不知道，可以這裡查詢。另外，Hong Kong 預設是未開通的，要去 AWS Console 開通一下。

另外，在企業內經常使用的 Proxy，使用 Set-AWSProxy 來進行設定：

PS C:\>Set-AWSProxy -Hostname https://proxy.testserver.com -Port 80 -BypassList 169.254.169.250;169.254.169.251;169.254.169.254

要重新設定新的憑證也是沒有問題，使用 Set-AWSCredential 可以新增與更新：

PS C:\>Set-AWSCredential -AccessKey AKIAIOSFODNN7EXAMPLE -SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY -StoreAs myCredentials

PS C:\>Get-AWSCredential -ListProfileDetail

ProfileName    StoreTypeName         ProfileLocation
-----------    -------------         ---------------
myCredentials  NetSDKCredentialsFile
kkbruce        SharedCredentialsFile C:\Users\BruceChen\.aws\credentials
default        SharedCredentialsFile C:\Users\BruceChen\.aws\credentials

-StoreAs 也就是未來使用在 -ProfileName 的名稱。

刪除憑證：

Remove-AWSCredentialProfile -ProfileName myCredentials

S3 cmdlet

PS C:\>Test-S3Bucket -BucketName kkbruce -ProfileName kkbruce
False

前面的儲存體 kkbruce 在測試的最後已經被刪除，透過 Profile kkbruce 去連線測試得到 False。

PS C:\>New-S3Bucket -BucketName kkbruce -ProfileName kkbruce

CreationDate         BucketName
------------         ----------
2020/1/2 上午 04:44:23 kkbruce

PS C:\>Test-S3Bucket -BucketName kkbruce -ProfileName kkbruce
True

現在，透過 New-S3Bucket cmdlet 可以來建立一個新的儲存體，建立成功之後，透過 Test-S3Bucket 測試就會得到 True。

Upload files

PS D:\Download>Write-S3Object -BucketName kkbruce -File .\demo.txt
PS D:\Download>Write-S3Object -BucketName kkbruce -File .\demo.txt -Key "demo-key.txt"
PS D:\Download>Get-S3Object -BucketName kkbruce

ETag         : "d41d8cd98f00b204e9800998ecf8427e"
BucketName   : kkbruce
Key          : demo-key.txt
LastModified : 2020/1/2 下午 01:34:28
Owner        : Amazon.S3.Model.Owner
Size         : 0
StorageClass : STANDARD

ETag         : "d41d8cd98f00b204e9800998ecf8427e"
BucketName   : kkbruce
Key          : demo.txt
LastModified : 2020/1/2 下午 01:34:03
Owner        : Amazon.S3.Model.Owner
Size         : 0
StorageClass : STANDARD


PS D:\Download>Get-S3Object -BucketName kkbruce -Key demo-key.txt

ETag         : "d41d8cd98f00b204e9800998ecf8427e"
BucketName   : kkbruce
Key          : demo-key.txt
LastModified : 2020/1/2 下午 01:34:28
Owner        : Amazon.S3.Model.Owner
Size         : 0
StorageClass : STANDARD

PS D:\Download>Get-S3Object -BucketName kkbruce -Key demo-key.txt

ETag         : "d41d8cd98f00b204e9800998ecf8427e"
BucketName   : kkbruce
Key          : demo-key.txt
LastModified : 2020/1/2 下午 01:34:28
Owner        : Amazon.S3.Model.Owner
Size         : 0
StorageClass : STANDARD

Write-S3Object 進行地端上傳至 AWS S3 動作。-Key 是指定上傳檔名。Get-S3Object 是取得 S3 物件。如果要建立目錄，只要上傳時指定好目錄階層：

PS D:\Download>Write-S3Object -BucketName kkbruce -File .\demo.txt -Key "test/demo.txt"
PS D:\Download>Get-S3Object -BucketName kkbruce

ETag         : "d41d8cd98f00b204e9800998ecf8427e"
BucketName   : kkbruce
Key          : test/demo.txt
LastModified : 2020/1/2 下午 02:11:08
Owner        : Amazon.S3.Model.Owner
Size         : 0
StorageClass : STANDARD

-Key "test/demo.txt" 就能建立 test 目錄。如果要上傳多個檔案，也很容易，只要指定 -Folder，那麼 cmdlet 就會將整個目錄下的檔案進行上傳。如果要過濾檔案，也只需要透過 -SearchPattern 來指定過濾模式。

PS D:\>Write-S3Object -BucketName kkbruce -Folder .\Downloads\ -KeyPrefix "demo/" -SearchPattern *.txt
PS D:\>Get-S3Object -BucketName kkbruce -KeyPrefix "demo"

ETag         : "d41d8cd98f00b204e9800998ecf8427e"
BucketName   : kkbruce
Key          : demo/demo.txt
LastModified : 2020/1/2 下午 02:19:51
Owner        : Amazon.S3.Model.Owner
Size         : 0
StorageClass : STANDARD

ETag         : "d41d8cd98f00b204e9800998ecf8427e"
BucketName   : kkbruce
Key          : demo/demo2.txt
LastModified : 2020/1/2 下午 02:19:51
Owner        : Amazon.S3.Model.Owner
Size         : 0
StorageClass : STANDARD

ETag         : "d41d8cd98f00b204e9800998ecf8427e"
BucketName   : kkbruce
Key          : demo/demo3.txt
LastModified : 2020/1/2 下午 02:19:51
Owner        : Amazon.S3.Model.Owner
Size         : 0
StorageClass : STANDARD

我在本機 Download 目錄準備一些檔案，並透過 -KeyPrefix "demo/" 指定目錄名稱，-SearchPattern *.txt 指定只上傳 *.txt 副檔名。

從以上測試也可以看出來，就 S3 而言其實並無目錄，只是把 prefix 當成目錄來看。通常為 Key 的字串。

Download files

要下載 S3 物件使用 Read-S3Object cmdlet。參數與 Write-S3Object 差不多。

-File 是下載單一檔案。

PS D:\Download>Read-S3Object -BucketName kkbruce -Key demo.txt -File demo.txt

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----          2020/1/2 下午 02:31              0 demo.txt

-Folder 要下載 S3 某一個目錄至本機目錄位置。

PS D:\Download>Read-S3Object -BucketName kkbruce -KeyPrefix demo -Folder D:\Downloads\demo

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----          2020/1/2 下午 02:32                demo

dir


    Directory: D:\Downloads\demo

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----          2020/1/2 下午 02:32              0 demo.txt
-a----          2020/1/2 下午 02:32              0 demo2.txt
-a----          2020/1/2 下午 02:32              0 demo3.txt

Delete files

Remove-S3Object 用來刪除 S3 物件。

PS D:\Download>Remove-S3Object -BucketName kkbruce -Key demo.txt

Confirm
Are you sure you want to perform this action?
Performing the operation "Remove-S3Object (DeleteObjects)" on target "".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): y

DeleteMarker VersionId RequestCharged
------------ --------- --------------

我們輕易的用 PowerShell 的管線(pipeline)來完成多檔案刪除。

PS D:\Download>Get-S3Object -BucketName kkbruce -KeyPrefix "demo/" | Remove-S3Object -Force

DeleteMarker DeleteMarkerVersionId Key            VersionId
------------ --------------------- ---            ---------
False                              demo/demo.txt
False                              demo/demo2.txt
False                              demo/demo3.txt

我們先列舉某個 Prefix 下的檔案，然後送到 Remove-S3Object 進行刪除。

Remove Bucket

PS D:\Download>Remove-S3Bucket -BucketName kkbruce -DeleteBucketContent

如果儲存體非為空，指定 -DeleteBucketContent 才能進行刪除。

小結

我們的目標是使用 AWS CLI 或 AWS PowerShell 來進行 AWS 的管理或操作，我們選擇一個好入門的 S3 服務來學習。AWS CLI 簡單快速又好用，但前面說過，要整合腳本就不是那麼好的選項。還好還有 AWS PowerShell 可以選用，且搭配文件服用，效果真的是不錯。如果已經對 PowerShell 有一些基礎，也是很好入手。

雲端能玩的東西真在太多了：

PS C:\>Get-AWSService | Measure-Object

可以猜猜現在 AWS 提供幾個服務。

KingKong Bruce記事

網頁