本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS::Serverless::WebFunction 创建 AWS Lambda Web 函数，该函数通过托管端点处理 HTTP 请求。与为响应调用和事件而运行的 Lambda 事件函数不同，Web 函数运行您的 Web 服务器并直接接收 HTTP 请求。从中 AWS SAM 生成 Web Function、包含您的代码和配置的不可变修订版以及将流量路由到一个或多个修订版的端点。`AWS::Serverless::WebFunction` **注意** 部署到时 AWS CloudFormation， AWS SAM 会将您的 AWS SAM 资源转换为 CloudFormation 资源。有关更多信息，请参阅 [生成 CloudFormation 的资源 AWS SAM](sam-specification-generated-resources.md)。 **重要** 您的函数代码必须运行一个 HTTP 服务器，该服务器监听`AWS_LAMBDA_HTTP_ENDPOINT`环境变量中的主机和端口。未设置运行时间`PORT`。默认情况下，运行时`index.js`在部署包的根目录下运行。[EntryPoint](#sam-webfunction-entrypoint)用于运行不同的文件。 **重要** 存放您的部署包的 Amazon S3 存储桶必须满足以下要求： 版本控制已启用。 存储桶策略授`lambda.amazonaws.com`予`s3:GetObject`和`s3:GetObjectVersion`权限。例如，我们建议您使用与函数修订版`aws:SourceArn`相匹配的`ArnLike`条件来确定策略的范围`arn:aws:lambda:{{us-east-1}}:{{111122223333}}:web-function/{{my-function}}/revision/*`。 如果对象使用加密 SSE-KMS，则它使用客户管理的密钥，其密钥策略`lambda.amazonaws.com`允许调用`kms:Decrypt`。不支持 Amazon S3 (`aws/s3`) 的 AWS 托管密钥，因为您无法更改其密钥策略。 有关存储桶策略的示例，请参阅*AWS Lambda 开发人员*[指南中的 Lambda 存储](https://docs.aws.amazon.com/lambda/latest/dg/web-functions-code-s3.html#web-functions-code-s3-bucket-policy)桶策略。 `CodeUri`必须引用 Amazon S3 中的对象。`sam build`和`sam package`命令不支持此资源的本地路径。 ## 语法 要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` Type: AWS::Serverless::WebFunction Properties: [AuthType](#sam-webfunction-authtype): {{String}} [AutoDeploymentMode](#sam-webfunction-autodeploymentmode): {{String}} [CodeUri](#sam-webfunction-codeuri): {{String | CodeUri}} [EgressNetworkConnectorArn](#sam-webfunction-egressnetworkconnectorarn): {{String}} [EndpointDescription](#sam-webfunction-endpointdescription): {{String}} [EndpointName](#sam-webfunction-endpointname): {{String}} [EndpointType](#sam-webfunction-endpointtype): {{String}} [EntryPoint](#sam-webfunction-entrypoint): {{String}} [EnvironmentVariables](#sam-webfunction-environmentvariables): {{Map}} [ExecutionRoleArn](#sam-webfunction-executionrolearn): {{String}} [FunctionName](#sam-webfunction-functionname): {{String}} [InlineCode](#sam-webfunction-inlinecode): {{String}} [KmsKeyArn](#sam-webfunction-kmskeyarn): {{String}} [LoggingConfig](#sam-webfunction-loggingconfig): {{Map}} [MaxConcurrencyPerEnvironment](#sam-webfunction-maxconcurrencyperenvironment): {{Integer}} [ReplicaRegions](#sam-webfunction-replicaregions): {{List | ReplicaRegions}} [RevisionDescription](#sam-webfunction-revisiondescription): {{String}} [RevisionWeights](#sam-webfunction-revisionweights): {{RevisionWeights}} [Runtime](#sam-webfunction-runtime): {{String}} [ScalingConfig](#sam-webfunction-scalingconfig): {{Map}} [Tags](#sam-webfunction-tags): {{Map}} [ThrottleConfig](#sam-webfunction-throttleconfig): {{Map}} [Timeout](#sam-webfunction-timeout): {{Integer}} ``` ## Properties `AuthType` 终端节点如何授权请求。 + `IamAuth`: Lambda 使用签名版本 4 和 IAM 对请求进行授权。呼叫者需要该`lambda:InvokeWebFunctionEndpoint`权限，该权限是通过针对该函数的基于资源的策略授予的。 + `ApplicationManaged`: 终端节点是公共的。您的函数必须自行授权每个请求。 *有效值*：`IamAuth`、`ApplicationManaged` *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionEndpoint`资源的`[AuthType](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-authtype)`属性。 `AutoDeploymentMode` 端点如何跨版本路由流量。 + `LatestRevision`: 将 100% 的流量发送到此部署创建的修订版。 + `Disabled`: 根据路径进行交通[RevisionWeights](#sam-webfunction-revisionweights)。 您可以使用哪些值以及`RevisionWeights`是否为必填值取决于 [EndpointType](#sam-webfunction-endpointtype)： + `HomeRegion`: 使用任一值。带有`Disabled`，`RevisionWeights`为必填项。 + `MultiRegion`或者`PerRegion`：使用`Disabled`。如果省略`RevisionWeights`，则端点会将 100% 的流量路由到在同一堆栈中创建的修订，因此您可以在单个部署中创建终端节点。流量不会转移到以后的部署创建的修订版上。 AWS SAM 转换模板时必须解析该值。支持 A `Ref` 到参数。不支持其他内部函数。 *有效值*：`LatestRevision`、`Disabled` *类型*：字符串 *必需*：否 *默认值*：`LatestRevision` *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `CodeUri` 部署包的 Amazon S3 位置。使用`Bucket`、`Key`和可选`Version`键指定 `s3://{{bucket}}/{{key}}` URI 或对象。有关存储桶的要求，请参阅本页顶部的注释。 *类型*：字符串 \| [CodeUri](sam-property-webfunction-codeuri.md) *是否必需*：是 *CloudFormation 兼容性*：此属性类似于`AWS::Lambda::WebFunctionRevision`资源的`[BuildConfig.CodeConfig.S3Object](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-lambda-webfunctionrevision-s3object.html)`属性。 AWS SAM 将 `s3://` URI 转换为`Bucket``Key`、和`VersionId`。 `EgressNetworkConnectorArn` 网络连接器的版本限定 ARN，用于通过您的 VPC 路由函数的出站流量。例如，ARN 必须以版本号结尾。`arn:aws:lambda:us-east-1:123456789012:network-connector:my-connector:1`要在同一模板中使用最新版本的连接器，请指定`!GetAtt {{MyConnector}}.LatestVersionArn`。连接器[ComputeTypes](sam-resource-networkconnector.md#sam-networkconnector-computetypes)必须是`WebFunction`。 如果您指定文字字符串，则 AWS SAM 会检查它是否为版本限定的网络连接器 ARN。内部函数由服务传递和验证。更改此值会创建新的修订版。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[ServiceConfig.EgressNetworkConnectorArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-lambda-webfunctionrevision-serviceconfig.html)`属性。 `EndpointDescription` 终端节点的描述。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionEndpoint`资源的`[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-description)`属性。 `EndpointName` 端点的名称。更改名称会替换端点。更改`EndpointType`还会替换端点，因此请`EndpointName`同时进行更改。 CloudFormation 如果没有新名称，就无法替换自定义名称的资源。 *类型*：字符串 *必需*：否 *默认值*：`prod` *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionEndpoint`资源的`[EndpointName](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-endpointname)`属性。 `EndpointType` 终端节点在哪里提供流量。 + `HomeRegion`: 从堆栈的区域提供服务。 + `MultiRegion`：将函数复制到中的区域，[ReplicaRegions](#sam-webfunction-replicaregions)并将每个请求路由到最近的区域。 + `PerRegion`：在每个副本区域中公开一个单独的终端节点。 `MultiRegion`并`PerRegion`要求`AutoDeploymentMode: Disabled`。 *有效值*: `HomeRegion`, `MultiRegion`, `PerRegion` *类型*：字符串 *必需*：否 *默认值*：`HomeRegion` *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionEndpoint`资源的`[EndpointType](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-endpointtype)`属性。 `EntryPoint` 运行时相对于部署包根目录运行的文件。 AWS SAM 在保留的`AWS_LAMBDA_NODEJS_ENTRYPOINT`环境变量中将其传递给运行时。 如果是内部函数，`EnvironmentVariables`则不能使用此属性。 *类型*：字符串 *必需*：否 *默认值*：`index.js` *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `EnvironmentVariables` Key-value 要设置为修订版本的环境变量的对。 + 密钥必须以字母开头，并且仅包含字母、数字和下划线。 + 值必须为非空且最多 4,096 个字符。 + AWS SAM 将数字和布尔值转换为字符串。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[ServiceConfig.EnvironmentVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-lambda-webfunctionrevision-serviceconfig.html#cfn-lambda-webfunctionrevision-serviceconfig-environmentvariables)`属性。 `ExecutionRoleArn` 函数在运行时担任的 IAM 角色的 ARN。如果您未指定角色，则使用`AWSLambdaBasicExecutionRole`托管策略和逻辑 ID 为 AWS SAM 创建一个角色`{{}}Role`。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[ServiceConfig.ExecutionRoleArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-lambda-webfunctionrevision-serviceconfig.html#cfn-lambda-webfunctionrevision-serviceconfig-executionrolearn)`属性。 `FunctionName` 函数的名称。在一个账户中，所有区域的函数名称必须是唯一的。如果不指定名称，则根据逻辑 ID 和堆栈 ID AWS SAM 生成一个名称，最多 64 个字符。更改名称会替换函数、其修订版和端点。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunction``AWS::Lambda::WebFunctionRevision`、和`AWS::Lambda::WebFunctionEndpoint`资源的`[FunctionName](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunction.html#cfn-lambda-webfunction-functionname)`属性。 `InlineCode` 不受 `AWS::Serverless::WebFunction` 支持。使用 [CodeUri](#sam-webfunction-codeuri)。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `KmsKeyArn` 用于加密修订版环境变量的 AWS KMS 密钥的 ARN。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[KmsKeyArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionrevision.html#cfn-lambda-webfunctionrevision-kmskeyarn)`属性。 `LoggingConfig` 修订版的日志配置，例如日志组和日志级别。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[ServiceConfig.TelemetryConfig.LoggingConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-lambda-webfunctionrevision-telemetryconfig.html#cfn-lambda-webfunctionrevision-telemetryconfig-loggingconfig)`属性。 `MaxConcurrencyPerEnvironment` 每个执行环境处理的最大并发请求数。 *类型*：整数 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[ServiceConfig.MaxConcurrencyPerEnvironment](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-lambda-webfunctionrevision-serviceconfig.html#cfn-lambda-webfunctionrevision-serviceconfig-maxconcurrencyperenvironment)`属性。 `ReplicaRegions` 要将函数复制到的区域。将此属性与`MultiRegion`和`PerRegion`端点一起使用。指定区域代码和区域组的列表，或者使用`IncludeRegions`和可选的对象`ExcludeRegions`。 *类型*：列表 \| [ReplicaRegions](sam-property-webfunction-replicaregions.md) *必需*：否 *CloudFormation 兼容性*：此属性类似于`AWS::Lambda::WebFunctionEndpoint`资源的`[Regions](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-regions)`属性。 AWS SAM 展开区域组`ExcludeRegions`并应用生成区域列表。 `RevisionDescription` 此部署创建的修订版的描述。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionrevision.html#cfn-lambda-webfunctionrevision-description)`属性。 `RevisionWeights` 修订版 ID 与流量权重的映射。如果`AutoDeploymentMode`是，则使用此属性`Disabled`。最多指定两个修订版。每个权重都是一个介于 1 到 100 之间的整数，且权重之和必须等于 100。 *类型*：[RevisionWeights](sam-property-webfunction-revisionweights.md) *必填*：条件性。“是” `Disabled` 和 `AutoDeploymentMode` “是” 时`EndpointType`为必填项`HomeRegion`。 *CloudFormation 兼容性*：此属性类似于`AWS::Lambda::WebFunctionEndpoint`资源的`[RevisionWeights](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-revisionweights)`属性。 AWS SAM 将地图转换为`RevisionId`和`Weight`对象的列表。 `Runtime` 例如，函数的运行时间`nodejs24.x`。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[BuildConfig.RuntimeConfig.Runtime](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-lambda-webfunctionrevision-runtimeconfig.html#cfn-lambda-webfunctionrevision-runtimeconfig-runtime)`属性。 `ScalingConfig` 端点的扩展配置，例如执行环境的最大数量。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionEndpoint`资源的`[ScalingConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-scalingconfig)`属性。 `Tags` 键值对映射，用于指定添加到函数和生成的执行角色的 AWS SAM 标签。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性类似于`AWS::Lambda::WebFunction`资源的`[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunction.html#cfn-lambda-webfunction-tags)`属性。中的`Tags`属性由键值对 AWS SAM 组成（而 CloudFormation 在此属性中则由`Tag`对象列表组成）。此外，还 AWS SAM 会自动向函数以及为其生成的默认角色添加`lambda:createdBy:SAM`标签。 `ThrottleConfig` 终端节点的限制配置，例如最大请求速率。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionEndpoint`资源的`[ThrottleConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-throttleconfig)`属性。 `Timeout` 该函数每次请求可以运行的最长时间（以秒为单位）。有效值介于 3 到 900 之间。 *类型*：整数 *必需*：否 *默认值*：`30` *CloudFormation 兼容性*：此属性直接传递给`AWS::Lambda::WebFunctionRevision`资源的`[ServiceConfig.TimeoutSeconds](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-lambda-webfunctionrevision-serviceconfig.html#cfn-lambda-webfunctionrevision-serviceconfig-timeoutseconds)`属性。 ## 返回值 ### Ref 当向`Ref`内部函数提供此资源的逻辑 ID 时，它将返回 Web 函数的 ARN。在需要函数名称的地方，请`FunctionName`改用值。 有关使用 `Ref` 函数的更多信息，请参阅*《AWS CloudFormation 用户指南》*中的 [`Ref`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)。 ### Fn:: GetAtt `Fn::GetAtt` 返回一个此类型指定属性的值。以下为可用属性和示例返回值。 有关使用 `Fn::GetAtt` 的更多信息，请参阅*《AWS CloudFormation 用户指南》*中的 [`Fn::GetAtt`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html)。 `FunctionArn` 网络函数的亚马逊资源名称 (ARN)。 `State` Web 函数的当前状态。 `StateReason` Web 函数处于当前状态的原因。 `CreatedAt` Web 函数的创建时间。 `UpdatedAt` Web 函数上次更新的时间。 要引用 AWS SAM 生成的修订版或端点，请使用其逻辑 ID `{{}}Revision` 和`{{}}Endpoint`。例如，`!GetAtt MyWebFunctionEndpoint.DomainName`返回具有逻辑 ID 的 Web 函数端点的域名`MyWebFunction`。有关更多信息，请参阅 [CloudFormation 何时生成的资源 AWS::Serverless::WebFunction 已指定](sam-specification-generated-resources-webfunction.md)。 ## 示例 ### 基本的网络功能 以下示例创建了一个 Web 函数，其 IAM-authorized 端点位于堆栈的区域。 AWS SAM 生成执行角色，端点将所有流量路由到此部署创建的修订版。 ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: MyWebFunction: Type: AWS::Serverless::WebFunction Properties: Runtime: nodejs24.x AuthType: IamAuth CodeUri: Bucket: amzn-s3-demo-bucket Key: webfn.zip Version: {{object-version-id}} Timeout: 30 Outputs: EndpointUrl: Value: !Sub https://${MyWebFunctionEndpoint.DomainName} ``` ### 在两个修订版之间分配流量 以下示例禁用自动部署，将 90% 的流量发送到一个现有修订版，10% 的流量发送到另一个修订版。两个修订版都必须已经存在。 ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: MyWebFunction: Type: AWS::Serverless::WebFunction Properties: Runtime: nodejs24.x AuthType: IamAuth CodeUri: s3://amzn-s3-demo-bucket/webfn-v2.zip AutoDeploymentMode: Disabled RevisionWeights: rev-abc123: 90 rev-def456: 10 ``` ### Multi-Region 网络函数 以下示例将该函数复制到除外的美国区域，`us-west-1`并将每个请求路由到最近的区域。由于省略`RevisionWeights`了，因此端点会将所有流量路由到在此堆栈中创建的修订版。 ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: MyWebFunction: Type: AWS::Serverless::WebFunction Properties: Runtime: nodejs24.x AuthType: IamAuth CodeUri: Bucket: amzn-s3-demo-bucket Key: webfn.zip Version: {{object-version-id}} EndpointName: prodmr EndpointType: MultiRegion AutoDeploymentMode: Disabled ReplicaRegions: IncludeRegions: - US ExcludeRegions: - us-west-1 ``` ### 带有 VPC 出口的 Web 函数 以下示例为 Web Functions 创建网络连接器，并通过连接器的子网和安全组路由该函数的出站流量。 ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Resources: MyConnector: Type: AWS::Serverless::NetworkConnector Properties: ComputeTypes: - WebFunction VpcConfig: SubnetIds: - subnet-0abc123def4567890 - subnet-0def456abc7890123 SecurityGroupIds: - sg-0abc1234abcde0001 NetworkProtocol: IPv4 MyWebFunction: Type: AWS::Serverless::WebFunction Properties: Runtime: nodejs24.x AuthType: IamAuth CodeUri: Bucket: amzn-s3-demo-bucket Key: webfn.zip Version: {{object-version-id}} EgressNetworkConnectorArn: !GetAtt MyConnector.LatestVersionArn ```