本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS::Serverless::WebFunction 建立 AWS Lambda Web 函數，透過受管端點提供 HTTP 請求。與為了回應呼叫和事件而執行的 Lambda 事件函數不同，Web 函數會執行您的 Web 伺服器並直接接收 HTTP 請求。從單一 `AWS::Serverless::WebFunction` AWS SAM 產生 Web 函數、包含程式碼和組態的不可變修訂，以及將流量路由至一或多個修訂的端點。 **注意** 當您部署到 時 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 儲存貯體必須符合下列要求： 版本控制已啟用。 儲存貯體政策會授予 `s3:GetObject`和 `lambda.amazonaws.com` `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 使用 Signature 第 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 轉換範本時， 值必須解析。支援 參數`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)` 屬性。 會將 `s3://` URI AWS SAM 轉換為 `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` 要設定為修訂版環境變數的鍵/值對。 + 金鑰必須以字母開頭，且只包含字母、數字和底線。 + 值必須為非空白且最多 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。如果您未指定角色， 會 AWS SAM 建立一個具有 `AWSLambdaBasicExecutionRole` 受管政策且邏輯 ID 為 的角色`{{}}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`。 *類型*：List \| [ReplicaRegions](sam-property-webfunction-replicaregions.md) *必要*：否 *CloudFormation 相容性*：此屬性類似於 `AWS::Lambda::WebFunctionEndpoint` resource. AWS SAM expands 區域群組的 `[Regions](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-regions)` 屬性，並適用於`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` 修訂 IDs 到流量權重的映射。當 `AutoDeploymentMode`為 時，使用此屬性`Disabled`。指定最多兩個修訂。每個權重是從 1 到 100 的整數，且權重最多必須加到 100。 *類型*：[RevisionWeights](sam-property-webfunction-revisionweights.md) *必要*：有條件限制。當 `AutoDeploymentMode`為 `Disabled`且 `EndpointType`為 時為必要`HomeRegion`。 *CloudFormation 相容性*：此屬性類似於 `AWS::Lambda::WebFunctionEndpoint` resource. AWS SAM convert the map to a list of `RevisionId`和 `Weight` 物件的 `[RevisionWeights](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-webfunctionendpoint.html#cfn-lambda-webfunctionendpoint-revisionweights)` 屬性。 `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 當將此資源的邏輯 ID 提供給`Ref`內部 函數時，它會傳回 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` Web 函數的 Amazon Resource Name (ARN)。 `State` Web 函數的目前狀態。 `StateReason` Web 函數目前狀態的原因。 `CreatedAt` Web 函數建立的時間。 `UpdatedAt` Web 函數上次更新的時間。 若要參考 AWS SAM 產生的修訂或端點，請使用其邏輯 IDs `{{}}Revision`和 `{{}}Endpoint`。例如， 會`!GetAtt MyWebFunctionEndpoint.DomainName`傳回邏輯 ID 為 之 Web 函數的端點網域名稱`MyWebFunction`。如需詳細資訊，請參閱[CloudFormation 指定 AWS::Serverless::WebFunction 時產生的資源](sam-specification-generated-resources-webfunction.md)。 ## 範例 ### 基本 Web 函數 下列範例會在堆疊的 Region 中使用 IAM 授權端點建立 Web 函數。 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 ``` ### 多區域 Web 函數 下列範例會將函數複寫到美國區域，但 `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 函數建立網路連接器，並透過連接器的子網路和安全群組路由函數的傳出流量。 ``` 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 ```