Kontrol peristiwa mana yang dikirim Lambda ke fungsi Anda

Anda dapat menggunakan pemfilteran peristiwa untuk mengontrol rekaman mana dari aliran atau antrian yang dikirim Lambda ke fungsi Anda. Misalnya, Anda dapat menambahkan filter sehingga fungsi Anda hanya memproses SQS pesan Amazon yang berisi parameter data tertentu. Pemfilteran acara hanya berfungsi dengan pemetaan sumber peristiwa tertentu. Anda dapat menambahkan filter ke pemetaan sumber peristiwa untuk hal-hal berikut ini: Layanan AWS

Untuk informasi spesifik tentang pemfilteran dengan sumber peristiwa tertentu, lihatMenggunakan filter dengan berbeda Layanan AWS. Lambda tidak mendukung pemfilteran acara untuk Amazon DocumentDB.

Secara default, Anda dapat menentukan hingga lima filter berbeda untuk pemetaan sumber peristiwa tunggal. Filter Anda secara logis ORed bersama-sama. Jika rekaman dari sumber acara memenuhi satu atau beberapa filter Anda, Lambda menyertakan catatan di acara berikutnya yang dikirim ke fungsi Anda. Jika tidak ada filter Anda yang puas, Lambda membuang catatan tersebut.

Memahami dasar-dasar penyaringan acara

Objek filter criteria (FilterCriteria) adalah struktur yang terdiri dari daftar filter (Filters). Setiap filter adalah struktur yang mendefinisikan pola penyaringan peristiwa ()Pattern. Sebuah pola adalah representasi string dari aturan JSON filter. Struktur suatu FilterCriteria objek adalah sebagai berikut.

{
   "Filters": [
        {
            "Pattern": "{ \"Metadata1\": [ rule1 ], \"data\": { \"Data1\": [ rule2 ] }}"
        }
    ]
}

Untuk kejelasan tambahan, berikut adalah nilai filter yang Pattern diperluas secara polosJSON.

{
    "Metadata1": [ rule1 ],
    "data": {
        "Data1": [ rule2 ]
    }
}

Pola filter Anda dapat mencakup properti metadata, properti data, atau keduanya. Parameter metadata yang tersedia dan format parameter data bervariasi sesuai dengan Layanan AWS yang bertindak sebagai sumber peristiwa. Misalnya, misalkan pemetaan sumber peristiwa Anda menerima catatan berikut dari SQS antrian Amazon:

{
    "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
    "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
    "body": "{\n "City": "Seattle",\n "State": "WA",\n "Temperature": "46"\n}",
    "attributes": {
        "ApproximateReceiveCount": "1",
        "SentTimestamp": "1545082649183",
        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
        "ApproximateFirstReceiveTimestamp": "1545082649185"
    },
    "messageAttributes": {},
    "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
    "eventSource": "aws:sqs",
    "eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
    "awsRegion": "us-east-2"
}

Berbagai jenis sumber acara menggunakan nilai kunci yang berbeda untuk bidang datanya. Untuk memfilter properti data, pastikan Anda menggunakan kunci yang benar dalam pola filter Anda. Untuk daftar kunci pemfilteran data, dan untuk melihat contoh pola filter untuk setiap yang didukung Layanan AWS, lihat. Menggunakan filter dengan berbeda Layanan AWS

Pemfilteran acara dapat menangani penyaringan multi-levelJSON. Misalnya, perhatikan fragmen catatan berikut dari aliran DynamoDB:

"dynamodb": {
    "Keys": {
        "ID": {
            "S": "ABCD"
        }
        "Number": {
            "N": "1234"
    },
    ...
}

Misalkan Anda hanya ingin memproses catatan tersebut di mana nilai kunci sortir Number adalah 4567. Dalam hal ini, FilterCriteria objek Anda akan terlihat seperti ini:

{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\": { \"Keys\": { \"Number\": { \"N\": [ "4567" ] } } } }"
        }
    ]
}

Untuk kejelasan tambahan, berikut adalah nilai filter yang Pattern diperluas secara polosJSON.

{
    "dynamodb": {
        "Keys": {
            "Number": {
                "N": [ "4567" ]
                }
            }
        }
}

Menangani catatan yang tidak memenuhi kriteria filter

Cara Lambda menangani catatan yang tidak memenuhi kriteria filter Anda tergantung pada sumber acara.

Sintaks aturan filter

Untuk aturan filter, Lambda mendukung EventBridge aturan Amazon dan menggunakan sintaks yang sama seperti. EventBridge Untuk informasi selengkapnya, lihat pola EventBridge acara Amazon di Panduan EventBridge Pengguna Amazon.

Berikut ini adalah ringkasan dari semua operator perbandingan yang tersedia untuk pemfilteran peristiwa Lambda.

Perhatikan bahwa operator Exists hanya bekerja pada node daun di sumber acara AndaJSON. Itu tidak cocok dengan node perantara. Misalnya, dengan berikut iniJSON, pola filter tidak { "person": { "address": [ { "exists": true } ] } }" akan menemukan kecocokan karena "address" merupakan simpul perantara.

{
  "person": {
    "name": "John Doe",
    "age": 30,
    "address": {
      "street": "123 Main St",
      "city": "Anytown",
      "country": "USA"
    }
  }
}

Melampirkan kriteria filter ke pemetaan sumber peristiwa (konsol)

Ikuti langkah-langkah ini untuk membuat pemetaan sumber peristiwa baru dengan kriteria filter menggunakan konsol Lambda.

Saat Anda memasukkan kriteria filter menggunakan konsol, Anda hanya memasukkan pola filter dan tidak perlu memberikan tanda kutip Pattern kunci atau escape. Pada langkah 6 dari instruksi sebelumnya, { "Metadata" : [ 1, 2 ] } sesuai dengan yang berikut ini. FilterCriteria

{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

Setelah membuat pemetaan sumber acara di konsol, Anda dapat melihat format FilterCriteria dalam detail pemicu. Untuk lebih banyak contoh pembuatan filter acara menggunakan konsol, lihatMenggunakan filter dengan berbeda Layanan AWS.

Melampirkan kriteria filter ke pemetaan sumber peristiwa ()AWS CLI

Misalkan Anda ingin pemetaan sumber peristiwa memiliki yang berikut: FilterCriteria

{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

Untuk membuat pemetaan sumber peristiwa baru dengan kriteria filter ini menggunakan AWS Command Line Interface (AWS CLI), jalankan perintah berikut.

aws lambda create-event-source-mapping \
    --function-name my-function \
    --event-source-arn arn:aws:sqs:us-east-2:123456789012:my-queue \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

create-event-source-mappingPerintah ini membuat pemetaan sumber SQS peristiwa Amazon baru untuk fungsi my-function dengan yang ditentukanFilterCriteria.

Untuk menambahkan kriteria filter ini ke pemetaan sumber peristiwa yang ada, jalankan perintah berikut.

aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

Perhatikan bahwa untuk memperbarui pemetaan sumber peristiwa, Anda memerlukannyaUUID. Anda bisa mendapatkan UUID dari list-event-source-mappingspanggilan. Lambda juga mengembalikan UUID respons. create-event-source-mappingCLI

Untuk menghapus kriteria filter dari sumber peristiwa, Anda dapat menjalankan update-event-source-mappingperintah berikut dengan FilterCriteria objek kosong.

aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria "{}"

Untuk lebih banyak contoh pembuatan filter acara menggunakan AWS CLI, lihatMenggunakan filter dengan berbeda Layanan AWS.

Melampirkan kriteria filter ke pemetaan sumber peristiwa ()AWS SAM

Misalkan Anda ingin mengonfigurasi sumber acara AWS SAM untuk menggunakan kriteria filter berikut:

{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

Untuk menambahkan kriteria filter ini ke pemetaan sumber acara Anda, masukkan cuplikan berikut ke dalam YAML templat untuk sumber acara Anda.

FilterCriteria: 
  Filters: 
    - Pattern: '{"Metadata": [1, 2]}'

Untuk informasi selengkapnya tentang membuat dan mengonfigurasi AWS SAM templat untuk pemetaan sumber peristiwa, lihat EventSourcebagian Panduan AWS SAM Pengembang. Untuk lebih banyak contoh pembuatan filter acara menggunakan AWS SAM templat, lihatMenggunakan filter dengan berbeda Layanan AWS.

Enkripsi kriteria filter

Secara default, Lambda tidak mengenkripsi objek kriteria filter Anda. Untuk kasus penggunaan di mana Anda dapat menyertakan informasi sensitif dalam objek kriteria filter Anda, Anda dapat menggunakan KMSkunci Anda sendiri untuk mengenkripsinya.

Setelah mengenkripsi objek kriteria filter, Anda dapat melihat versi teks biasa menggunakan panggilan. GetEventSourceMappingAPI Anda harus memiliki kms:Decrypt izin untuk dapat berhasil melihat kriteria filter dalam teks biasa.

Anda dapat menentukan KMS kunci Anda sendiri melalui konsol,API/CLI, atau AWS CloudFormation.

Jika Anda menggunakan KMS kunci Anda sendiri, API operasi berikut harus diizinkan dalam kebijakan kunci:

Anda dapat menggunakan AWS CloudTrail untuk melacak AWS KMS permintaan yang dibuat Lambda atas nama Anda. Untuk contoh CloudTrail peristiwa, lihatMemantau kunci enkripsi Anda untuk Lambda.

Kami juga merekomendasikan menggunakan tombol kms:ViaServicekondisi untuk membatasi penggunaan KMS kunci untuk permintaan dari Lambda saja. Nilai kunci ini adalah kepala layanan Lambda regional ()lambda.AWS_region.amazonaws.com. Berikut ini adalah contoh kebijakan kunci yang memberikan semua izin yang relevan:

{
    "Version": "2012-10-17",
    "Id": "example-key-policy-1",
    "Statement": [
        {
            "Sid": "Allow Lambda to decrypt using the key",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.us-east-1.amazonaws.com"
            },
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "ArnEquals" : {
                    "aws:SourceArn": [
                        "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:<esm_uuid>"
                    ]
                },
                "StringEquals": {
                    "kms:EncryptionContext:aws:lambda:FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:test-function",
                    "kms:EncryptionContext:aws:lambda:EventSourceArn": "arn:aws:sqs:us-east-1:123456789012:test-queue"
                }
            }
        },
        {
            "Sid": "Allow actions by an AWS account on the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow use of the key to specific roles",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/ExampleRole"
            },
            "Action": [
                "kms:Decrypt",
                "kms:DescribeKey",
                "kms:GenerateDataKey"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals" : {
                    "kms:ViaService": "lambda.us-east-1.amazonaws.com"
                }
            }
        }
    ]
}

Untuk menggunakan KMS kunci Anda sendiri untuk mengenkripsi kriteria filter, Anda juga dapat menggunakan CreateEventSourceMapping AWS CLI perintah berikut. Tentukan KMS kunci ARN dengan --kms-key-arn bendera.

aws lambda create-event-source-mapping --function-name my-function \
    --maximum-batching-window-in-seconds 60 \
    --event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
    --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \
    --kms-key-arn arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

Jika Anda memiliki pemetaan sumber peristiwa yang ada, gunakan UpdateEventSourceMapping AWS CLI perintah sebagai gantinya. Tentukan KMS kunci ARN dengan --kms-key-arn bendera.

aws lambda update-event-source-mapping --function-name my-function \
    --maximum-batching-window-in-seconds 60 \
    --event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
    --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \
    --kms-key-arn arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

Operasi ini menimpa KMS kunci apa pun yang telah ditentukan sebelumnya. Jika Anda menentukan --kms-key-arn bendera bersama dengan argumen kosong, Lambda berhenti menggunakan KMS kunci Anda untuk mengenkripsi kriteria filter. Sebaliknya, Lambda default kembali menggunakan kunci milik Amazon.

Untuk menentukan KMS kunci Anda sendiri dalam AWS CloudFormation templat, gunakan KMSKeyArn properti jenis AWS::Lambda::EventSourceMapping sumber daya. Misalnya, Anda dapat menyisipkan cuplikan berikut ke dalam YAML template untuk sumber acara Anda.

MyEventSourceMapping:
  Type: AWS::Lambda::EventSourceMapping
  Properties:
    ...
    FilterCriteria:
      Filters:
        - Pattern: '{"a": [1, 2]}'
    KMSKeyArn: "arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599"
    ...

Untuk dapat melihat kriteria filter terenkripsi Anda dalam teks biasa dalam DeleteEventSourceMappingAPIpanggilan GetEventSourceMappingatau, Anda harus memiliki izin. kms:Decrypt

Mulai 6 Agustus 2024, FilterCriteria bidang tidak lagi muncul di AWS CloudTrail log dari CreateEventSourceMappingUpdateEventSourceMapping, dan DeleteEventSourceMappingAPImemanggil jika fungsi Anda tidak menggunakan pemfilteran peristiwa. Jika fungsi Anda menggunakan pemfilteran peristiwa, FilterCriteria bidang akan muncul sebagai empty ({}). Anda masih dapat melihat kriteria filter Anda dalam teks biasa dalam respons GetEventSourceMappingAPIpanggilan jika Anda memiliki kms:Decrypt izin untuk kunci yang benar. KMS

{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "AROA123456789EXAMPLE:userid1",
        "arn": "arn:aws:sts::123456789012:assumed-role/Example/example-role",
        "accountId": "123456789012",
        "accessKeyId": "ASIAIOSFODNN7EXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "AROA987654321EXAMPLE",
                "arn": "arn:aws:iam::123456789012:role/User1",
                "accountId": "123456789012",
                "userName": "User1"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2024-05-09T20:35:01Z",
                "mfaAuthenticated": "false"
            }
        },
        "invokedBy": "AWS Internal"
    },
    "eventTime": "2024-05-09T21:05:41Z",
    "eventSource": "lambda.amazonaws.com",
    "eventName": "CreateEventSourceMapping20150331",
    "awsRegion": "us-east-2",
    "sourceIPAddress": "AWS Internal",
    "userAgent": "AWS Internal",
    "requestParameters": {
        "eventSourceArn": "arn:aws:sqs:us-east-2:123456789012:example-queue",
        "functionName": "example-function",
        "enabled": true,
        "batchSize": 10,
        "filterCriteria": {},
        "kMSKeyArn": "arn:aws:kms:us-east-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "scalingConfig": {},
        "maximumBatchingWindowInSeconds": 0,
        "sourceAccessConfigurations": []
    },
    "responseElements": {
        "uUID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
        "batchSize": 10,
        "maximumBatchingWindowInSeconds": 0,
        "eventSourceArn": "arn:aws:sqs:us-east-2:123456789012:example-queue",
        "filterCriteria": {},
        "kMSKeyArn": "arn:aws:kms:us-east-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:example-function",
        "lastModified": "May 9, 2024, 9:05:41 PM",
        "state": "Creating",
        "stateTransitionReason": "USER_INITIATED",
        "functionResponseTypes": [],
        "eventSourceMappingArn": "arn:aws:lambda:us-east-2:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLEbbbbb"
    },
    "requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
    "eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "sessionCredentialFromConsole": "true"
}

Menggunakan filter dengan berbeda Layanan AWS

Berbagai jenis sumber acara menggunakan nilai kunci yang berbeda untuk bidang datanya. Untuk memfilter properti data, pastikan Anda menggunakan kunci yang benar dalam pola filter Anda. Tabel berikut memberikan kunci penyaringan untuk setiap didukung Layanan AWS.

Bagian berikut memberikan contoh pola filter untuk berbagai jenis sumber peristiwa. Mereka juga memberikan definisi format data masuk yang didukung dan format bodi pola filter untuk setiap layanan yang didukung.