本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 PowerShell 建置 Lambda 函數 以下各節說明以 PowerShell 撰寫 Lambda 函數程式碼時，如何套用常見的程式設計模式與核心概念。 Lambda 提供下列適用於 PowerShell 的範例應用程式： + [blank-powershell](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-powershell) – PowerShell 函數，顯示記錄、環境變數和 AWS SDK 的使用。 開始之前，您必須先設定 PowerShell 開發環境。如需如何執行此動作的詳細資訊，請參閱[設定 PowerShell 開發環境](powershell-devenv.md)。 若要了解如何使用 AWSLambdaPSCore 模組從 範本下載範例 PowerShell 專案、建立 PowerShell 部署套件，以及將 PowerShell 函數部署至 AWS 雲端，請參閱 [使用 .zip 封存檔部署 PowerShell Lambda 函數](powershell-package.md)。 Lambda 提供適用於 .NET 語言的以下執行期： | Name | 識別符 | 作業系統 | 取代日期 | 封鎖函數建立 | 封鎖函數更新 | | --- | --- | --- | --- | --- | --- | | .NET 10 | `dotnet10` | Amazon Linux 2023 | 2028 年 11 月 14 日 | 2028 年 12 月 14 日 | 2029 年 1 月 15 日 | | .NET 9 （僅限容器） | `dotnet9` | Amazon Linux 2023 | 2026 年 11 月 10 日 | 未排程 | 未排程 | | .NET 8 | `dotnet8` | Amazon Linux 2023 | 2026 年 11 月 10 日 | 2026 年 12 月 10 日 | 2027 年 1 月 11 日 | **Topics** + [設定 PowerShell 開發環境](powershell-devenv.md) + [使用 .zip 封存檔部署 PowerShell Lambda 函數](powershell-package.md) + [定義以 PowerShell 編寫的 Lambda 函數處理常式](powershell-handler.md) + [使用 Lambda 內容物件擷取 PowerShell 函數資訊](powershell-context.md) + [記錄和監控 Powershell Lambda 函數](powershell-logging.md) # 設定 PowerShell 開發環境 Lambda 為 PowerShell 執行時間提供一組工具和程式庫。如需安裝指示，請參閱 [Lambda Tools for PowerShell](https://github.com/aws/aws-lambda-dotnet/tree/master/PowerShell) (在 GitHub 上)。 AWSLambdaPSCore 模組包括以下 cmdlet，以協助編寫和發佈 PowerShell Lambda 函數。 + **Get-AWSPowerShellLambdaTemplate** - 傳回入門範本的清單。 + **New-AWSPowerShellLambda** - 根據範本建立初步的 PowerShell 指令碼。 + **Publish-AWSPowerShellLambda** - 向 Lambda 發佈特定的 PowerShell 指令碼。 + **New-AWSPowerShellLambdaPackage** - 建立 Lambda 部署套件，您可以將其用於 CI/CD 系統進行部署。 # 使用 .zip 封存檔部署 PowerShell Lambda 函數 PowerShell 執行時間的部署套件包含 PowerShell 指令碼、PowerShell 指令碼所需要的 PowerShell 模組，以及代管 PowerShell Core 所需的組件。 ## 建立 Lambda 函數 若要開始使用 Lambda 來編寫和叫用 PowerShell 指令碼，您可以使用 `New-AWSPowerShellLambda` cmdlet 根據範本建立入門指令碼。您可以使用 `Publish-AWSPowerShellLambda` cmdlet 將指令碼部署至 Lambda。然後，您可以透過命令列或 Lambda 主控台測試指令碼。 若要建立新的 PowerShell 指令碼、將它上傳並對其進行測試，請執行以下操作： 1. 若要檢視可用範本的清單，請執行以下命令： ``` PS C:\> Get-AWSPowerShellLambdaTemplate Template Description -------- ----------- Basic Bare bones script CodeCommitTrigger Script to process AWS CodeCommit Triggers ... ``` 1. 若要根據 `Basic` 範本建立範例指令碼，請執行下列命令： ``` New-AWSPowerShellLambda -ScriptName MyFirstPSScript -Template Basic ``` 一個名為 `MyFirstPSScript.ps1` 的新檔案已建立在目前目錄下的新子目錄中。該目錄的名稱依據 `-ScriptName` 參數而定。您可以使用 `-Directory` 參數來選擇另一個目錄。 您可以看到新的檔案包含下列內容： ``` # PowerShell script file to run as a Lambda function # # When executing in Lambda the following variables are predefined. # $LambdaInput - A PSObject that contains the Lambda function input data. # $LambdaContext - An Amazon.Lambda.Core.ILambdaContext object that contains information about the currently running Lambda environment. # # The last item in the PowerShell pipeline is returned as the result of the Lambda function. # # To include PowerShell modules with your Lambda function, like the AWSPowerShell.NetCore module, add a "#Requires" statement # indicating the module and version. #Requires -Modules @{ModuleName='AWSPowerShell.NetCore';ModuleVersion='3.3.618.0'} # Uncomment to send the input to CloudWatch Logs # Write-Host (ConvertTo-Json -InputObject $LambdaInput -Compress -Depth 5) ``` 1. 若要了解日誌訊息如何從 PowerShell 指令碼傳送至 Amazon CloudWatch Logs，請取消範例指令碼中 `Write-Host` 一行的註解。 若要示範如何從您的 Lambda 函數傳回資料，請在指令碼的結尾處以 `$PSVersionTable` 新增一行。如此會將 `$PSVersionTable` 新增至 PowerShell 管道。在 PowerShell 指令碼完成之後，PowerShell 管道中的最後一個物件即為 Lambda 函數的傳回資料。`$PSVersionTable` 是 PowerShell 全域變數，它也提供有關執行環境的資訊。 完成這些變更之後，最後兩行的範例指令碼應類似： ``` Write-Host (ConvertTo-Json -InputObject $LambdaInput -Compress -Depth 5) $PSVersionTable ``` 1. 在您編輯 `MyFirstPSScript.ps1` 檔案之後，請將目錄變更為指令碼的位置。然後執行下列命令，將指令碼發佈至 Lambda︰ ``` Publish-AWSPowerShellLambda -ScriptPath .\MyFirstPSScript.ps1 -Name MyFirstPSScript -Region us-east-2 ``` 請注意，`-Name` 參數指定 Lambda 函數名稱，此名稱會出現在 Lambda 主控台。您可以使用此函式來手動叫用您的指令碼。 1. 使用 AWS Command Line Interface (AWS CLI) `invoke` 命令來叫用函數。 ``` > aws lambda invoke --function-name MyFirstPSScript out ``` # 定義以 PowerShell 編寫的 Lambda 函數處理常式 當 Lambda 函數被叫用時，Lambda 處理常式會叫用 PowerShell 指令碼。 當 PowerShell 指令碼被叫用時，會預先定義以下變數： + *\$1LambdaInput* - 包含處理常式之輸入的 PSObject。此輸入可以是事件資料 (由事件來源發佈) 或您提供的自訂輸入，例如字串或任何自訂資料物件。 + *\$1LambdaContext* - Amazon.Lambda.Core.ILambdaContext 物件，您可以用它來存取有關目前叫用的資訊，例如，目前函數的名稱、記憶體限制，剩餘的執行時間和記錄。 例如，考量以下 PowerShell 範例程式碼。 ``` #Requires -Modules @{ModuleName='AWSPowerShell.NetCore';ModuleVersion='3.3.618.0'} Write-Host 'Function Name:' $LambdaContext.FunctionName ``` 此指令碼會傳回從 \$1LambdaContext 變數取得的 FunctionName 屬性。 **注意** 您必須在 PowerShell 指令碼中使用 `#Requires` 陳述式，指示指令碼所要依據的模組。此陳述式執行兩個重要任務。1) 它會與其他開發人員進行通訊以決定指令碼要使用哪個模組。2) 它定義 AWS PowerShell 工具在部署過程中，封裝指令碼時所需要的相依模組。如需有關 PowerShell 中的 `#Requires` 陳述式的詳細資訊，請參閱[關於需求](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_requires?view=powershell-6)。如需 PowerShell 部署套件的詳細資訊，請參閱 [使用 .zip 封存檔部署 PowerShell Lambda 函數](powershell-package.md)。 但您的 PowerShell Lambda 函數使用 AWS PowerShell cmdlet 時，請務必設定 `#Requires` 陳述式，它參考支援 PowerShell Core 的 `AWSPowerShell.NetCore` 模組，而非參考僅支援 Windows PowerShell 的 `AWSPowerShell` 模組。此外，請務必使用版本 3.3.270.0 或更新版本的 `AWSPowerShell.NetCore`，它可最佳化 cmdlet 匯入程序。如果您使用舊版本，將面臨較長的冷啟動時間。如需詳細資訊，請參閱 [AWS Tools for PowerShell](https://aws.amazon.com/powershell/?track=sdk)。 ## 傳回資料 有些 Lambda 叫用旨在將資料傳回至呼叫者。例如，如果叫用是為了回應來自 API Gateway 的 Web 請求，則我們的 Lambda 函數必須傳回回應。對於 PowerShell Lambda 而言，新增至 PowerShell 管道的最後一個物件是來自 Lambda 叫用的傳回資料。如果該物件為字串，將以其原樣傳回。否則，會使用 `ConvertTo-Json` cmdlet 將該物件轉換為 JSON。 例如，請考量以下 PowerShell 陳述式，它將 `$PSVersionTable` 新增至 PowerShell 管道： ``` $PSVersionTable ``` 在 PowerShell 指令碼完成之後，PowerShell 管道中的最後一個物件即為 Lambda 函數的傳回資料。`$PSVersionTable` 是 PowerShell 全域變數，它也提供有關執行環境的資訊。 # 使用 Lambda 內容物件擷取 PowerShell 函數資訊 當 Lambda 執行您的函數時，它會傳遞內容資訊，方法是讓 `$LambdaContext` 變數可用於[處理常式](powershell-handler.md)。此變數提供的方法和各項屬性包含了有關叫用、函式以及執行環境的資訊。 **內容屬性** + `FunctionName` – Lambda 函數的名稱。 + `FunctionVersion` – 函數的[版本](configuration-versions.md)。 + `InvokedFunctionArn` - 用於調用此函數的 Amazon Resource Name (ARN)。指出調用者是否指定版本號或別名。 + `MemoryLimitInMB` - 分配給函數的記憶體數量。 + `AwsRequestId` - 調用請求的識別符。 + `LogGroupName` - 函數的日誌群組。 + `LogStreamName` - 函數執行個體的記錄串流。 + `RemainingTime` - 執行逾時前剩餘的毫秒數。 + `Identity` - (行動應用程式) 已授權請求的 Amazon Cognito 身分的相關資訊。 + `ClientContext` - (行動應用程式) 用戶端應用程式提供給 Lambda 的用戶端內容。 + `Logger` - 函數的 [Logger 物件](powershell-logging.md)。 下列 PowerShell 程式碼片段顯示可列印一些內容資訊的簡易處理函式。 ``` #Requires -Modules @{ModuleName='AWSPowerShell.NetCore';ModuleVersion='3.3.618.0'} Write-Host 'Function name:' $LambdaContext.FunctionName Write-Host 'Remaining milliseconds:' $LambdaContext.RemainingTime.TotalMilliseconds Write-Host 'Log group name:' $LambdaContext.LogGroupName Write-Host 'Log stream name:' $LambdaContext.LogStreamName ``` # 記錄和監控 Powershell Lambda 函數 AWS Lambda 會自動代表您監控 Lambda 函數，並將日誌傳送至 Amazon CloudWatch。您的 Lambda 函數隨附有 CloudWatch Logs 日誌群組，且函數的每一執行個體各有一個日誌串流。Lambda 執行期環境會將每次調用的詳細資訊傳送至日誌串流，並且轉傳來自函數程式碼的日誌及其他輸出。如需詳細資訊，請參閱[將 Lambda 函式日誌傳送至 CloudWatch Logs](monitoring-cloudwatchlogs.md)。 此頁面說明如何從 Lambda 函數的程式碼產生日誌輸出，並使用 AWS Command Line Interface、Lambda 主控台或 CloudWatch 主控台存取日誌。 **Topics** + [建立傳回日誌的函數](#powershell-logging-output) + [在 Lambda 主控台檢視日誌](#powershell-logging-console) + [在 CloudWatch 主控台中檢視 記錄](#powershell-logging-cwconsole) + [使用 AWS Command Line Interface (AWS CLI) 檢視日誌](#powershell-logging-cli) + [刪除日誌](#powershell-logging-delete) ## 建立傳回日誌的函數 若要從函式程式碼輸出記錄，您可以使用 [Microsoft.PowerShell.Utility](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility) 的 cmdlet 或任何寫入 `stdout` 或 `stderr` 的記錄模組。以下範例使用 `Write-Host`。 **Example [function/Handler.ps1](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-powershell/function/Handler.ps1) - 記錄** ``` #Requires -Modules @{ModuleName='AWSPowerShell.NetCore';ModuleVersion='3.3.618.0'} Write-Host `## Environment variables Write-Host AWS_LAMBDA_FUNCTION_VERSION=$Env:AWS_LAMBDA_FUNCTION_VERSION Write-Host AWS_LAMBDA_LOG_GROUP_NAME=$Env:AWS_LAMBDA_LOG_GROUP_NAME Write-Host AWS_LAMBDA_LOG_STREAM_NAME=$Env:AWS_LAMBDA_LOG_STREAM_NAME Write-Host AWS_EXECUTION_ENV=$Env:AWS_EXECUTION_ENV Write-Host AWS_LAMBDA_FUNCTION_NAME=$Env:AWS_LAMBDA_FUNCTION_NAME Write-Host PATH=$Env:PATH Write-Host `## Event Write-Host (ConvertTo-Json -InputObject $LambdaInput -Compress -Depth 3) ``` **Example 記錄格式** ``` START RequestId: 56639408-xmpl-435f-9041-ac47ae25ceed Version: $LATEST Importing module ./Modules/AWSPowerShell.NetCore/3.3.618.0/AWSPowerShell.NetCore.psd1 [Information] - ## Environment variables [Information] - AWS_LAMBDA_FUNCTION_VERSION=$LATEST [Information] - AWS_LAMBDA_LOG_GROUP_NAME=/aws/lambda/blank-powershell-function-18CIXMPLHFAJJ [Information] - AWS_LAMBDA_LOG_STREAM_NAME=2020/04/01/[$LATEST]53c5xmpl52d64ed3a744724d9c201089 [Information] - AWS_EXECUTION_ENV=AWS_Lambda_dotnet6_powershell_1.0.0 [Information] - AWS_LAMBDA_FUNCTION_NAME=blank-powershell-function-18CIXMPLHFAJJ [Information] - PATH=/var/lang/bin:/usr/local/bin:/usr/bin/:/bin:/opt/bin [Information] - ## Event [Information] - { "Records": [ { "messageId": "19dd0b57-b21e-4ac1-bd88-01bbb068cb78", "receiptHandle": "MessageReceiptHandle", "body": "Hello from SQS!", "attributes": { "ApproximateReceiveCount": "1", "SentTimestamp": "1523232000000", "SenderId": "123456789012", "ApproximateFirstReceiveTimestamp": "1523232000001" }, ... END RequestId: 56639408-xmpl-435f-9041-ac47ae25ceed REPORT RequestId: 56639408-xmpl-435f-9041-ac47ae25ceed Duration: 3906.38 ms Billed Duration: 9867 ms Memory Size: 512 MB Max Memory Used: 367 MB Init Duration: 5960.19 ms XRAY TraceId: 1-5e843da6-733cxmple7d0c3c020510040 SegmentId: 3913xmpl20999446 Sampled: true ``` .NET 執行期會記錄每次調用的 `START`、`END` 和 `REPORT` 行。報告明細行提供下列詳細資訊。 **REPORT 行資料欄位** + **RequestId** - 進行調用的唯一請求 ID。 + **持續時間** - 函數的處理常式方法處理事件所花費的時間量。 + **計費持續時間** - 調用的計費時間量。 + **記憶體大小** - 分配給函數的記憶體數量。 + **使用的記憶體上限** - 函數所使用的記憶體數量。當調用共用執行環境時，Lambda 會報告所有調用使用的記憶體上限。此行為可能會導致報告值高於預期值。 + **初始化持續時間** - 對於第一個提供的請求，這是執行期載入函數並在處理常式方法之外執行程式碼所花費的時間量。 + **XRAY TraceId** - 對於追蹤的請求，這是 [AWS X-Ray 追蹤 ID](services-xray.md)。 + **SegmentId** - 對於追蹤的請求，這是 X-Ray 區段 ID。 + **已取樣** - 對於追蹤的請求，這是取樣結果。 ## 在 Lambda 主控台檢視日誌 您可以在調用 Lambda 函數之後，使用 Lambda 主控台來檢視日誌輸出。 如果可以從內嵌**程式碼**編輯器測試您的程式碼，您會在**執行結果**中找到日誌。使用主控台測試功能以調用函數時，您會在**詳細資訊**區段找到**日誌輸出**。 ## 在 CloudWatch 主控台中檢視 記錄 您可以使用 Amazon CloudWatch 主控台來檢視所有 Lambda 函數調用的日誌。 **若要在 CloudWatch 主控台上檢視日誌** 1. 在 CloudWatch 主控台上開啟[日誌群組頁面](https://console.aws.amazon.com/cloudwatch/home?#logs:)。 1. 選擇您的函數的日誌群組 (**/aws/lambda/*your-function-name***)。 1. 選擇日誌串流 每個日誌串流都會對應至[函式的執行個體](lambda-runtime-environment.md)。當您更新 Lambda 函數，以及建立其他執行個體以處理並行調用時，就會顯示日誌串流。若要尋找特定調用的日誌，建議您使用 檢測函數 AWS X-Ray。X-Ray 會在追蹤內記錄有關請求和日誌串流的詳細資訊。 ## 使用 AWS Command Line Interface (AWS CLI) 檢視日誌 是一種 AWS CLI 開放原始碼工具，可讓您使用命令列 Shell 中的 命令與 AWS 服務互動。若要完成本節中的步驟，您必須擁有 [AWS CLI 版本 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。 您可以透過 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)，使用 `--log-type` 命令選項來擷取要調用的日誌。其回應將包含 `LogResult` 欄位，內含該次調用的 base64 編碼日誌 (最大達 4 KB)。 **Example 擷取日誌 ID** 下列範例顯示如何從名稱為 `my-function` 的函數的 `LogResult` 欄位來擷取*日誌 ID*。 ``` aws lambda invoke --function-name my-function out --log-type Tail ``` 您應該會看到下列輸出： ``` { "StatusCode": 200, "LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...", "ExecutedVersion": "$LATEST" } ``` **Example 解碼日誌** 在相同的命令提示中，使用 `base64` 公用程式來解碼日誌。下列範例顯示如何擷取 `my-function` 的 base64 編碼日誌。 ``` aws lambda invoke --function-name my-function out --log-type Tail \ --query 'LogResult' --output text --cli-binary-format raw-in-base64-out | base64 --decode ``` 如果您使用的是第 2 AWS CLI 版，則需要 **cli-binary-format**選項。若要讓此成為預設的設定，請執行 `aws configure set cli-binary-format raw-in-base64-out`。若要取得更多資訊，請參閱*《AWS Command Line Interface 使用者指南第 2 版》*中 [AWS CLI 支援的全域命令列選項](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list)。 您應該會看到下列輸出： ``` START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST "AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib", END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Duration: 79.67 ms Billed Duration: 80 ms Memory Size: 128 MB Max Memory Used: 73 MB ``` 該 `base64` 公用程式可在 Linux、macOS 和 [Ubuntu on Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10) 上使用。macOS 使用者可能需要使用 `base64 -D`。 **Example get-logs.sh 指令碼** 在相同的命令提示中，使用下列指令碼下載最後五個日誌事件。該指令碼使用 `sed` 以從輸出檔案移除引述，並休眠 15 秒以使日誌可供使用。輸出包括來自 Lambda 的回應以及來自 `get-log-events` 命令的輸出。 複製下列程式碼範例的內容，並將您的 Lambda 專案目錄儲存為 `get-logs.sh`。 如果您使用的是第 2 AWS CLI 版，則需要 **cli-binary-format**選項。若要讓此成為預設的設定，請執行 `aws configure set cli-binary-format raw-in-base64-out`。若要取得更多資訊，請參閱*《AWS Command Line Interface 使用者指南第 2 版》*中 [AWS CLI 支援的全域命令列選項](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list)。 ``` #!/bin/bash aws lambda invoke --function-name my-function --cli-binary-format raw-in-base64-out --payload '{"key": "value"}' out sed -i'' -e 's/"//g' out sleep 15 aws logs get-log-events --log-group-name /aws/lambda/my-function --log-stream-name stream1 --limit 5 ``` **Example macOS 和 Linux (僅限)** 在相同的命令提示中，macOS 和 Linux 使用者可能需要執行下列命令，以確保指令碼可執行。 ``` chmod -R 755 get-logs.sh ``` **Example 擷取最後五個記錄事件** 在相同的命令提示中，執行下列指令碼以取得最後五個日誌事件。 ``` ./get-logs.sh ``` 您應該會看到下列輸出： ``` { "StatusCode": 200, "ExecutedVersion": "$LATEST" } { "events": [ { "timestamp": 1559763003171, "message": "START RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf Version: $LATEST\n", "ingestionTime": 1559763003309 }, { "timestamp": 1559763003173, "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tENVIRONMENT VARIABLES\r{\r \"AWS_LAMBDA_FUNCTION_VERSION\": \"$LATEST\",\r ...", "ingestionTime": 1559763018353 }, { "timestamp": 1559763003173, "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tEVENT\r{\r \"key\": \"value\"\r}\n", "ingestionTime": 1559763018353 }, { "timestamp": 1559763003218, "message": "END RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\n", "ingestionTime": 1559763018353 }, { "timestamp": 1559763003218, "message": "REPORT RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\tDuration: 26.73 ms\tBilled Duration: 27 ms \tMemory Size: 128 MB\tMax Memory Used: 75 MB\t\n", "ingestionTime": 1559763018353 } ], "nextForwardToken": "f/34783877304859518393868359594929986069206639495374241795", "nextBackwardToken": "b/34783877303811383369537420289090800615709599058929582080" } ``` ## 刪除日誌 當您刪除函數時，不會自動刪除日誌群組。若要避免無限期地儲存日誌，請刪除日誌群組，或[設定保留期間](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html#SettingLogRetention)，系統會在該時間之後自動刪除日誌。