AWS::Serverless::Function - Amazon Serverless Application Model
语法属性返回值示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

AWS::Serverless::Function

创建 Amazon Lambda 函数、Amazon Identity and Access Management (IAM) 执行角色和触发该函数的事件源映射。

AWS::Serverless::Function 资源还支持 Metadata 资源属性，因此您可以指示 Amazon SAM 构建应用程序所需的自定义运行时系统。有关构建自定义运行时系统的更多信息，请参阅 在 Amazon SAM 中构建具有自定义运行时的 Lambda 函数。

注意

部署到 Amazon CloudFormation 时，Amazon SAM 会将您的 Amazon SAM 资源转换为 Amazon CloudFormation 资源。有关更多信息，请参阅 为 Amazon SAM 生成的 Amazon CloudFormation 资源。

语法

要在您的 Amazon Serverless Application Model (Amazon SAM) 模板中声明此实体，请使用以下语法。

属性

Architectures

该函数的指令集架构。

有关此属性更多信息，请参阅《Amazon Lambda 开发人员指南》中的 Lambda 指令集架构。

有效值：x86_64 或 arm64 之一。

类型：列表

必需：否

默认值：x86_64

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 Architectures 属性。

AssumeRolePolicyDocument

为针对该函数默认创建的 Role 添加 AssumeRolePolicyDocument。如果未指定此属性，则 Amazon SAM 为该函数添加默认的代入角色。

类型：JSON

必需：否

Amazon CloudFormation 兼容性：此属性类似于 AWS::IAM::Role 资源的 AssumeRolePolicyDocument 属性。Amazon SAM 将此属性添加到为此函数生成的 IAM 角色中。如果为此函数提供了角色的 Amazon 资源名称（ARN），则此属性将不执行任何操作。

AutoPublishAlias

Lambda 别名的名称。要了解有关 Lambda 别名的更多信息，请参阅《Amazon Lambda 开发人员指南》中的 Lambda 函数别名。有关使用此属性的示例，请参见 使用 Amazon SAM 逐步部署无服务器应用程序。

如果设置了此属性，Amazon SAM 会生成 AWS::Lambda::Version 和 AWS::Lambda::Alias 资源。有关此场景的更多信息，请参阅指定了 AutoPublishAlias 属性。有关生成的 Amazon CloudFormation 资源的一般信息，请参阅 为 Amazon SAM 生成的 Amazon CloudFormation 资源。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性为 Amazon SAM 独有，没有 Amazon CloudFormation 等效属性。

AutoPublishAliasAllProperties

指定何时创建新的 AWS::Lambda::Version。当为 true 时，修改 Lambda 函数中的任何属性时，就会创建新的 Lambda 版本。当为 false 时，只有修改了以下任何属性时，才会创建新的 Lambda 版本：

  • Environment、MemorySize 或者 SnapStart。

  • 导致 Code 属性更新的任何更改，例如 CodeDict、ImageUri、或 InlineCode。

此属性需要定义 AutoPublishAlias。

如果也指定 AutoPublishCodeSha256，则其行为优先于 AutoPublishAliasAllProperties: true。

类型：布尔值

必需：否

默认值：false

Amazon CloudFormation 兼容性：此属性为 Amazon SAM 独有，没有 Amazon CloudFormation 等效属性。

AutoPublishCodeSha256

使用时，此字符串将与 CodeUri 值一起确定是否需要发布新的 Lambda 版本。此属性通常用于解决以下部署问题：部署包存储在 Amazon S3 位置，且被包含更新后的 Lambda 函数代码的新部署包取代，但 CodeUri 属性保持不变（相反情况是新的部署包上传到新的 Amazon S3 位置并且 CodeUri 更改为新位置）。

此问题由 Amazon SAM 模板标记，具有以下特征：

在这种情况下，更新 AutoPublishCodeSha256 会导致成功创建新的 Lambda 版本。但是，部署到 Amazon S3 的新函数代码将无法识别。要识别新的函数代码，请考虑在 Amazon S3 存储桶中使用版本控制。为 Lambda 函数指定 Version 属性，并将存储桶配置为始终使用最新的部署包。

在这种情况下，要成功触发逐步部署，必须为 AutoPublishCodeSha256 提供一个唯一的值。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性为 Amazon SAM 独有，没有 Amazon CloudFormation 等效属性。

CodeSigningConfigArn

AWS::Lambda::CodeSigningConfig 资源的 ARN，用于为此函数启用代码签名。有关代码签名的更多信息，请参阅 为您的 Amazon SAM 应用程序设置代码签名。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 CodeSigningConfigArn 属性。

CodeUri

函数的代码。可接受的值包括：

  • 该函数的 Amazon S3 URI。例如 s3://bucket-123456789/sam-app/1234567890abcdefg。

  • 函数的本地路径。例如 hello_world/。

  • 一个 FunctionCode 对象。

注意

如果您提供函数的 Amazon S3 URI 或 FunctionCode 对象，则必须引用有效的 Lambda 部署包。

如果您提供本地文件路径，请在部署时使用 Amazon SAM CLI 上传本地文件。要了解更多信息，请参阅Amazon SAM 如何在部署时上传本地文件。

如果您在 CodeUri 属性中使用内置函数，Amazon SAM 将无法正确解析这些值。可以考虑改用 AWS::LanguageExtensions 转换。

类型：[ 字符串 | FunctionCode ]

必填：条件性。当 PackageType 设置为 Zip 时，则 CodeUri 或 InlineCode 中的一种为必需。

Amazon CloudFormation 兼容性：此属性类似于 AWS::Lambda::Function 资源的 Code 属性。嵌套的 Amazon S3 属性的命名有所不同。

DeadLetterQueue

在 Lambda 发送无法处理的事件时配置 Amazon Simple Notification Service (Amazon SNS)主题或 Amazon Simple Queue Service (Amazon SQS) 队列。有关死信队列功能的更多信息，请参阅《Amazon Lambda 开发人员指南》中的死信队列。

注意

如果您的 Lambda 函数的事件源是 Amazon SQS 队列，请为源队列而不是 Lambda 函数配置死信队列。您为函数配置的死信队列用于函数的异步调用队列，而不是用于事件源队列。

类型：映射 | DeadLetterQueue

必需：否

Amazon CloudFormation 兼容性：此属性类似于 AWS::Lambda::Function 资源的 DeadLetterConfig 属性。在 Amazon CloudFormation 中，类型派生自 TargetArn，而在 Amazon SAM 中，您必须将类型与 TargetArn 一起传递。

DeploymentPreference

用于启用逐步 Lambda 部署的设置。

如果指定了 DeploymentPreference 对象，则 Amazon SAM 会创建名为 ServerlessDeploymentApplication 的 AWS::CodeDeploy::Application（每个堆栈一个）、名为 <function-logical-id>DeploymentGroup 的 AWS::CodeDeploy::DeploymentGroup 和名为 CodeDeployServiceRole 的 AWS::IAM::Role。

类型：DeploymentPreference

必需：否

Amazon CloudFormation 兼容性：此属性为 Amazon SAM 独有，没有 Amazon CloudFormation 等效属性。

另请参阅：有关此属性的更多信息，请参阅 使用 Amazon SAM 逐步部署无服务器应用程序。

Description

该函数的描述。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 Description 属性。

Environment

运行时系统环境的配置。

类型：环境

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 Environment 属性。

EphemeralStorage

指定 /tmp 中 Lambda 函数可用的磁盘空间（以 MB 为单位）的对象。

有关此属性的更多信息，请参阅《Amazon Lambda 开发人员指南》中的 Lambda 执行环境。

类型：EphemeralStorage

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 EphemeralStorage 属性。

EventInvokeConfig

描述 Lambda 函数的事件调用配置的对象。

类型：EventInvokeConfiguration

必需：否

Amazon CloudFormation 兼容性：此属性为 Amazon SAM 独有，没有 Amazon CloudFormation 等效属性。

Events

指定触发此函数的事件。事件由一个类型和一组依赖于该类型的属性组成。

类型：EventSource

必需：否

Amazon CloudFormation 兼容性：此属性为 Amazon SAM 独有，没有 Amazon CloudFormation 等效属性。

FileSystemConfigs

指定 Amazon Elastic File System (Amazon EFS) 文件系统连接设置的 FileSystemConfig 对象列表。

如果模板包含 AWS::EFS::MountTarget 资源，您还必须指定一个 DependsOn 资源属性，以确保在函数之前创建或更新装载目标。

类型：列表

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 FileSystemConfigs 属性。

FunctionName

函数的名称。如果您没有指定名称，则系统为您生成唯一的名称。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 FunctionName 属性。

FunctionUrlConfig

描述函数 URL 的对象。函数 URL 是可用于调用函数的 HTTPS 端点。

有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的函数 URL。

类型：FunctionUrlConfig

必需：否

Amazon CloudFormation 兼容性：此属性为 Amazon SAM 独有，没有 Amazon CloudFormation 等效属性。

Handler

代码中被调用以开始执行的函数。仅当属性 PackageType 为 Zip 时，该属性是必需属性。

类型：字符串

必需：条件

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 Handler 属性。

ImageConfig

用于配置 Lambda 容器映像设置的对象。有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的将容器映像与 Lambda 结合使用。

类型：ImageConfig

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 ImageConfig 属性。

ImageUri

Lambda 函数容器映像的 Amazon Elastic Container Registry (Amazon ECR) 存储库 URI 仅当 PackageType 属性设置为 Image 时，此属性才适用，否则将被忽略。有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的将容器映像与 Lambda 结合使用。

注意

如果 PackageType 属性设置为 Image，则 ImageUri 为必需，或者必须使用 Amazon SAM 模板文件中的必要 Metadata 条目来构建应用程序。有关更多信息，请参阅 使用 Amazon SAM 进行默认构建。

使用必要的 Metadata 条目构建应用程序优先于 ImageUri，因此，如果您同时指定两者，则 ImageUri 会被忽略。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function Code 数据类型的 ImageUri 属性。

InlineCode

直接在模板中编写的 Lambda 函数代码。仅当 PackageType 属性设置为 Zip 时，此属性才适用，否则将被忽略。

注意

如果 PackageType 属性设置为 Zip（默认），则 CodeUri 或 InlineCode 中的一个为必需。

类型：字符串

必需：条件

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function Code 数据类型的 ZipFile 属性。

KmsKeyArn

Amazon Key Management Service (Amazon KMS) 密钥的 ARN，Lambda 使用它加密和解密函数的环境变量。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 KmsKeyArn 属性。

Layers

此函数应使用的 LayerVersion ARN 列表。此处指定的顺序是运行 Lambda 函数时它们的导入顺序。版本可以是包含版本号的完整 ARN，也可以是 LayerVersion 资源的引用。例如，对 LayerVersion 的引用为 !Ref MyLayer，而包含版本号的完整 ARN 为 arn:aws:lambda:region:account-id:layer:layer-name:version。

类型：列表

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 Layers 属性。

LoggingConfig

该函数的 Amazon CloudWatch Logs 配置设置。

类型：LoggingConfig

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 LoggingConfig 属性。

MemorySize

每次调用函数时分配的内存大小（以 MB 为单位）。

类型：整数

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 MemorySize 属性。

PackageType

Lambda 函数的部署包类型。有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的Lambda 部署包。

注意:

1. 如果此属性设置为 Zip（默认），则将应用 CodeUri 或 InlineCode，并忽略 ImageUri。

2. 如果此属性设置为 Image，则仅应用 ImageUri，并忽略 CodeUri 和 InlineCode。存储函数容器映像所需的 Amazon ECR 存储库可以由 Amazon SAM CLI 自动创建。有关更多信息，请参阅 sam deploy。

有效值：Zip 或 Image

类型：字符串

必需：否

默认值：Zip

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 PackageType 属性。

PermissionsBoundary

用于此函数执行角色的权限边界的 ARN。仅当为您生成角色时，此属性才起作用。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::IAM::Role 资源的 PermissionsBoundary 属性。

Policies

此函数的权限策略。策略将附加到函数的默认 Amazon Identity and Access Management (IAM) 执行角色中。

此属性接受单个值或值列表。允许的值包括：

注意

如果指定 Role 属性，则将忽略该属性。

类型：字符串 | 列表 | 映射

必需：否

Amazon CloudFormation 兼容性：此属性类似于 AWS::IAM::Role 资源的 Policies 属性。

PropagateTags

指明是否将 Tags 属性中的标签传递给 AWS::Serverless::Function 生成的资源。指定 True 以在生成的资源中传播标签。

类型：布尔值

必需：否

默认值：False

Amazon CloudFormation 兼容性：此属性为 Amazon SAM 独有，没有 Amazon CloudFormation 等效属性。

ProvisionedConcurrencyConfig

函数别名的预置并发配置。

注意

仅当设置 AutoPublishAlias 时才可以指定 ProvisionedConcurrencyConfig。否则将导致错误。

类型：ProvisionedConcurrencyConfig

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Alias 资源的 ProvisionedConcurrencyConfig 属性。

RecursiveLoop

函数的递归循环检测配置的状态。

当此值设置为 Allow 且 Lambda 检测到您的函数作为递归循环的一部分调用时，它不会采取任何操作。

当此值设置为 Terminate 且 Lambda 检测到您的函数作为递归循环的一部分调用时，它会停止调用函数并通知您。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 RecursiveLoop 属性。

ReservedConcurrentExecutions

希望为函数预留的最大并发执行数。

有关此属性更多信息，请参阅《Amazon Lambda 开发人员指南》中的 Lambda 函数扩展。

类型：整数

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 ReservedConcurrentExecutions 属性。

Role

要用作此函数执行角色的 IAM 角色的 ARN。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性类似于 AWS::Lambda::Function 资源的 Role 属性。这在 Amazon CloudFormation 中为必需，但在 Amazon SAM 中并非必需。如果未指定角色，则会为您创建一个逻辑 ID 为 <function-logical-id>Role 的角色。

RolePath

函数的 IAM 执行角色的路径。

生成角色时请使用此属性。当使用 Role 属性指定角色时，请勿使用。

类型：字符串

必需：条件

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::IAM::Role 资源的 Path 属性。

Runtime

函数的运行时的标识符。仅当属性 PackageType 为 Zip 时，该属性是必需属性。

注意

如果为此属性指定 provided 标识符，则可以使用 Metadata 资源属性指示 Amazon SAM 构建此函数所需的自定义运行时系统。有关构建自定义运行时系统的更多信息，请参阅 在 Amazon SAM 中构建具有自定义运行时的 Lambda 函数。

类型：字符串

必需：条件

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 Runtime 属性。

RuntimeManagementConfig

为 Lambda 函数配置运行时系统管理选项，例如运行时环境更新、回滚行为以及选择特定的运行时版本。要了解更多信息，请参阅《Amazon Lambda 开发人员指南》中的 Lambda 运行时系统更新。

类型：RuntimeManagementConfig

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 RuntimeManagementConfig 属性。

SnapStart

创建任何新 Lambda 函数版本的快照。快照是初始化函数的缓存状态，包括其所有依赖项。函数仅被初始化一次，缓存的状态将在未来的所有调用中重复使用，从而通过减少必须初始化函数的次数来提高应用程序性能。要了解更多信息，请参阅《Amazon Lambda 开发人员指南》中的使用 Lambda SnapStart 提高启动性能。

类型：SnapStart

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 SnapStart 属性。

SourceKmsKeyArn

代表用于加密客户 ZIP 功能代码的 KMS 密钥 ARN。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function Code 数据类型的 SourceKmsKeyArn 属性。

Tags

指定添加到此函数的标签的映射（字符串到字符串）。有关标签的有效键和值的详细信息，请参阅《Amazon Lambda 开发人员指南》中的标签键和值要求。

创建堆栈后，Amazon SAM 会自动向此 Lambda 函数以及为此函数生成的默认角色添加 lambda:createdBy:SAM 标签。

类型：映射

必需：否

Amazon CloudFormation 兼容性：此属性类似于 AWS::Lambda::Function 资源的 Tags 属性。Amazon SAM 中的 Tags 属性由键值对组成（而在 Amazon CloudFormation 中此属性则由 Tag 对象列表组成）。此外，Amazon SAM 还会自动向此 Lambda 函数以及为此函数生成的默认角色添加 lambda:createdBy:SAM 标签。

Timeout

函数在停止之前可以运行的最长时间（以秒为单位）。

类型：整数

必需：否

原定设置值：3

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 Timeout 属性。

Tracing

指定函数的 X-Ray 跟踪模式的字符串。

  • Active – 为该函数激活 X-Ray 跟踪

  • Disabled – 为该函数停用 X-Ray 跟踪

  • PassThrough – 为该函数激活 X-Ray 跟踪 采样决策委托给下游服务。

如果指定为 Active 或 PassThrough 且未设置 Role 属性，则 Amazon SAM 会将 arn:aws:iam::aws:policy/AWSXrayWriteOnlyAccess 策略添加到它为您创建的 Lambda 执行角色中。

有关 X-Ray 的更多信息，请参阅《Amazon Lambda 开发人员指南》中的结合使用 Amazon Lambda 和 Amazon X-Ray。

有效值：[Active|Disabled|PassThrough]

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性类似于 AWS::Lambda::Function 资源的 TracingConfig 属性。

VersionDescription

指定在新的 Lambda 版本资源上添加的 Description 字段。

类型：字符串

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Version 资源的 Description 属性。

VpcConfig

该配置使该函数能够访问您的虚拟私有云（VPC）中的私有资源。

类型：VpcConfig

必需：否

Amazon CloudFormation 兼容性：此属性直接传递给 AWS::Lambda::Function 资源的 VpcConfig 属性。

返回值

Ref

当向 Ref 内置函数提供此资源的逻辑 ID 时，将返回底层 Lambda 函数的资源名称。

有关使用 Ref 函数的更多信息，请参阅《Amazon CloudFormation 用户指南》中的 Ref。

Fn::GetAtt

Fn::GetAtt 返回一个此类型指定属性的值。以下为可用属性和示例返回值。

有关使用 Fn::GetAtt 的更多信息，请参阅《Amazon CloudFormation 用户指南》中的 Fn::GetAtt。

Arn

底层 Lambda 函数的 ARN。

示例

简单函数

以下是 Amazon S3 存储桶中包类型为 Zip（默认）的 AWS::Serverless::Function 资源和函数代码的基本示例。

YAML

Type: AWS::Serverless::Function
Properties:
  Handler: index.handler
  Runtime: python3.9
  CodeUri: s3://bucket-name/key-name

函数属性示例

以下是使用 InlineCode、Layers、Tracing、Policies、Amazon EFS和 Api 事件源的包类型为 Zip（默认）的 AWS::Serverless::Function 示例。

YAML

Type: AWS::Serverless::Function
DependsOn: MyMountTarget        # This is needed if an AWS::EFS::MountTarget resource is declared for EFS
Properties:
  Handler: index.handler
  Runtime: python3.9
  InlineCode: |
    def handler(event, context):
      print("Hello, world!")
  ReservedConcurrentExecutions: 30
  Layers:
    - Ref: MyLayer
  Tracing: Active
  Timeout: 120
  FileSystemConfigs:
    - Arn: !Ref MyEfsFileSystem
      LocalMountPath: /mnt/EFS
  Policies:
    - AWSLambdaExecute
    - Version: '2012-10-17		 	 	 ' 
      Statement:
        - Effect: Allow
          Action:
            - s3:GetObject
            - s3:GetObjectACL
          Resource: 'arn:aws:s3:::sam-s3-demo-bucket/*'
  Events:
    ApiEvent:
      Type: Api
      Properties:
        Path: /path
        Method: get

ImageConfig 示例

以下是包类型为 Image 的 Lambda 函数的 ImageConfig 示例。

YAML

HelloWorldFunction:
  Type: AWS::Serverless::Function
  Properties:
    PackageType: Image
    ImageUri: account-id.dkr.ecr.region.amazonaws.com/ecr-repo-name:image-name
    ImageConfig:
      Command:
        - "app.lambda_handler"
      EntryPoint:
        - "entrypoint1"
      WorkingDirectory: "workDir"

RuntimeManagementConfig 示例

配置为根据当前行为更新其运行时环境的 Lambda 函数：

TestFunction
  Type: AWS::Serverless::Function
  Properties:
    ...
    Runtime: python3.9
    RuntimeManagementConfig:
      UpdateRuntimeOn: Auto

配置为在函数更新时更新其运行时环境的 Lambda 函数：

TestFunction
  Type: AWS::Serverless::Function
  Properties:
    ...
    Runtime: python3.9
    RuntimeManagementConfig:
      UpdateRuntimeOn: FunctionUpdate

配置为手动更新其运行时环境的 Lambda 函数：

TestFunction
  Type: AWS::Serverless::Function
  Properties:
    ...
    Runtime: python3.9
    RuntimeManagementConfig:
      RuntimeVersionArn: arn:aws:lambda:us-east-1::runtime:4c459dd0104ee29ec65dcad056c0b3ddbe20d6db76b265ade7eda9a066859b1e
      UpdateRuntimeOn: Manual

SnapStart 示例

针对未来版本启用 SnapStart 的 Lambda 函数示例：

TestFunc
  Type: AWS::Serverless::Function
  Properties:
    ...
    SnapStart:
      ApplyOn: PublishedVersions