# 使用 PowerShell 构建 Lambda 函数
以下部分说明在使用 PowerShell 编写 Lambda 函数代码时如何应用常见的编程模式和核心概念。
Lambda 为 PowerShell 提供了以下示例应用程序：
+ [blank-powershell](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-powershell) – 此 PowerShell 函数可显示日志记录、环境变量和AWS开发工具包的使用情况。
在您开始之前，您必须先设置 PowerShell 开发环境。有关如何执行此操作的说明，请参阅 [设置 PowerShell 开发环境](powershell-devenv.md)。
要了解如何使用 AWSLambdaPSCore 模块从模板中下载示例 PowerShell 项目、创建 PowerShell 部署包，以及在AWS云中部署 PowerShell 函数，请参阅 [使用 .zip 文件归档部署 PowerShell Lambda 函数](powershell-package.md)。
Lambda 为.NET 语言提供以下运行时系统：
| 名称 | 标识符 | 操作系统 | 弃用日期 | 阻止函数创建 | 阻止函数更新 |
| --- | --- | --- | --- | --- | --- |
| .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 运行时提供一组工具和库。有关安装说明，请参阅 GitHub 上的 [Lambda tools for Powershell](https://github.com/aws/aws-lambda-dotnet/tree/master/PowerShell)。
AWSLambdaPSCore 模块包括以下 cmdlet，可帮助创作和发布 PowerShell Lambda 函数。
+ **Get-AWSPowerShellLambdaTemplate** – 返回入门模板列表。
+ **New-AWSPowerShellLambda** – 根据模板创建初始 PowerShell 脚本。
+ **Publish-AWSPowerShellLambda** – 将给定 PowerShell 脚本发布到 Lambda。
+ **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` 语句的更多信息，请参阅[关于 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` 语句，使其引用 `AWSPowerShell.NetCore` 模块，该模块支持 PowerShell Core，而不是 `AWSPowerShell` 模块，该模块仅支持 Windows PowerShell。此外，请确保使用 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 语句，该语句在 PowerShell 管道中添加 `$PSVersionTable`：
```
$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` – 函数的[记录器对象](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) 上使用 cmdlets，或者使用任何写入到 `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。
+ **Duration**（持续时间）– 函数的处理程序方法处理事件所花费的时间。
+ **Billed Duration**（计费持续时间）– 针对调用计费的时间量。
+ **Memory Size**（内存大小）– 分配给函数的内存量。
+ **Max Memory Used**（最大内存使用量）– 函数使用的内存量。如果调用共享执行环境，Lambda 会报告所有调用使用的最大内存。此行为可能会导致报告值高于预期。
+ **Init Duration**（初始持续时间）– 对于提供的第一个请求，为运行时在处理程序方法外部加载函数和运行代码所花费的时间。
+ **XRAY TraceId** – 对于追踪的请求，为 [AWS X-Ray 追踪 ID](services-xray.md)。
+ **SegmentId** – 对于追踪的请求，为 X-Ray 分段 ID。
+ **Sampled**（采样）– 对于追踪的请求，为采样结果。
## 在 Lambda 控制台中查看日志
调用 Lambda 函数后，您可以使用 Lambda 控制台查看日志输出。
如果可以在嵌入式**代码**编辑器中测试代码，则可以在**执行结果**中找到日志。使用控制台测试功能调用函数时，可以在**详细信息**部分找到**日志输出**。
## 在 CloudWatch 控制台中查看日志
您可以使用 Amazon CloudWatch 控制台查看所有 Lambda 函数调用的日志。
**使用 CloudWatch 控制台查看日志**
1. 打开 CloudWatch 控制台的 [Log groups](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` 字段，其中包含多达 4KB 来自调用的 base64 编码日志。
**Example 检索日志 ID**
以下示例说明如何从 `LogResult` 字段中检索名为 `my-function` 的函数的*日志 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
```
如果使用 **cli-binary-format** 版本 2，则 AWS CLI 选项是必需的。要将其设为默认设置，请运行 `aws configure set cli-binary-format raw-in-base64-out`。有关更多信息，请参阅*版本 2 的 AWS Command Line Interface 用户指南*中的 [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` 命令的输出。
复制以下代码示例的内容并将其作为 `get-logs.sh` 保存在 Lambda 项目目录中。
如果使用 **cli-binary-format** 版本 2，则 AWS CLI 选项是必需的。要将其设为默认设置，请运行 `aws configure set cli-binary-format raw-in-base64-out`。有关更多信息，请参阅*版本 2 的 AWS Command Line Interface 用户指南*中的 [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)，在该保留期之后，日志将自动删除。