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 pesan Amazon SQS yang berisi parameter data tertentu. Pemfilteran peristiwa hanya berfungsi dengan pemetaan sumber peristiwa tertentu. Anda dapat menambahkan filter ke pemetaan sumber peristiwa untuk hal berikut: Layanan AWS

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

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

Memahami dasar-dasar pemfilteran peristiwa

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

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

Untuk kejelasan tambahan, berikut adalah nilai filter yang Pattern diperluas dalam JSON biasa.

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

Pola filter Anda dapat menyertakan 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, pemetaan sumber peristiwa Anda menerima catatan berikut dari antrian Amazon SQS:

{
    "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 peristiwa menggunakan nilai kunci yang berbeda untuk bidang data mereka. 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 masing-masing yang didukung Layanan AWS, lihatMenggunakan filter dengan yang berbeda Layanan AWS.

Pemfilteran peristiwa dapat menangani pemfilteran JSON multi-level. Misalnya, pertimbangkan fragmen catatan berikut dari aliran DynamoDB:

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

Misalkan Anda ingin memproses hanya catatan di mana nilai kunci pengurutan 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 dalam JSON biasa.

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

Menangani catatan yang tidak memenuhi kriteria filter

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

Sintaks aturan filter

Untuk aturan filter, Lambda mendukung EventBridge aturan Amazon dan menggunakan sintaks yang sama seperti EventBridge. Untuk informasi selengkapnya, lihat pola EventBridge peristiwa 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 berfungsi pada node daun di JSON sumber acara Anda. Itu tidak cocok dengan node perantara. Misalnya, dengan JSON berikut, pola filter tidak { "person": { "address": [ { "exists": true } ] } }" akan menemukan kecocokan karena "address" merupakan node 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 ku Pattern tip kunci atau escape. Pada langkah 6 dari instruksi sebelumnya, { "Metadata" : [ 1, 2 ] } sesuai dengan yang berikut iniFilterCriteria.

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

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

Melampirkan kriteria filter ke pemetaan sumber peristiwa (AWS CLI)

Misalkan Anda ingin pemetaan sumber peristiwa memiliki yang berikutFilterCriteria:

{
   "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 ]}"}]}'

Perintah create-event-source-mapping ini membuat pemetaan sumber peristiwa Amazon SQS baru untuk fungsi dengan yang ditentukan. my-function FilterCriteria

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 memerlukan UUID-nya. Anda bisa mendapatkan UUID dari panggilan list-event-source-mappings. Lambda juga mengembalikan UUID dalam respons CLI create- event-source-mapping.

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

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

Untuk contoh lebih lanjut tentang membuat filter acara menggunakan AWS CLI, lihatMenggunakan filter dengan yang berbeda Layanan AWS.

Melampirkan kriteria filter ke pemetaan sumber peristiwa (AWS SAM)

Misalkan Anda ingin mengonfigurasi sumber peristiwa 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 template YAML untuk sumber acara Anda.

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

Untuk informasi selengkapnya tentang membuat dan mengonfigurasi AWS SAM template untuk pemetaan sumber peristiwa, lihat EventSource bagian Panduan Peng AWS SAM embang. Untuk lebih banyak contoh pembuatan filter acara menggunakan AWS SAM templat, lihatMenggunakan filter dengan yang berbeda Layanan AWS.

Enkripsi kriteria filter

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

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

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

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

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

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

Untuk menggunakan kunci KMS Anda sendiri untuk mengenkripsi kriteria filter, Anda juga dapat menggunakan CreateEventSourceMapping AWS CLI perintah berikut. Tentukan kunci KMS 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 kunci KMS 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 mengganti kunci KMS apa pun yang telah ditentukan sebelumnya. Jika Anda menentukan --kms-key-arn flag bersama dengan argumen kosong, Lambda berhenti menggunakan kunci KMS Anda untuk mengenkripsi kriteria filter. Sebagai gantinya, Lambda secara default kembali menggunakan kunci. Amazon-owned

Untuk menentukan kunci KMS Anda sendiri dalam CloudFormation template, gunakan KMSKeyArn properti jenis AWS::Lambda::EventSourceMapping sumber daya. Misalnya, Anda dapat menyisipkan cuplikan berikut ke dalam template YAML 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 panggilan GetEventSourceMapping atau DeleteEventSourceMapping API, Anda harus memiliki kms:Decrypt izin.

Mulai 6 Agustus 2024, FilterCriteria bidang tidak lagi muncul di AWS CloudTrail log dari CreateEventSourceMapping, UpdateEventSourceMapping, dan panggilan DeleteEventSourceMapping API 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 dalam teks biasa dalam respons panggilan GetEventSourceMapping API jika Anda memiliki kms:Decrypt izin untuk kunci KMS yang benar.

{
    "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 yang berbeda Layanan AWS

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

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