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。

重要

您的函數程式碼必須執行 HTTP 伺服器，以監聽AWS_LAMBDA_HTTP_ENDPOINT環境變數中的主機和連接埠。執行時間不會設定 PORT。根據預設，執行時間index.js會在部署套件的根目錄執行。使用 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 儲存貯體政策。

CodeUri 必須在 Amazon S3 中參考物件。sam build 和 sam package命令不支援此資源的本機路徑。

語法

若要在 AWS Serverless Application Model (AWS SAM) 範本中宣告此實體，請使用下列語法。

YAML


Type: AWS::Serverless::WebFunction
Properties:
  AuthType: String
  AutoDeploymentMode: String
  CodeUri: String | CodeUri
  EgressNetworkConnectorArn: String
  EndpointDescription: String
  EndpointName: String
  EndpointType: String
  EntryPoint: String
  EnvironmentVariables: Map
  ExecutionRoleArn: String
  FunctionName: String
  InlineCode: String
  KmsKeyArn: String
  LoggingConfig: Map
  MaxConcurrencyPerEnvironment: Integer
  ReplicaRegions: List | ReplicaRegions
  RevisionDescription: String
  RevisionWeights: RevisionWeights
  Runtime: String
  ScalingConfig: Map
  Tags: Map
  ThrottleConfig: Map
  Timeout: Integer

Properties

AuthType

端點如何授權請求。

IamAuth：Lambda 使用 Signature 第 4 版和 IAM 授權請求。呼叫者需要透過函數上的資源型政策授予的 lambda:InvokeWebFunctionEndpoint 許可。
ApplicationManaged：端點為公有。您的函數必須授權每個請求本身。

有效值：IamAuth、ApplicationManaged

類型：字串

必要：是

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionEndpoint 資源的 AuthType 屬性。

AutoDeploymentMode

端點如何跨修訂路由流量。

LatestRevision：會將 100% 的流量傳送至此部署建立的修訂版。
Disabled：根據 RevisionWeights 路由流量。

您可以使用哪些值，以及是否需要RevisionWeights，取決於 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

必要：是

CloudFormation 相容性：此屬性類似於 AWS::Lambda::WebFunctionRevision 資源的 BuildConfig.CodeConfig.S3Object 屬性。會將 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 必須是 WebFunction。

如果您指定常值字串，會 AWS SAM 檢查是否為符合版本資格的網路連接器 ARN。內部函數由服務傳遞和驗證。變更此值會建立新的修訂。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionRevision 資源的 ServiceConfig.EgressNetworkConnectorArn 屬性。

EndpointDescription

端點的描述。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionEndpoint 資源的 Description 屬性。

EndpointName

端點的名稱。變更名稱會取代端點。變更 EndpointType 也會取代端點，因此EndpointName請同時變更。如果沒有新名稱， CloudFormation 則無法取代自訂命名的資源。

類型：字串

必要：否

預設：prod

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionEndpoint 資源的 EndpointName 屬性。

EndpointType

端點提供流量的位置。

HomeRegion：從堆疊的區域提供服務。
MultiRegion：會將函數複寫至 ReplicaRegions 中的區域，並將每個請求路由至最近的區域。
PerRegion：在每個複本區域中公開個別的端點。

MultiRegion 和 PerRegion需要 AutoDeploymentMode: Disabled。

有效值：HomeRegion、MultiRegion、 PerRegion

類型：字串

必要：否

預設：HomeRegion

CloudFormation 相容性：此屬性會直接傳遞至 AWS::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 屬性。

ExecutionRoleArn

函數執行時所擔任之 IAM 角色的 ARN。如果您未指定角色，會 AWS SAM 建立一個具有 AWSLambdaBasicExecutionRole 受管政策且邏輯 ID 為的角色<resource-logical-id>Role。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionRevision 資源的 ServiceConfig.ExecutionRoleArn 屬性。

FunctionName

函數的名稱。函數名稱在所有區域中的帳戶內必須是唯一的。如果您未指定名稱，會從邏輯 ID 和堆疊 ID AWS SAM 產生名稱，最多 64 個字元。變更名稱會取代函數、其修訂版及其端點。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunction、 AWS::Lambda::WebFunctionRevision和 AWS::Lambda::WebFunctionEndpoint 資源的 FunctionName 屬性。

InlineCode

不支援 AWS::Serverless::WebFunction。使用 CodeUri。

類型：字串

必要：否

CloudFormation 相容性：此屬性對是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

KmsKeyArn

用於加密修訂環境變數之 AWS KMS 金鑰的 ARN。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionRevision 資源的 KmsKeyArn 屬性。

LoggingConfig

修訂版的記錄組態，例如日誌群組和日誌層級。

類型：映射

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionRevision 資源的 ServiceConfig.TelemetryConfig.LoggingConfig 屬性。

MaxConcurrencyPerEnvironment

每個執行環境處理的並行請求數目上限。

類型：整數

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionRevision 資源的 ServiceConfig.MaxConcurrencyPerEnvironment 屬性。

ReplicaRegions

要複寫函數的區域。將此屬性與 MultiRegion和 PerRegion端點搭配使用。指定區域代碼和區域群組的清單，或具有 IncludeRegions和選用的物件ExcludeRegions。

類型：List | ReplicaRegions

必要：否

CloudFormation 相容性：此屬性類似於 AWS::Lambda::WebFunctionEndpoint resource. AWS SAM expands 區域群組的 Regions 屬性，並適用於ExcludeRegions產生區域清單。

RevisionDescription

此部署建立之修訂的描述。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionRevision 資源的 Description 屬性。

RevisionWeights

修訂 IDs 到流量權重的映射。當 AutoDeploymentMode為時，使用此屬性Disabled。指定最多兩個修訂。每個權重是從 1 到 100 的整數，且權重最多必須加到 100。

類型：RevisionWeights

必要：有條件限制。當 AutoDeploymentMode為 Disabled且 EndpointType為時為必要HomeRegion。

CloudFormation 相容性：此屬性類似於 AWS::Lambda::WebFunctionEndpoint resource. AWS SAM convert the map to a list of RevisionId和 Weight 物件的 RevisionWeights 屬性。

Runtime

函數的執行時間，例如 nodejs24.x。

類型：字串

必要：是

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionRevision 資源的 BuildConfig.RuntimeConfig.Runtime 屬性。

ScalingConfig

端點的擴展組態，例如執行環境的最大數量。

類型：映射

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionEndpoint 資源的 ScalingConfig 屬性。

Tags

索引鍵/值對的映射，指定新增至函數和 AWS SAM 產生的執行角色的標籤。

類型：映射

必要：否

CloudFormation 相容性：此屬性類似於 AWS::Lambda::WebFunction 資源的 Tags 屬性。中的 Tags AWS SAM 屬性包含鍵值對（而 CloudFormation 此屬性包含Tag物件清單）。此外， AWS SAM 會自動將lambda:createdBy:SAM標籤新增至函數，以及為其產生的預設角色。

ThrottleConfig

端點的限流組態，例如請求率上限。

類型：映射

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionEndpoint 資源的 ThrottleConfig 屬性。

Timeout

函數可依請求執行的時間上限，以秒為單位。有效值為 3 到 900。

類型：整數

必要：否

預設：30

CloudFormation 相容性：此屬性會直接傳遞至 AWS::Lambda::WebFunctionRevision 資源的 ServiceConfig.TimeoutSeconds 屬性。

傳回值

Ref

當將此資源的邏輯 ID 提供給Ref內部函數時，它會傳回 Web 函數的 ARN。如果您需要函數名稱，請FunctionName改用的值。

如需使用 Ref函數的詳細資訊，請參閱AWS CloudFormation 《使用者指南Ref》中的。

Fn::GetAtt

Fn::GetAtt 會傳回此類型之指定屬性的值。以下為可用屬性及傳回值的範例。

如需使用的詳細資訊Fn::GetAtt，請參閱AWS CloudFormation 《使用者指南Fn::GetAtt》中的。

FunctionArn: Web 函數的 Amazon Resource Name (ARN)。
State: Web 函數的目前狀態。
StateReason: Web 函數目前狀態的原因。
CreatedAt: Web 函數建立的時間。
UpdatedAt: Web 函數上次更新的時間。

若要參考 AWS SAM 產生的修訂或端點，請使用其邏輯 IDs <resource-logical-id>Revision和 <resource-logical-id>Endpoint。例如，會!GetAtt MyWebFunctionEndpoint.DomainName傳回邏輯 ID 為之 Web 函數的端點網域名稱MyWebFunction。如需詳細資訊，請參閱CloudFormation 指定 AWS::Serverless::WebFunction 時產生的資源。

範例

基本 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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

ScheduleV2

CodeUri