View a markdown version of this page

sam deploy - AWS Serverless Application Model

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

sam deploy

此頁面提供 AWS Serverless Application Model 命令列界面 (AWS SAM CLI) sam deploy命令的參考資訊。

sam deploy 命令 AWS 雲端 會使用 將應用程式部署到 AWS CloudFormation。

重要

不要在不受信任的程式碼sam deploy上執行。命令使用您的 AWS 登入資料來建立範本定義的資源,包括 IAM 角色和政策,並上傳範本參考的本機檔案。它也會依寫入方式套用專案組態檔案中的選項。在部署您未撰寫的專案之前,請先檢閱範本和組態檔案。

使用情況

$ <environment variables> sam deploy <options>

環境變數

SAM_CLI_POLL_DELAY

設定 Shell 中值為 秒SAM_CLI_POLL_DELAY的環境變數,以設定 AWS SAM CLI 檢查 CloudFormation 堆疊狀態的頻率,這在查看調節時非常有用 CloudFormation。此 env 變數用於輪詢在執行 時進行的 describe_stack API 呼叫sam deploy。

以下是此變數的範例:

$ SAM_CLI_POLL_DELAY=5 sam deploy

選項

--capabilities LIST

您必須指定才能允許 CloudFormation 建立特定堆疊的功能清單。某些堆疊範本可能包含會影響 許可的資源, AWS 帳戶例如,透過建立新的 AWS Identity and Access Management (IAM) 使用者。對於這些堆疊,您必須指定此選項來明確認可其功能。唯一有效的值為 CAPABILITY_IAM 和 CAPABILITY_NAMED_IAM。如果您有 IAM 資源,則可以指定任一功能。如果您有具有自訂名稱的 IAM 資源,則必須指定 CAPABILITY_NAMED_IAM。如果您未指定此選項,則操作會傳回InsufficientCapabilities錯誤。

當您部署包含巢狀應用程式的應用程式時,您必須使用 CAPABILITY_AUTO_EXPAND來確認應用程式包含巢狀應用程式。如需詳細資訊,請參閱部署巢狀應用程式。

--config-env TEXT

在要使用的組態檔案中指定預設參數值的環境名稱。預設值為 default。如需關於組態檔案的詳細資訊,請參閱 AWS SAM CLI 組態檔案。

--config-file PATH

組態檔案的路徑和檔案名稱,其中包含要使用的預設參數值。預設值位於專案目錄的根samconfig.toml目錄中。如需關於組態檔案的詳細資訊,請參閱 AWS SAM CLI 組態檔案。

--confirm-changeset | --no-confirm-changeset

提示 AWS SAM CLI確認 是否部署計算的變更集。

--debug

開啟偵錯記錄以列印 產生的偵錯訊息 AWS SAM CLI,並顯示時間戳記。

--disable-rollback | --no-disable-rollback

指定在部署期間發生錯誤時是否要轉返 CloudFormation 堆疊。根據預設,如果在部署期間發生錯誤,您的 CloudFormation 堆疊會回復到最後的穩定狀態。如果您指定 --disable-rollback並在部署期間發生錯誤,則在發生錯誤之前建立或更新的資源不會復原。

--express | --no-express

指定是否使用 CloudFormation 快速模式。作用中時,一旦套用資源組態,堆疊操作就會完成。資源會在背景繼續準備就緒。部署時間最多可縮短 4 倍。

當您也指定 時, CloudFormation AWS SAM CLI會將轉返行為傳遞至 DeploymentConfig 參數--disable-rollback。

預設值為 --no-express。

--fail-on-empty-changeset | --no-fail-on-empty-changeset

指定如果堆疊沒有變更,是否傳回非零結束碼。預設行為是傳回非零結束碼。

--force-upload

指定此選項以上傳成品,即使它們符合 Amazon S3 儲存貯體中的現有成品。比對成品會遭到覆寫。

--guided, -g

指定此選項,讓 AWS SAM CLI使用提示來引導您完成部署。

--help

顯示此訊息並結束。

--image-repositories TEXT

函數映射至其 Amazon ECR 儲存庫 URI。依邏輯 ID 參考函數。以下是範例:

$ sam deploy --image-repositories Function1=123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo

您可以在單一命令中多次指定此選項。

--image-repository TEXT

此命令上傳函數映像的 Amazon ECR 儲存庫名稱。使用 Image套件類型宣告的函數需要此選項。

--kms-key-id TEXT

用來加密 Amazon S3 儲存貯體中靜態成品的 AWS Key Management Service (AWS KMS) 金鑰 ID。如果您未指定此選項,則 AWS SAM 會使用 Amazon S3-managed加密金鑰。

對於AWS::Serverless::WebFunction上傳到您使用 指定的儲存貯體--s3-bucket,金鑰必須是客戶受管金鑰,其金鑰政策允許 lambda.amazonaws.com呼叫 kms:Decrypt。

--metadata

要連接到範本中參考之所有成品的中繼資料映射。

--no-execute-changeset

指出是否套用變更集。如果您想要在套用變更集之前檢視堆疊變更,請指定此選項。此命令會 CloudFormation 建立變更集,然後結束而不套用變更集。若要套用變更集,請執行相同的命令,而不使用此選項。

--no-progressbar

將成品上傳至 Amazon S3 時,請勿顯示進度列。

--notification-arns LIST

與堆疊建立 CloudFormation 關聯的 Amazon Simple Notification Service (Amazon SNS) 主題 ARNs 清單。

--on-failure [ROLLBACK | DELETE | DO_NOTHING]

指定堆疊無法建立時要採取的動作。

下列選項可供使用:

  • ROLLBACK – 將堆疊復原至先前的已知良好狀態。

  • DELETE – 如果存在堆疊,則將堆疊復原至先前的已知良好狀態。否則, 會刪除堆疊。

  • DO_NOTHING – 既不會轉返,也不會刪除堆疊。效果與 的效果相同--disable-rollback。

預設行為是 ROLLBACK。

注意

您可以指定 --disable-rollback選項或 --on-failure選項,但不能同時指定兩者。

--output [ text | json ]

命令輸出的格式:

  • text – 列印一般、人類可讀取的輸出。這是預設值。

  • json – 列印結構化、機器可讀取的輸出。當您想要以程式設計方式使用輸出時,例如在 CI/CD 管道、IDE 延伸模組和 AI 輔助工具中,請使用此格式。

部署會在一段時間內執行。當您指定 時--output json, AWS SAM CLI會隨著部署進度,列印每行一個 JSON 物件的串流。每個物件都包含 type 欄位,可識別其包含的資訊類型,例如變更集、部署事件、堆疊輸出和最終結果。在失敗時,最後一個物件包含一個error物件,描述出了什麼問題。

注意

--output json 選項與需要互動式提示的選項不相容,例如 --guided和 --confirm-changeset。

--parameter-overrides LIST

包含 CloudFormation 參數的字串會覆寫編碼為鍵值對的字串。每個覆寫都使用格式 ParameterKey=name,ParameterValue=value。多個覆寫會以空格分隔。以下是兩個範例:

$ sam deploy --parameter-overrides ParameterKey=value1,ParameterValue=value2
$ sam deploy --parameter-overrides ParameterKey=value1,ParameterValue=value2 ParameterKey=hello,ParameterValue=world ParameterKey=apple,ParameterValue=banana
--profile TEXT

從您的登入資料檔案中取得 AWS 登入資料的特定設定檔。

--region TEXT

AWS 區域 要部署到的 。例如 us-east-1。

--resolve-image-repos

自動建立 Amazon ECR 儲存庫,以用於封裝和部署非引導式部署。此選項僅適用於具有PackageType: Image指定 的函數和層。如果您指定 --guided選項,則 AWS SAM CLI會忽略 --resolve-image-repos。

注意

如果 使用此選項 AWS SAM 自動為函數或層建立任何 Amazon ECR 儲存庫,而您稍後從 AWS SAM 範本中刪除這些函數或層,則會自動刪除對應的 Amazon ECR 儲存庫。

--resolve-s3

自動建立 Amazon S3 儲存貯體,用於封裝和部署非引導式部署。如果您指定 --guided選項,則 AWS SAM CLI 會忽略 --resolve-s3。如果您同時指定 --s3-bucket和 --resolve-s3選項,則會發生錯誤。

使用此選項或 時--guided, 的程式碼AWS::Serverless::WebFunction會上傳至屬於堆疊的程式碼儲存貯體,而非受管儲存貯體。如需詳細資訊,請參閱建置和部署 Lambda Web 函數。

--role-arn TEXT

套用變更集時 CloudFormation 擔任之 IAM 角色的 Amazon Resource Name (ARN)。

--s3-bucket TEXT

此命令上傳 CloudFormation 範本的 Amazon S3 儲存貯體名稱。如果您的範本大於 51,200 個位元組,則需要 --s3-bucket選項或 --resolve-s3選項。如果您同時指定 --s3-bucket和 --resolve-s3選項,則會發生錯誤。

的程式碼AWS::Serverless::WebFunction也會上傳至此儲存貯體,該儲存貯體必須已啟用版本控制,並允許 Lambda 讀取程式碼。如需詳細資訊,請參閱建置和部署 Lambda Web 函數。

--s3-prefix TEXT

新增至上傳到 Amazon S3 儲存貯體之成品名稱的字首。字首名稱是 Amazon S3 儲存貯體的路徑名稱 (資料夾名稱)。

--save-params

將您在命令列提供的參數儲存至 AWS SAM 組態檔案。

--signing-profiles LIST

用來簽署部署套件的簽署設定檔清單。此選項會取得索引鍵/值對的清單,其中索引鍵是要簽署的函數或 layer 的名稱,而值是簽署描述檔,選用的描述檔擁有者以 分隔:。例如 FunctionNameToSign=SigningProfileName1 LayerNameToSign=SigningProfileName2:SigningProfileOwner。

--stack-name TEXT

(必要) 您要部署的 CloudFormation 堆疊名稱。如果您指定現有的堆疊,則命令會更新堆疊。如果您指定新的堆疊,則命令會建立它。

--tags LIST

要與建立或更新的堆疊建立關聯的標籤清單。 CloudFormation 也會將這些標籤傳播到堆疊中支援該標籤的資源。

--template-file, --template, -t PATH

範本 AWS SAM 所在的路徑和檔案名稱。

注意

如果您指定此選項,則 AWS SAM 只會部署範本及其指向的本機資源。

--use-json

CloudFormation 範本的輸出 JSON。預設輸出為 YAML。

範例

如需使用 sam deploy 子命令的詳細範例和深入演練,請參閱 使用 部署簡介 AWS SAM。