Transformasi masukan Amazon EventBridge Pipes

Amazon EventBridge Pipes mendukung transformator input opsional saat meneruskan data ke pengayaan dan target. Anda dapat menggunakan transformator Input untuk membentuk kembali payload input JSON acara untuk melayani kebutuhan pengayaan atau layanan target. Untuk Amazon API Gateway dan API tujuan, ini adalah bagaimana Anda membentuk acara input ke RESTful model AndaAPI. Transformator input dimodelkan sebagai parameter. InputTemplate Mereka dapat berupa teks gratis, JSON jalur ke payload acara, atau JSON objek yang menyertakan JSON jalur sebaris ke payload acara. Untuk pengayaan, muatan acara berasal dari sumbernya. Untuk target, muatan acara adalah apa yang dikembalikan dari pengayaan, jika ada yang dikonfigurasi pada pipa. Selain data khusus layanan dalam muatan acara, Anda dapat menggunakan variabel cadangan dalam data referensi InputTemplate untuk pipa Anda.

Untuk mengakses item dalam array, gunakan notasi braket persegi.

catatan

EventBridge tidak mendukung semua sintaks JSON Path dan mengevaluasinya saat runtime. Sintaks yang didukung meliputi:

• notasi titik (misalnya,$.detail)

• tanda hubung

• menggarisbawahi

• karakter alfanumerik

• indeks array

• wildcard (*)

Berikut ini adalah InputTemplate parameter sampel yang mereferensikan payload SQS acara Amazon:

String statis

InputTemplate: "Hello, sender"

JSONJalan

InputTemplate: <$.attributes.SenderId>

String dinamis

InputTemplate: "Hello, <$.attributes.SenderId>"

Statis JSON

InputTemplate: >
{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3",
}

Dinamis JSON

InputTemplate: >
{
  "key1": "value1"
  "key2": <$.body.key>,
  "d": <aws.pipes.event.ingestion-time>
}

Menggunakan notasi braket persegi untuk mengakses item dalam array:

InputTemplate: >
{
  "key1": "value1"
  "key2": <$.body.Records[3]>,
  "d": <aws.pipes.event.ingestion-time>
}

catatan

EventBridge menggantikan transformator input saat runtime untuk memastikan output yang valid. JSON Karena itu, letakkan tanda kutip di sekitar variabel yang merujuk ke parameter JSON jalur, tetapi jangan letakkan tanda kutip di sekitar variabel yang merujuk ke JSON objek atau array.

Variabel yang dicadangkan

Template masukan dapat menggunakan variabel cadangan berikut:

• <aws.pipes.pipe-arn>— Nama Sumber Daya Amazon (ARN) dari pipa.

• <aws.pipes.pipe-name>— Nama pipa.

• <aws.pipes.source-arn>— ARN Sumber acara pipa.

• <aws.pipes.enrichment-arn>— ARN Pengayaan pipa.

• <aws.pipes.target-arn>— Target pipa. ARN

• <aws.pipes.event.ingestion-time>— Waktu di mana acara diterima oleh transformator input. Ini adalah stempel ISO waktu 8601. Kali ini berbeda untuk trafo input pengayaan dan trafo input target, tergantung pada kapan pengayaan selesai memproses acara.

• <aws.pipes.event>— Acara yang diterima oleh transformator input.

  Untuk transformator input pengayaan, ini adalah acara dari sumbernya. Ini berisi muatan asli dari sumbernya, ditambah metadata khusus layanan tambahan. Lihat topik Sumber EventBridge Pipa Amazon untuk contoh khusus layanan.

  Untuk transformator input target, ini adalah peristiwa yang dikembalikan oleh pengayaan, jika dikonfigurasi, tanpa metadata tambahan. Dengan demikian, muatan yang dikembalikan pengayaan mungkin non-. JSON Jika tidak ada pengayaan yang dikonfigurasi pada pipa, ini adalah peristiwa dari sumber dengan metadata.

• <aws.pipes.event.json>— Sama sepertiaws.pipes.event, tetapi variabel hanya memiliki nilai jika muatan asli, baik dari sumber atau dikembalikan oleh pengayaan, adalah. JSON Jika pipa memiliki bidang yang dikodekan, seperti SQS body bidang Amazon atau Kinesisdata, bidang tersebut diterjemahkan dan diubah menjadi valid. JSON Karena tidak lolos, variabel hanya dapat digunakan sebagai nilai untuk JSON bidang. Untuk informasi selengkapnya, lihat Penguraian data tubuh implisit.

Contoh transformasi masukan

Berikut ini adalah contoh EC2 acara Amazon yang dapat kita gunakan sebagai contoh acara kita.

{
  "version": "0",
  "id": "7bf73129-1428-4cd3-a780-95db273d1602",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "123456789012",
  "time": "2015-11-11T21:29:54Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111"
  ],
  "detail": {
    "instance-id": "i-0123456789",
    "state": "RUNNING"
  }
}
		

Mari kita gunakan yang berikut ini JSON sebagai Transformer kita.

{
  "instance" : <$.detail.instance-id>,
  "state": <$.detail.state>,
  "pipeArn" : <aws.pipes.pipe-arn>,
  "pipeName" : <aws.pipes.pipe-name>,
  "originalEvent" : <aws.pipes.event.json>
}

Berikut ini akan menjadi Output yang dihasilkan:

{
  "instance" : "i-0123456789",
  "state": "RUNNING",
  "pipeArn" : "arn:aws:pipe:us-east-1:123456789012:pipe/example",
  "pipeName" : "example",
  "originalEvent" : {
    ... // commented for brevity
  }
}

Penguraian data tubuh implisit

Bidang berikut dalam payload masuk mungkin JSON -escaped, seperti SQS body objek Amazon, atau base64 yang dikodekan, seperti objek Kinesis. data Untuk penyaringan dan transformasi input, EventBridge mengubah bidang ini menjadi valid JSON sehingga sub-nilai dapat direferensikan secara langsung. Misalnya, <$.data.someKey> untuk Kinesis.

Agar target menerima muatan asli tanpa metadata tambahan, gunakan transformator input dengan data tubuh ini, khusus untuk sumbernya. Misalnya, <$.body> untuk AmazonSQS, atau <$.data> untuk Kinesis. Jika muatan asli adalah JSON string yang valid (misalnya{"key": "value"}), maka penggunaan transformator input dengan data badan spesifik sumber akan menghasilkan tanda kutip dalam muatan sumber asli dihapus. Misalnya, {"key": "value"} akan menjadi "{key: value}" ketika dikirim ke target. Jika target Anda memerlukan JSON muatan yang valid (misalnya, EventBridge Lambda atau Step Functions), ini akan menyebabkan kegagalan pengiriman. Agar target menerima data sumber asli tanpa menghasilkan tidak validJSON, bungkus transformator input data badan sumber. JSON Misalnya, {"data": <$.data>}.

Penguraian tubuh implisit juga dapat digunakan untuk mengisi nilai secara dinamis untuk sebagian besar target pipa atau parameter pengayaan. Untuk informasi selengkapnya, silakan lihat Parameter jalur dinamis

catatan

Jika payload asli validJSON, bidang ini akan berisi unescaped, non-base64-encoded. JSON Namun, jika payload tidak validJSON, EventBridge base64-mengkodekan bidang yang tercantum di bawah ini, dengan pengecualian Amazon. SQS

• MQ Aktif — data

• Kinesis — data

• Amazon MSK — key dan value

• MQ Kelinci — data

• Apache Kafka yang dikelola sendiri; — dan key value

• Amazon SQS — body

Masalah umum dengan mengubah input

Ini adalah beberapa masalah umum saat mengubah input dalam EventBridge pipa:

• Untuk String, tanda kutip diperlukan.

• Tidak ada validasi saat membuat JSON path untuk template Anda.

• Jika Anda menentukan variabel untuk mencocokkan JSON jalur yang tidak ada dalam acara tersebut, variabel tersebut tidak dibuat dan tidak akan muncul di output.

• JSONproperti seperti hanya aws.pipes.event.json dapat digunakan sebagai nilai JSON bidang, bukan sebaris di string lain.

• EventBridge tidak lolos dari nilai yang diekstraksi oleh Jalur Input, saat mengisi Template Input untuk target.

• Jika JSON jalur mereferensikan JSON objek atau array, tetapi variabel direferensikan dalam string, EventBridge menghapus tanda kutip internal untuk memastikan string yang valid. Misalnya, “Body is <$.body>” akan mengakibatkan EventBridge penghapusan tanda kutip dari objek.

  Oleh karena itu, jika Anda ingin menampilkan JSON objek berdasarkan variabel JSON jalur tunggal, Anda harus menempatkannya sebagai kunci. Dalam contoh ini,{"body": <$.body>}.

• Kutipan tidak diperlukan untuk variabel yang mewakili string. Mereka diizinkan, tetapi EventBridge Pipes secara otomatis menambahkan tanda kutip ke nilai variabel string selama transformasi, untuk memastikan output transformasi validJSON. EventBridge Pipa tidak menambahkan tanda kutip ke variabel yang mewakili JSON objek atau array. Jangan menambahkan tanda kutip untuk variabel yang mewakili JSON objek atau array.

  Misalnya, template input berikut mencakup variabel yang mewakili string dan JSON objek:

  {
    "pipeArn" : <aws.pipes.pipe-arn>,
    "pipeName" : <aws.pipes.pipe-name>,
    "originalEvent" : <aws.pipes.event.json>
  }

  Menghasilkan valid JSON dengan kutipan yang tepat:

  {
    "pipeArn" : "arn:aws:events:us-east-2:123456789012:pipe/example",
    "pipeName" : "example",
    "originalEvent" : {
      ... // commented for brevity
    }
  }

• Untuk pengayaan atau target Lambda atau Step Functions, batch dikirim ke target sebagai JSON array, meskipun ukuran batch adalah 1. Namun, transformator input masih akan diterapkan ke catatan individu di JSON Array, bukan array secara keseluruhan. Untuk informasi selengkapnya, lihat Pengelompokan dan konkurensi EventBridge Pipa Amazon.