本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 sam sync 同步至 的簡介 AWS 雲端 Command AWS Serverless Application Model Line Interface (AWS SAM CLI) `sam sync`命令提供快速將本機應用程式變更同步至 的選項 AWS 雲端。開發應用程式`sam sync`時使用 來： 1. 自動偵測本機變更並將其同步至 AWS 雲端。 1. 自訂要同步到 的本機變更 AWS 雲端。 1. 在雲端中準備您的應用程式以進行測試和驗證。 使用 `sam sync`，您可以建立快速開發工作流程，以縮短將本機變更同步至雲端進行測試和驗證所需的時間。 **注意** 建議開發環境使用 `sam sync`命令。對於生產環境，我們建議使用或`sam deploy`設定*持續整合和交付 (CI/CD)* 管道。如需詳細資訊，請參閱 [使用 部署您的應用程式和資源 AWS SAM](serverless-deploying.md)。 `sam sync` 命令是 的一部分 AWS SAM Accelerate。 *AWS SAM Accelerate*提供工具，可讓您用來加速在 中開發和測試無伺服器應用程式的體驗 AWS 雲端。 **Topics** + [ ## 自動偵測本機變更並將其同步至 AWS 雲端 ](#using-sam-cli-sync-auto) + [ ## 自訂要同步到 的本機變更 AWS 雲端 ](#using-sam-cli-sync-customize) + [ ## 在雲端中準備您的應用程式以進行測試和驗證 ](#using-sam-cli-sync-test) + [ ## sam 同步命令的選項 ](#using-sam-cli-sync-options) + [ ## 疑難排解 ](#using-sam-cli-sync-troubleshooting) + [ ## 範例 ](#using-sam-cli-sync-examples) + [ ## 進一步了解 ](#using-sam-cli-sync-learn) ## 自動偵測本機變更並將其同步至 AWS 雲端 `sam sync` 使用 `--watch`選項執行 ，以開始將您的應用程式同步至 AWS 雲端。這會執行下列動作： 1. **建置您的應用程式 ** – 此程序類似於使用 `sam build`命令。 1. **部署您的應用程式** – AWS SAM CLI AWS CloudFormation 使用預設設定將您的應用程式部署到 。使用下列預設值： 1. AWS 登入資料和一般組態設定可在您的`.aws`使用者資料夾中找到。 1. 在您的應用程式`samconfig.toml`檔案中找到的應用程式部署設定。 如果找不到預設值， AWS SAM CLI會通知您並結束同步程序。 1. **注意本機變更** – AWS SAM CLI會保持執行狀態，並注意應用程式的本機變更。這是 `--watch`選項提供的內容。 此選項預設為開啟。如需預設值，請參閱您應用程式的 `samconfig.toml` 檔案。以下是範例 檔案： ``` ... [default.sync] [default.sync.parameters] watch = true ... ``` 1. **同步本機變更至 AWS 雲端**- 當您進行本機變更時， AWS 雲端 會透過可用的最快速方法 AWS SAM CLI偵測和同步這些變更至 。視變更類型而定，可能會發生下列情況： 1. 如果您更新的資源支援服務 AWS APIs， AWS SAM CLI將使用它來部署您的變更。這會導致快速同步，以更新 中的資源 AWS 雲端。 1. 如果您更新的資源不支援 AWS 服務 APIs， AWS SAM CLI將執行 CloudFormation 部署。這會在 中更新您的整個應用程式 AWS 雲端。雖然速度不那麼快，但它確實讓您無法手動啟動部署。 由於 `sam sync`命令會在 中自動更新您的應用程式 AWS 雲端，因此建議僅用於開發環境。當您執行 時`sam sync`，系統會要求您確認： ``` **The sync command should only be used against a development stack**. Confirm that you are synchronizing a development stack. Enter Y to proceed with the command, or enter N to cancel: [Y/n]: ENTER ``` ## 自訂要同步到 的本機變更 AWS 雲端 提供選項來自訂要同步到 的本機變更 AWS 雲端。這可以加快在雲端中查看本機變更以進行測試和驗證所需的時間。 例如，提供僅同步程式碼變更`--code`的選項，例如 AWS Lambda 函數程式碼。在開發期間，如果您特別專注於 Lambda 程式碼，這將使您快速變更到雲端進行測試和驗證。以下是範例： ``` $ sam sync --code --watch ``` 若要僅同步特定 Lambda 函數或 layer 的程式碼變更，請使用 `--resource-id`選項。以下是範例： ``` $ sam sync --code --resource-id HelloWorldFunction --resource-id HelloWorldLayer ``` ## 在雲端中準備您的應用程式以進行測試和驗證 `sam sync` 命令會自動尋找可用於在 中更新應用程式的最快方法 AWS 雲端。這可以加快您的開發和雲端測試工作流程。透過利用 AWS 服務 APIs，您可以快速開發、同步和測試支援的資源。如需實作範例，請參閱*完成 AWS SAM 研討會*中的[單元 6 - AWS SAM 加速](https://s12d.com/sam-ws-en-accelerate)。 ## sam 同步命令的選項 以下是您可以用來修改`sam sync`命令的一些主要選項。如需所有選項的清單，請參閱 [sam sync](sam-cli-command-reference-sam-sync.md)。 ### 執行一次性 CloudFormation 部署 使用 `--no-watch`選項來關閉自動同步。以下是範例： ``` $ sam sync --no-watch ``` AWS SAM CLI 將執行一次性 CloudFormation 部署。此命令會將 `sam build`和 `sam deploy`命令執行的動作分組在一起。 ### 略過初始 CloudFormation 部署 您可以自訂每次執行`sam sync`時是否需要 CloudFormation 部署。 + 提供 `--no-skip-deploy-sync`以在每次執行`sam sync`時要求 CloudFormation 部署。這可確保您的本機基礎設施同步到 CloudFormation，防止偏離。使用此選項可為您的開發和測試工作流程增加額外的時間。 + 提供 `--skip-deploy-sync` 讓 CloudFormation 部署成為選用。 AWS SAM CLI 會將您的本機 AWS SAM 範本與部署的 CloudFormation 範本進行比較，如果未偵測到變更， 會略過初始 CloudFormation 部署。略過 CloudFormation 部署可節省您同步本機變更至 的時間 AWS 雲端。 如果未偵測到變更， AWS SAM CLI仍會在下列情況下執行 CloudFormation 部署： + 如果自上次 CloudFormation 部署以來已超過 7 天。 + 如果偵測到大量的 Lambda 函數程式碼變更，讓 CloudFormation 部署成為更新應用程式的最快方法。 以下是範例： ``` $ sam sync --skip-deploy-sync ``` ### 從巢狀堆疊同步資源 **從巢狀堆疊同步資源** 1. 使用 提供根堆疊`--stack-name`。 1. 使用下列格式識別巢狀堆疊中的資源：`nestedStackId/resourceId`。 1. 使用 在巢狀堆疊中提供資源`--resource-id`。 以下是範例： ``` $ sam sync --code --stack-name sam-app --resource-id myNestedStack/HelloWorldFunction ``` 如需建立巢狀應用程式的詳細資訊，請參閱 [在 中使用巢狀應用程式重複使用程式碼和資源 AWS SAM](serverless-sam-template-nested-applications.md)。 ### 指定要更新的特定 CloudFormation 堆疊 若要指定要更新的特定 CloudFormation 堆疊，請提供 `--stack-name`選項。以下是範例： ``` $ sam sync --stack-name dev-sam-app ``` ### 在來源資料夾中建置您的專案，以加快建置時間 對於支援的執行時間和建置方法，您可以使用 `--build-in-source`選項直接在來源資料夾中建置專案。根據預設， 會在暫存目錄中 AWS SAM CLI建置，這涉及透過原始碼和專案檔案進行複製。使用 `--build-in-source`時， AWS SAM 會直接在您的來源資料夾中CLI建置，而不需要將檔案複製到暫時目錄，即可加速建置程序。 如需支援的執行時間和建置方法清單，請參閱 ` --build-in-source`。 ### 指定不會啟動同步的檔案和資料夾 使用 `--watch-exclude`選項指定更新時不會啟動同步的任何檔案或資料夾。如需有關此選項的詳細資訊，請參閱 `--watch-exclude`。 以下是排除與`HelloWorldFunction`函數相關聯`package-lock.json`檔案的範例： ``` $ sam sync --watch --watch-exclude HelloWorldFunction=package-lock.json ``` 執行此命令時， AWS SAM CLI會啟動同步程序。這包含下列項目： + 執行 `sam build` 來建置您的 函數，並準備您的應用程式以進行部署。 + 執行 `sam deploy`以部署您的應用程式。 + 請注意應用程式的變更。 當我們修改`package-lock.json`檔案時， AWS SAM CLI 不會啟動同步。更新另一個檔案時， AWS SAM CLI會啟動同步，其中包含 `package-lock.json` 檔案。 以下是指定子堆疊 Lambda 函數的範例： ``` $ sam sync --watch --watch-exclude ChildStackA/MyFunction=database.sqlite3 ``` ## 疑難排解 若要對 進行故障診斷 AWS SAM CLI，請參閱 [AWS SAM CLI 故障診斷](sam-cli-troubleshooting.md)。 ## 範例 ### 使用 sam 同步更新 Hello World 應用程式 在此範例中，我們從初始化範例 Hello World 應用程式開始。若要進一步了解此應用程式，請參閱 [教學課程：使用 部署 Hello World 應用程式 AWS SAM](serverless-getting-started-hello-world.md)。 執行 會`sam sync`開始建置和部署程序。 ``` $ sam sync The SAM CLI will use the AWS Lambda, Amazon API Gateway, and AWS StepFunctions APIs to upload your code without performing a CloudFormation deployment. This will cause drift in your CloudFormation stack. **The sync command should only be used against a development stack**. Confirm that you are synchronizing a development stack. Enter Y to proceed with the command, or enter N to cancel: [Y/n]: Queued infra sync. Waiting for in progress code syncs to complete... Starting infra sync. Manifest file is changed (new hash: 3298f13049d19cffaa37ca931dd4d421) or dependency folder (.aws-sam/deps/0663e6fe-a888-4efb-b908-e2344261e9c7) is missing for (HelloWorldFunction), downloading dependencies and copying/building source Building codeuri: /Users/.../Demo/sync/sam-app/hello_world runtime: python3.9 metadata: {} architecture: x86_64 functions: HelloWorldFunction Running PythonPipBuilder:CleanUp Running PythonPipBuilder:ResolveDependencies Running PythonPipBuilder:CopySource Build Succeeded Successfully packaged artifacts and wrote output template to file /var/folders/45/5ct135bx3fn2551_ptl5g6_80000gr/T/tmpx_5t4u3f. Execute the following command to deploy the packaged template sam deploy --template-file /var/folders/45/5ct135bx3fn2551_ptl5g6_80000gr/T/tmpx_5t4u3f --stack-name Deploying with following values =============================== Stack name : sam-app Region : us-west-2 Disable rollback : False Deployment s3 bucket : aws-sam-cli-managed-default-samclisam-s3-demo-bucket-1a4x26zbcdkqr Capabilities : ["CAPABILITY_NAMED_IAM", "CAPABILITY_AUTO_EXPAND"] Parameter overrides : {} Signing Profiles : null Initiating deployment ===================== 2023-03-17 11:17:19 - Waiting for stack create/update to complete CloudFormation events from stack operations (refresh every 0.5 seconds) --------------------------------------------------------------------------------------------------------------------------------------------- ResourceStatus ResourceType LogicalResourceId ResourceStatusReason --------------------------------------------------------------------------------------------------------------------------------------------- CREATE_IN_PROGRESS AWS::CloudFormation::Stack sam-app Transformation succeeded CREATE_IN_PROGRESS AWS::CloudFormation::Stack AwsSamAutoDependencyLayerNestedSt - ack CREATE_IN_PROGRESS AWS::IAM::Role HelloWorldFunctionRole - CREATE_IN_PROGRESS AWS::IAM::Role HelloWorldFunctionRole Resource creation Initiated CREATE_IN_PROGRESS AWS::CloudFormation::Stack AwsSamAutoDependencyLayerNestedSt Resource creation Initiated ack CREATE_COMPLETE AWS::IAM::Role HelloWorldFunctionRole - CREATE_COMPLETE AWS::CloudFormation::Stack AwsSamAutoDependencyLayerNestedSt - ack CREATE_IN_PROGRESS AWS::Lambda::Function HelloWorldFunction - CREATE_IN_PROGRESS AWS::Lambda::Function HelloWorldFunction Resource creation Initiated CREATE_COMPLETE AWS::Lambda::Function HelloWorldFunction - CREATE_IN_PROGRESS AWS::ApiGateway::RestApi ServerlessRestApi - CREATE_IN_PROGRESS AWS::ApiGateway::RestApi ServerlessRestApi Resource creation Initiated CREATE_COMPLETE AWS::ApiGateway::RestApi ServerlessRestApi - CREATE_IN_PROGRESS AWS::ApiGateway::Deployment ServerlessRestApiDeployment47fc2d - 5f9d CREATE_IN_PROGRESS AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermi - ssionProd CREATE_IN_PROGRESS AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermi Resource creation Initiated ssionProd CREATE_IN_PROGRESS AWS::ApiGateway::Deployment ServerlessRestApiDeployment47fc2d Resource creation Initiated 5f9d CREATE_COMPLETE AWS::ApiGateway::Deployment ServerlessRestApiDeployment47fc2d - 5f9d CREATE_IN_PROGRESS AWS::ApiGateway::Stage ServerlessRestApiProdStage - CREATE_IN_PROGRESS AWS::ApiGateway::Stage ServerlessRestApiProdStage Resource creation Initiated CREATE_COMPLETE AWS::ApiGateway::Stage ServerlessRestApiProdStage - CREATE_COMPLETE AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermi - ssionProd CREATE_COMPLETE AWS::CloudFormation::Stack sam-app - --------------------------------------------------------------------------------------------------------------------------------------------- CloudFormation outputs from deployed stack ---------------------------------------------------------------------------------------------------------------------------------------------- Outputs ---------------------------------------------------------------------------------------------------------------------------------------------- Key HelloWorldFunctionIamRole Description Implicit IAM Role created for Hello World function Value arn:aws:iam::012345678910:role/sam-app-HelloWorldFunctionRole-BUFVMO2PJIYF Key HelloWorldApi Description API Gateway endpoint URL for Prod stage for Hello World function Value https://pcrx5gdaof.execute-api.us-west-2.amazonaws.com/Prod/hello/ Key HelloWorldFunction Description Hello World Lambda Function ARN Value arn:aws:lambda:us-west-2:012345678910:function:sam-app-HelloWorldFunction-2PlN6TPTQoco ---------------------------------------------------------------------------------------------------------------------------------------------- Stack creation succeeded. Sync infra completed. Infra sync completed. CodeTrigger not created as CodeUri or DefinitionUri is missing for ServerlessRestApi. ``` 部署完成後，我們會修改`HelloWorldFunction`程式碼。 AWS SAM CLI 會偵測此變更，並將我們的應用程式同步至 AWS 雲端。由於 AWS Lambda 支援 AWS 服務 APIs，因此會執行快速同步。 ``` Syncing Lambda Function HelloWorldFunction... Manifest is not changed for (HelloWorldFunction), running incremental build Building codeuri: /Users/.../Demo/sync/sam-app/hello_world runtime: python3.9 metadata: {} architecture: x86_64 functions: HelloWorldFunction Running PythonPipBuilder:CopySource Finished syncing Lambda Function HelloWorldFunction. ``` 接著，我們在應用程式的 AWS SAM 範本中修改 API 端點。我們將 `/hello`變更為 `/helloworld`。 ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 ... Resources: HelloWorldFunction: ... Properties: ... Events: HelloWorld: Type: Api Properties: Path: /helloworld Method: get ``` 由於 Amazon API Gateway 資源不支援 AWS 服務 API，因此 AWS SAM CLI會自動執行 CloudFormation 部署。以下是輸出範例： ``` Queued infra sync. Waiting for in progress code syncs to complete... Starting infra sync. Manifest is not changed for (HelloWorldFunction), running incremental build Building codeuri: /Users/.../Demo/sync/sam-app/hello_world runtime: python3.9 metadata: {} architecture: x86_64 functions: HelloWorldFunction Running PythonPipBuilder:CopySource Build Succeeded Successfully packaged artifacts and wrote output template to file /var/folders/45/5ct135bx3fn2551_ptl5g6_80000gr/T/tmpuabo0jb9. Execute the following command to deploy the packaged template sam deploy --template-file /var/folders/45/5ct135bx3fn2551_ptl5g6_80000gr/T/tmpuabo0jb9 --stack-name Deploying with following values =============================== Stack name : sam-app Region : us-west-2 Disable rollback : False Deployment s3 bucket : aws-sam-cli-managed-default-samclisam-s3-demo-bucket-1a4x26zbcdkqr Capabilities : ["CAPABILITY_NAMED_IAM", "CAPABILITY_AUTO_EXPAND"] Parameter overrides : {} Signing Profiles : null Initiating deployment ===================== 2023-03-17 14:41:18 - Waiting for stack create/update to complete CloudFormation events from stack operations (refresh every 0.5 seconds) --------------------------------------------------------------------------------------------------------------------------------------------- ResourceStatus ResourceType LogicalResourceId ResourceStatusReason --------------------------------------------------------------------------------------------------------------------------------------------- UPDATE_IN_PROGRESS AWS::CloudFormation::Stack sam-app Transformation succeeded UPDATE_IN_PROGRESS AWS::CloudFormation::Stack AwsSamAutoDependencyLayerNestedSt - ack UPDATE_COMPLETE AWS::CloudFormation::Stack AwsSamAutoDependencyLayerNestedSt - ack UPDATE_IN_PROGRESS AWS::ApiGateway::RestApi ServerlessRestApi - UPDATE_COMPLETE AWS::ApiGateway::RestApi ServerlessRestApi - CREATE_IN_PROGRESS AWS::ApiGateway::Deployment ServerlessRestApiDeployment8cf30e - d3cd UPDATE_IN_PROGRESS AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermi Requested update requires the ssionProd creation of a new physical resource; hence creating one. UPDATE_IN_PROGRESS AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermi Resource creation Initiated ssionProd CREATE_IN_PROGRESS AWS::ApiGateway::Deployment ServerlessRestApiDeployment8cf30e Resource creation Initiated d3cd CREATE_COMPLETE AWS::ApiGateway::Deployment ServerlessRestApiDeployment8cf30e - d3cd UPDATE_IN_PROGRESS AWS::ApiGateway::Stage ServerlessRestApiProdStage - UPDATE_COMPLETE AWS::ApiGateway::Stage ServerlessRestApiProdStage - UPDATE_COMPLETE AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermi - ssionProd UPDATE_COMPLETE_CLEANUP_IN_PROGRE AWS::CloudFormation::Stack sam-app - SS DELETE_IN_PROGRESS AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermi - ssionProd DELETE_IN_PROGRESS AWS::ApiGateway::Deployment ServerlessRestApiDeployment47fc2d - 5f9d DELETE_COMPLETE AWS::ApiGateway::Deployment ServerlessRestApiDeployment47fc2d - 5f9d UPDATE_COMPLETE AWS::CloudFormation::Stack AwsSamAutoDependencyLayerNestedSt - ack DELETE_COMPLETE AWS::Lambda::Permission HelloWorldFunctionHelloWorldPermi - ssionProd UPDATE_COMPLETE AWS::CloudFormation::Stack sam-app - --------------------------------------------------------------------------------------------------------------------------------------------- CloudFormation outputs from deployed stack ---------------------------------------------------------------------------------------------------------------------------------------------- Outputs ---------------------------------------------------------------------------------------------------------------------------------------------- Key HelloWorldFunctionIamRole Description Implicit IAM Role created for Hello World function Value arn:aws:iam::012345678910:role/sam-app-HelloWorldFunctionRole-BUFVMO2PJIYF Key HelloWorldApi Description API Gateway endpoint URL for Prod stage for Hello World function Value https://pcrx5gdaof.execute-api.us-west-2.amazonaws.com/Prod/hello/ Key HelloWorldFunction Description Hello World Lambda Function ARN Value arn:aws:lambda:us-west-2:012345678910:function:sam-app-HelloWorldFunction-2PlN6TPTQoco ---------------------------------------------------------------------------------------------------------------------------------------------- Stack update succeeded. Sync infra completed. Infra sync completed. ``` ## 進一步了解 如需所有`sam sync`選項的說明，請參閱 [sam sync](sam-cli-command-reference-sam-sync.md)。