CreateEventSourceMapping - AWS Lambda

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

CreateEventSourceMapping

建立事件來源和 AWS Lambda 函數間的映射。Lambda 會從事件來源讀取項目,並調用函數。

如需關於如何設定不同事件來源的詳細資訊,請參閱下列主題。

以下錯誤處理選項僅適用於串流來源 (DynamoDB 和 Kinesis):

  • BisectBatchOnFunctionError - 如果函數傳回錯誤,將批次分割為兩個並重試。

  • DestinationConfig - 將捨棄的記錄傳送到 Amazon SQS 佇列或 Amazon SNS 主題。

  • MaximumRecordAgeInSeconds - 捨棄超過指定存留期的記錄。預設值為無限 (-1)。設定為無限 (-1) 時,系統會重試失敗的記錄,直到記錄到期為止。

  • MaximumRetryAttempts - 在指定的重試次數之後捨棄記錄。預設值為無限 (-1)。設定為 infinite (-1) 時,系統會重試失敗的記錄,直到記錄到期為止。

  • ParallelizationFactor - 同時處理來自每個碎片的多個批次。

如需每個事件來源套用哪些組態參數的詳細資訊,請參閱下列主題。

請求語法

POST /2015-03-31/event-source-mappings/ HTTP/1.1 Content-type: application/json { "AmazonManagedKafkaEventSourceConfig": { "ConsumerGroupId": "string" }, "BatchSize": number, "BisectBatchOnFunctionError": boolean, "DestinationConfig": { "OnFailure": { "Destination": "string" }, "OnSuccess": { "Destination": "string" } }, "DocumentDBEventSourceConfig": { "CollectionName": "string", "DatabaseName": "string", "FullDocument": "string" }, "Enabled": boolean, "EventSourceArn": "string", "FilterCriteria": { "Filters": [ { "Pattern": "string" } ] }, "FunctionName": "string", "FunctionResponseTypes": [ "string" ], "MaximumBatchingWindowInSeconds": number, "MaximumRecordAgeInSeconds": number, "MaximumRetryAttempts": number, "ParallelizationFactor": number, "Queues": [ "string" ], "ScalingConfig": { "MaximumConcurrency": number }, "SelfManagedEventSource": { "Endpoints": { "string" : [ "string" ] } }, "SelfManagedKafkaEventSourceConfig": { "ConsumerGroupId": "string" }, "SourceAccessConfigurations": [ { "Type": "string", "URI": "string" } ], "StartingPosition": "string", "StartingPositionTimestamp": number, "Topics": [ "string" ], "TumblingWindowInSeconds": number }

URI 請求參數

請求不會使用任何 URI 參數。

請求主體

請求接受採用 JSON 格式的下列資料。

AmazonManagedKafkaEventSourceConfig

Amazon Managed Streaming for Apache Kafka (Amazon MSK) 事件來源的具體組態設定。

類型:AmazonManagedKafkaEventSourceConfig 物件

必要:否

BatchSize

Lambda 從串流或佇列中提取並傳送至函數的每個批次中的記錄數目上限。Lambda 會將批次中的所有記錄以單一呼叫形式傳送至函數,直到達到同步調用的承載限制 (6 MB)。

  • Amazon Kinesis - 預設值 100。上限為 10,000。

  • Amazon DynamoDB Streams - 預設值 100。上限為 10,000。

  • Amazon Simple Queue Service - 預設值 10。對於標準佇列,最大值為 10,000。對於 FIFO 隊列,最大值為 10。

  • Amazon Managed Streaming for Apache Kafka - 預設值 100。上限為 10,000。

  • 自我管理型 Apache Kafka - 預設值 100。上限為 10,000。

  • Amazon MQ (ActiveMQ 和 RabbitMQ) - 預設值 100。上限為 10,000。

  • DocumentDB:預設為 100。上限為 10,000。

類型:整數

有效範圍:最小值為 1。最大值為 10000。

必要:否

BisectBatchOnFunctionError

(僅限 Kinesis 和 DynamoDB Streams) 如果函數傳回錯誤,將批次分割為兩個並重試。

類型:布林值

必要:否

DestinationConfig

(僅限 Kinesis、DynamoDB Streams、Amazon MSK 和自我管理的 Kafka) 指定在 Lambda 處理過後事件目的地的組態物件。

類型:DestinationConfig 物件

必要:否

DocumentDBEventSourceConfig

DocumentDB 事件來源的具體組態設定。

類型:DocumentDBEventSourceConfig 物件

必要:否

Enabled

當為 true 時,則事件來源映射處於作用中狀態。當為 false 時,Lambda 會暫停輪詢與調用。

預設:True

類型:布林值

必要:否

EventSourceArn

事件來源的 Amazon Resource Name (ARN)。

  • Amazon Kinesis - 資料串流或串流取用者的 ARN。

  • Amazon DynamoDB Streams - 串流的 ARN。

  • Amazon Simple Queue Service - 佇列的 ARN。

  • Amazon Managed Streaming for Apache Kafka – 叢集的 ARN 或 VPC 連線的 ARN (適用於跨帳戶事件來源映射)。

  • Amazon MQ - 代理程式的 ARN。

  • Amazon DocumentDB:DocumentDB 變更串流的 ARN。

類型:String

模式:arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+-\d{1})?:(\d{12})?:(.*)

必要:否

FilterCriteria

定義篩選條件標準的物件,用於決定 Lambda 是否應該處理事件。如需詳細資訊,請參閱 Lambda 事件篩選

類型:FilterCriteria 物件

必要:否

FunctionName

Lambda 函數的名稱。

名稱格式
  • 函數名稱 - MyFunction

  • 函數 ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction

  • 版本或別名 ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction:PROD

  • 部分 ARN - 123456789012:function:MyFunction

長度限制條件僅會套用到完整的 ARN。若您僅指定函數名稱,則其長度限制為 64 個字元。

類型:字串

長度限制:長度下限為 1。長度上限為 140。

模式:(arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

必要:是

FunctionResponseTypes

(Kinesis、DynamoDB Streams 和 Amazon SQS) 套用至事件來源映射的目前回應類型列舉清單。

類型:字串陣列

陣列成員:項目數下限為 0。項目數上限為 1。

有效值:ReportBatchItemFailures

必要:否

MaximumBatchingWindowInSeconds

Lambda 調用函數之前收集記錄所花費的最長時間 (以秒為單位)。您可以將 MaximumBatchingWindowInSeconds 設定為從 0 秒到 300 秒之間的任意值,增量為秒。

如果事件來源是串流和 Amazon SQS,預設批次間隔為 0 秒。如果事件來源是 Amazon MSK、自主管理 Apache Kafka 、Amazon MQ 以及 DocumentDB,則預設批次間隔為 500 毫秒。請注意,因為您只能以秒為增量變更 MaximumBatchingWindowInSeconds,所以預設批次間隔一旦變更後就無法再恢復到 500 毫秒的預設值。要恢復預設批次間隔,必須建立新的事件來源映射。

相關設定:如果事件來源是串流和 Amazon SQS,將 BatchSize 設定為大於 10 的值時,必須將 MaximumBatchingWindowInSeconds 至少設定為 1。

類型:整數

有效範圍:最小值為 0。最大值為 300。

必要:否

MaximumRecordAgeInSeconds

(僅限 Kinesis 和 DynamoDB Streams) 捨棄超過指定存留期的記錄。預設值為無限 (-1)。

類型:整數

有效範圍:最小值為 -1。最大值為 604800。

必要:否

MaximumRetryAttempts

(僅限 Kinesis 和 DynamoDB Streams) 在指定的重試次數之後捨棄記錄。預設值為無限 (-1)。設定為 infinite (-1) 時,系統會重試失敗的記錄,直到記錄到期為止。

類型:整數

有效範圍:最小值為 -1。最大值為 10000。

必要:否

ParallelizationFactor

(僅限 Kinesis 和 DynamoDB Streams) 要從各個碎片同時處理的批次數。

類型:整數

有效範圍:最小值為 1。最大值為 10。

必要:否

Queues

(MQ) 要使用的 Amazon MQ 代理程式目的地佇列的名稱。

類型:字串陣列

陣列成員:固定項目數為 1。

長度限制:長度下限為 1。長度上限為 1000。

模式:[\s\S]*

必要:否

ScalingConfig

(僅限 Amazon SQS) 事件來源的擴展組態。如需詳細資訊,請參閱設定 Amazon SQS 事件來源的並行上限

類型:ScalingConfig 物件

必要:否

SelfManagedEventSource

用於接收記錄的自我管理 Apache Kafka 叢集。

類型:SelfManagedEventSource 物件

必要:否

SelfManagedKafkaEventSourceConfig

用於自我管理的 Apache Kafka 事件來源的具體組態設定。

類型:SelfManagedKafkaEventSourceConfig 物件

必要:否

SourceAccessConfigurations

保護事件來源所需的身分驗證協定或 VPC 元件。

類型:SourceAccessConfiguration 物件陣列

陣列成員:項目數下限為 0。項目數上限為 22。

必要:否

StartingPosition

要從中開始讀取的串流位置。Amazon Kinesis 和 Amazon DynamoDB Stream 事件來源所必需。Amazon Kinesis 串流、Amazon DocumentDB、Amazon MSK 以及自我管理的 Apache Kafka 僅支援 AT_TIMESTAMP

類型:字串

有效值:TRIM_HORIZON | LATEST | AT_TIMESTAMP

必要:否

StartingPositionTimestamp

StartingPosition 設定為 AT_TIMESTAMP,這是開始讀取的時間 (以 Unix 時間秒為單位)。StartingPositionTimestamp 不能為未來的時間。

類型:Timestamp

必要:否

Topics

Kafka 主題名稱。

類型:字串陣列

陣列成員:固定項目數為 1。

長度限制:長度下限為 1。長度上限為 249。

模式:^[^.]([a-zA-Z0-9\-_.]+)

必要:否

TumblingWindowInSeconds

(僅限 Kinesis 和 DynamoDB Streams) DynamoDB 和 Kinesis Streams 事件來源處理時段的持續時間 (以秒為單位)。值為 0 秒代表沒有輪轉時段。

類型:整數

有效範圍:最小值為 0。最大值為 900。

必要:否

回應語法

HTTP/1.1 202 Content-type: application/json { "AmazonManagedKafkaEventSourceConfig": { "ConsumerGroupId": "string" }, "BatchSize": number, "BisectBatchOnFunctionError": boolean, "DestinationConfig": { "OnFailure": { "Destination": "string" }, "OnSuccess": { "Destination": "string" } }, "DocumentDBEventSourceConfig": { "CollectionName": "string", "DatabaseName": "string", "FullDocument": "string" }, "EventSourceArn": "string", "FilterCriteria": { "Filters": [ { "Pattern": "string" } ] }, "FunctionArn": "string", "FunctionResponseTypes": [ "string" ], "LastModified": number, "LastProcessingResult": "string", "MaximumBatchingWindowInSeconds": number, "MaximumRecordAgeInSeconds": number, "MaximumRetryAttempts": number, "ParallelizationFactor": number, "Queues": [ "string" ], "ScalingConfig": { "MaximumConcurrency": number }, "SelfManagedEventSource": { "Endpoints": { "string" : [ "string" ] } }, "SelfManagedKafkaEventSourceConfig": { "ConsumerGroupId": "string" }, "SourceAccessConfigurations": [ { "Type": "string", "URI": "string" } ], "StartingPosition": "string", "StartingPositionTimestamp": number, "State": "string", "StateTransitionReason": "string", "Topics": [ "string" ], "TumblingWindowInSeconds": number, "UUID": "string" }

回應元素

如果動作成功,則服務傳回 HTTP 202 回應。

服務會傳回下列 JSON 格式的資料。

AmazonManagedKafkaEventSourceConfig

Amazon Managed Streaming for Apache Kafka (Amazon MSK) 事件來源的具體組態設定。

類型:AmazonManagedKafkaEventSourceConfig 物件

BatchSize

Lambda 從串流或佇列中提取並傳送至函數的每個批次中的記錄數目上限。Lambda 會將批次中的所有記錄以單一呼叫形式傳送至函數,直到達到同步調用的承載限制 (6 MB)。

預設值:依服務而異。對於 Amazon SQS,預設值為 10。對於所有其他服務,預設值為 100。

相關設定:當您將 BatchSize 設定為大於 10 的值時,必須將 MaximumBatchingWindowInSeconds 至少設定為 1。

類型:整數

有效範圍:最小值為 1。最大值為 10000。

BisectBatchOnFunctionError

(僅限 Kinesis 和 DynamoDB Streams) 如果函數傳回錯誤,將批次分割為兩個並重試。預設值為 false。

類型:布林值

DestinationConfig

(僅限 Kinesis、DynamoDB Streams、Amazon MSK 和自我管理的 Apache 卡夫卡事件來源) 一種組態物件,可在 Lambda 處理事件後指定事件的目的地。

類型:DestinationConfig 物件

DocumentDBEventSourceConfig

DocumentDB 事件來源的具體組態設定。

類型:DocumentDBEventSourceConfig 物件

EventSourceArn

事件來源的 Amazon Resource Name (ARN)。

類型:String

模式:arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+-\d{1})?:(\d{12})?:(.*)

FilterCriteria

定義篩選條件標準的物件,用於決定 Lambda 是否應該處理事件。如需詳細資訊,請參閱 Lambda 事件篩選

類型:FilterCriteria 物件

FunctionArn

Lambda 函數的 ARN。

類型:String

模式:arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?

FunctionResponseTypes

(Kinesis、DynamoDB Streams 和 Amazon SQS) 套用至事件來源映射的目前回應類型列舉清單。

類型:字串陣列

陣列成員:項目數下限為 0。項目數上限為 1。

有效值:ReportBatchItemFailures

LastModified

上次更新事件來源映射或其狀態變更的日期 (以 Unix 時間秒為單位)。

類型:Timestamp

LastProcessingResult

函數的最後一次 Lambda 調用的結果。

類型:字串

MaximumBatchingWindowInSeconds

Lambda 調用函數之前收集記錄所花費的最長時間 (以秒為單位)。您可以將 MaximumBatchingWindowInSeconds 設定為從 0 秒到 300 秒之間的任意值,增量為秒。

如果事件來源是串流和 Amazon SQS,預設批次間隔為 0 秒。如果事件來源是 Amazon MSK、自主管理 Apache Kafka 、Amazon MQ 以及 DocumentDB,則預設批次間隔為 500 毫秒。請注意,因為您只能以秒為增量變更 MaximumBatchingWindowInSeconds,所以預設批次間隔一旦變更後就無法再恢復到 500 毫秒的預設值。要恢復預設批次間隔,必須建立新的事件來源映射。

相關設定:如果事件來源是串流和 Amazon SQS,將 BatchSize 設定為大於 10 的值時,必須將 MaximumBatchingWindowInSeconds 至少設定為 1。

類型:整數

有效範圍:最小值為 0。最大值為 300。

MaximumRecordAgeInSeconds

(僅限 Kinesis 和 DynamoDB Streams) 捨棄超過指定存留期的記錄。預設值為 -1,這會將最大存留期設定為無限。當值設定為無限時,Lambda 永遠不會捨棄舊記錄。

注意

最大記錄保留期的最小有效值為 60 秒。雖然小於 60 且大於 -1 的值在參數的絕對範圍內,但不允許這些值

類型:整數

有效範圍:最小值為 -1。最大值為 604800。

MaximumRetryAttempts

(僅限 Kinesis 和 DynamoDB Streams) 在指定的重試次數之後捨棄記錄。預設值為 -1,這會將重試數上限設定為無限。如果 MaximumRetryAttempts 是無限的,Lambda 會重試失敗的記錄,直到事件來源中的記錄到期為止。

類型:整數

有效範圍:最小值為 -1。最大值為 10000。

ParallelizationFactor

(僅限 Kinesis 和 DynamoDB Streams) 要從每個碎片中同時處理的批次數。預設值為 1。

類型:整數

有效範圍:最小值為 1。最大值為 10。

Queues

(Amazon MQ) 要使用的 Amazon MQ 代理程式目的地佇列的名稱。

類型:字串陣列

陣列成員:固定項目數為 1。

長度限制:長度下限為 1。長度上限為 1000。

模式:[\s\S]*

ScalingConfig

(僅限 Amazon SQS) 事件來源的擴展組態。如需詳細資訊,請參閱設定 Amazon SQS 事件來源的並行上限

類型:ScalingConfig 物件

SelfManagedEventSource

用於事件來源的自我管理型 Apache Kafka 叢集。

類型:SelfManagedEventSource 物件

SelfManagedKafkaEventSourceConfig

用於自我管理的 Apache Kafka 事件來源的具體組態設定。

類型:SelfManagedKafkaEventSourceConfig 物件

SourceAccessConfigurations

保護和定義事件來源的身分驗證協定、VPC 元件或虛擬主機。

類型:SourceAccessConfiguration 物件陣列

陣列成員:項目數下限為 0。項目數上限為 22。

StartingPosition

要從中開始讀取的串流位置。Amazon Kinesis 和 Amazon DynamoDB Stream 事件來源所必需。Amazon Kinesis 串流、Amazon DocumentDB、Amazon MSK 以及自我管理的 Apache Kafka 僅支援 AT_TIMESTAMP

類型:字串

有效值:TRIM_HORIZON | LATEST | AT_TIMESTAMP

StartingPositionTimestamp

StartingPosition 設定為 AT_TIMESTAMP,這是開始讀取的時間 (以 Unix 時間秒為單位)。StartingPositionTimestamp 不能為未來的時間。

類型:Timestamp

State

事件來源映射的狀態。可為下列其中之一:CreatingEnablingEnabledDisablingDisabledUpdatingDeleting

類型:字串

StateTransitionReason

指出使用者或 Lambda 是否對事件來源映射進行最後的變更。

類型:字串

Topics

Kafka 主題名稱。

類型:字串陣列

陣列成員:固定項目數為 1。

長度限制:長度下限為 1。長度上限為 249。

模式:^[^.]([a-zA-Z0-9\-_.]+)

TumblingWindowInSeconds

(僅限 Kinesis 和 DynamoDB Streams) DynamoDB 和 Kinesis Streams 事件來源處理時段的持續時間 (以秒為單位)。值為 0 秒代表沒有輪轉時段。

類型:整數

有效範圍:最小值為 0。最大值為 900。

UUID

事件來源映射的識別符。

類型:字串

錯誤

如需所有動作常見錯誤的資訊,請參閱常見錯誤

InvalidParameterValueException

請求中的其中一個參數無效。

HTTP 狀態碼:400

ResourceConflictException

資源已存在,或另一個操作正在進行中。

HTTP 狀態碼:409

ResourceNotFoundException

請求中指定的資源不存在。

HTTP 狀態碼:404

ServiceException

AWS Lambda 服務發生內部錯誤。

HTTP 狀態碼:500

TooManyRequestsException

超出請求輸送量限制。如需詳細資訊,請參閱 Lambda 配額

HTTP 狀態碼:429

另請參閱

如需在語言特定的 AWS 開發套件之一中使用此 API 的詳細資訊,請參閱下列說明: