Halaman ini diterjemahkan oleh Cloud Translation API.

Mengubah peristiwa yang diterima

Lanjutan

Anda dapat mengubah data peristiwa dengan menulis ekspresi transformasi menggunakan CEL. Misalnya, Anda dapat mengubah payload peristiwa untuk memenuhi kontrak API tertentu di tujuan.

Perhatikan bahwa peristiwa selalu dikirim dalam format CloudEvents menggunakan permintaan HTTP dalam mode konten biner, kecuali jika Anda menentukan binding pesan.

Menetapkan format data input dan output

Selain menulis ekspresi transformasi di CEL, Anda dapat secara opsional menentukan format data dari data peristiwa yang masuk. Hal ini memungkinkan Eventarc Advanced mengetahui cara mengurai payload peristiwa. Anda juga dapat mengonversi data dari satu format ke format lainnya.

Format berikut didukung: Avro, JSON, dan Protobuf. Untuk mengetahui informasi selengkapnya, lihat Memformat peristiwa yang diterima.

Ekspresi transformasi

Saat mengubah peristiwa, semua atribut peristiwa dapat diakses dalam ekspresi CEL sebagai variabel melalui objek message yang telah ditentukan sebelumnya. Variabel ini diisi dengan nilai berdasarkan data peristiwa saat runtime. Contoh:

message.id menampilkan atribut id peristiwa
message.data menampilkan representasi nilai CEL dari payload peristiwa
message.data.some-key menampilkan konten kolom bernama some-key dari payload peristiwa

Kolom di message.data selalu direpresentasikan sebagai jenis String dan nilainya dipetakan dari peristiwa asli menggunakan skema yang ditentukan saat menetapkan format data input.

Ekspresi transformasi harus menyatakan peristiwa lengkap yang menyertakan atribut konteks peristiwa dan payload data peristiwa. Ekspresi ditulis dalam JSON, tetapi fungsi, makro, dan operator CEL standar, serta ekspresi reguler menggunakan RE2 didukung. Eventarc Advanced juga mendukung fungsi ekstensi tertentu yang dapat digunakan untuk mengubah data peristiwa.

Berikut adalah dua contoh penggunaan ekspresi CEL untuk mengubah data peristiwa Anda. Untuk mengetahui kasus penggunaan dan contoh lainnya, lihat Contoh transformasi.

Contoh: Memformat nilai atribut

Contoh berikut memformat nilai atribut phone_number menggunakan fungsi ekspresi reguler. (Atribut lainnya telah dihilangkan.)

  // Input:
  // {
  //   "data":
  //   {
  //     "email_address": "charlie@altostrat.com",
  //     "phone_number": "8005550100",
  //   }
  // }
  // Output:
  // {
  //    "data":
  //    {
  //      "email_domain": "altostrat.com",
  //      "phone_number": "(800) 555-0100",
  //      "area_code": "800",
  //      "local_number": "5550100",
  //    }
  // }

  {
    "data":
    {
      "email_domain": re.capture(
                        message.data.email_address,
                        "\\S+@(\\S+)"),

      "phone_number": re.extract(
                        message.data.phone_number,
                        "^(\\d{3})(\\d{3})(\\d{4})", "(\\1) \\2-\\3"
                      ),

    }.merge ( re.captureN(message.data.phone_number,
                        "^(?P\d{3})[\w\-)(]*(?P\d{7})"
                      )
    )
  }

Berikut adalah fungsi ekspresi reguler yang digunakan dalam contoh sebelumnya:

re.capture: mengambil nilai grup pertama yang tidak bernama atau bernama. Argumennya adalah sebagai berikut:
- target: string yang harus diuraikan
- regex: ekspresi reguler yang digunakan untuk mengambil nilai
Menampilkan string dari nilai grup pertama yang diambil.
re.captureN: melakukan pencocokan penuh pada string dan ekspresi reguler yang diberikan. Argumennya adalah sebagai berikut:
- target: string yang harus diuraikan
- regex: ekspresi reguler yang digunakan untuk mengambil nilai
Menampilkan peta dengan pasangan kunci dan nilai untuk grup bernama (nama grup, string yang diambil) atau grup tanpa nama (indeks grup, string yang diambil).
re.extract: mencocokkan nilai grup dari string target yang diberikan dan menulis ulang string. Argumennya adalah sebagai berikut:
- target: string yang harus diuraikan
- regex: ekspresi reguler yang digunakan untuk mengekstrak nilai
- rewrite: ekspresi reguler untuk cara memformat hasil
Menampilkan string nilai yang diekstrak yang diformat berdasarkan argumen rewrite.

Contoh: Memetakan array ke array objek

Contoh berikut memetakan array bilangan bulat ke dalam array objek. (Atribut lainnya telah dihilangkan.)

  // Input:
  // {
  //   "data":
  //   {
  //        "product_ids": [1, 2, 3]
  //   }
  // }
  // Output:
  // {
  //    "data":
  //    {
  //             "products": [
  //                {
  //                   "name": "apple",
  //                   "price": 70
  //                },
  //                {
  //                    "name": "orange",
  //                    "price":  80
  //                },
  //                {
  //                    "name": "Product(3)",
  //                    "price": 0
  //                },
  //                {
  //                     "name": "apple",
  //                     "price": 70
  //                }
  //            ]
  //    }
  // }

  {
    "data":
    {
      "products":  message.data.product_ids.map(product_id,
              product_id == 1?
              {
                "name": "apple",
                "price": 70
              } :
              product_id == 2?
              {
                "name": "orange",
                "price":  80
              } :
              // Default:
              {
                "name": "Product(" + string(product_id) + ")",
                "price": 0
              }
          )
    }
  }

Mengonfigurasi pipeline untuk mengubah peristiwa

Anda dapat mengonfigurasi pipeline untuk mengubah data peristiwa di Konsol Google Cloud atau menggunakan gcloud CLI.

Perhatikan bahwa hanya satu mediasi per pipeline yang didukung.

Konsol

Di konsol Google Cloud, buka halaman Eventarc > Pipelines.

Buka Pipeline
Anda dapat membuat pipeline atau, jika Anda mengupdate pipeline, klik nama pipeline.

Perhatikan bahwa mengupdate pipeline mungkin memerlukan waktu lebih dari 10 menit.
Di halaman Detail pipeline, klik Edit.
Di panel Mediasi peristiwa, lakukan hal berikut:
1. Centang kotak Terapkan transformasi.
2. Dalam daftar Format masuk, pilih format yang berlaku.
  
  Untuk informasi selengkapnya, lihat Memformat peristiwa yang diterima.
3. Di kolom CEL expression, tulis ekspresi transformasi dalam JSON. Fungsi, makro, dan operator CEL yang telah ditetapkan, serta ekspresi reguler didukung. Contoh:
```
{
"id": message.id,
"datacontenttype": "application/json",
"data": "{ \"scrubbed\": \"true\" }"
}
```
  Contoh sebelumnya melakukan hal berikut:
  - Menghapus semua atribut dari peristiwa asli kecuali id-nya
  - Menetapkan atribut datacontenttype ke application/json
  - Mengganti payload peristiwa dengan string JSON statis
4. Klik Lanjutkan.
Di panel Destination, lakukan hal berikut:
1. Jika berlaku, di daftar Format keluar, pilih format.
  
  Untuk informasi selengkapnya, lihat Memformat peristiwa yang diterima.
2. Secara opsional, terapkan Penautan pesan. Untuk informasi selengkapnya, lihat bagian Menentukan binding pesan dalam dokumen ini.
Klik Simpan.

gcloud

Buka terminal.
Anda dapat membuat pipeline atau memperbarui pipeline menggunakan perintah gcloud beta eventarc pipelines update:

Perhatikan bahwa mengupdate pipeline mungkin memerlukan waktu lebih dari 10 menit.
```
gcloud beta eventarc pipelines update PIPELINE_NAME \
    --location=REGION \
    --mediations=transformation_template= \
{
  TRANSFORMATION_EXPRESSION
}
```
Ganti kode berikut:
- PIPELINE_NAME: ID pipeline atau nama yang sepenuhnya memenuhi syarat
- REGION: Lokasi Eventarc Advanced yang didukung
  
  Atau, Anda dapat menetapkan properti lokasi gcloud CLI:
```
gcloud config set eventarc/location REGION
```
- TRANSFORMATION_EXPRESSION: ekspresi yang ditulis dalam JSON. Fungsi, makro, dan operator CEL yang telah ditetapkan, serta ekspresi reguler didukung. Flag mediations digunakan untuk menerapkan kunci transformation_template.
Contoh:
```
gcloud beta eventarc pipelines update my-pipeline \
    --location=us-central1 \
    --mediations=transformation_template= \
{
"id": message.id,
"datacontenttype": "application/json",
"data": "{ \"scrubbed\": \"true\" }"
}
```
Contoh sebelumnya melakukan hal berikut:
- Menghapus semua atribut dari peristiwa asli kecuali id-nya
- Menetapkan atribut datacontenttype ke application/json
- Mengganti payload peristiwa dengan string JSON statis

Fungsi ekstensi

Eventarc Advanced mendukung fungsi ekstensi berikut yang dapat digunakan untuk mengubah data peristiwa yang diterima melalui bus.

Fungsi	Deskripsi
`denormalize`	Mendenormalisasi peta atau daftar dengan menambahkan data redundan untuk meningkatkan performa pembacaan. Nama kolom dalam peta yang dihasilkan dipisahkan menggunakan titik (`.`). Indeks daftar dikonversi menjadi kunci string, mulai dari `0`. Perhatikan bahwa karena Anda tidak dapat menggunakan titik (`.`) dalam nama kolom Avro dan Protobuf, hanya gunakan fungsi ini untuk menargetkan data JSON. Misalnya: `map.() -> map(string, dyn)` atau `list() -> map(string, dyn)`
`merge`	Menggabungkan dua kolom dan menampilkan kolom gabungan. Kolom dengan nama duplikat digabungkan. Misalnya: `message.(message) -> message`
`removeFields`	Menghapus kolom tertentu dari peristiwa. Nama kolom di-resolve sebagai jalur. Karakter titik (`.`) digunakan sebagai pembatas. Perhatikan bahwa JSON mentah diharapkan. Jika Anda melakukan marshalling JSON, transformasi dapat diterapkan ke string JSON dan menyebabkan error. Contoh: `message.(list(string)) -> message`
`setField`	Menambahkan atau mengganti kolom peristiwa dengan kunci yang diberikan. Nama kolom di-resolve sebagai jalur. Karakter titik (`.`) digunakan sebagai pembatas. Contoh: `message.(string, dyn) -> message`

Contoh: Menambahkan atribut ke payload peristiwa tanpa mengubah data lain

// Input:
// {
//   "data": 
//   {
//        "credit_card_number": "XXXX-XXXX-XXXX-XXXX"
//   }
// }
// Output:
// {
//    "data":
//    {
//        "credit_card_number": "XXXX-XXXX-XXXX-XXXX",
//        "card_type": "credit"
//    }
// }
{
  "data": message.data.merge(
    {
      "card_type": "credit"
    }
  )
}

Contoh: Mendenormalisasi daftar item dari payload peristiwa

// Input:
//{
//"data": 
//   {
//        "products": [
//          {
//            "number": 021774,
//            "type": "perishable",
//            "price": 2.00
//          },
//          {
//            "number": 95602,
//            "type": "diy",
//            "price": 120.00
//          },
//          {
//            "number": 568302,
//            "type": "toys",
//            "price": 12.00
//          }
//        ]
//   }
//}
//
// Output:
//{
//"data":
//    {
//        "products": {
//            "0.number": 021774,
//            "0.type": "perishable",
//            "0.price": 2.00,
//            "1.number": 95602,
//            "1.type": "diy",
//            "1.price": 120.00,
//            "2.number": 568302,
//            "2.type": "toys",
//            "2.price": 12.00
//          }
//   }
//}
//
//
message.setField("data.products", message.data.products.denormalize())

Contoh: Menghapus kolom dari payload peristiwa

// Input:
// {
//   "data": 
//   {
//     "payment": {
//       "card_number": "XXXX-XXXX-XXXX-XXXX",
//       "card_type": "credit",
//     }
//   }
// }
// Output:
// {
//   "data":
//   {
//     "payment": {
//       "card_type": "credit"
//     }
//   }
// }
message.removeFields(["data.payment.card_number"])

Menentukan binding pesan

Secara default, peristiwa selalu dikirim ke tujuan dalam format CloudEvents menggunakan permintaan HTTP dalam mode konten biner. Atau, Anda dapat mengganti perilaku ini dengan menentukan binding pesan dan membuat permintaan HTTP baru.

Setiap header HTTP yang diperkenalkan oleh kebijakan atau kontrol lain (misalnya, token OAuth atau OIDC) akan dipertahankan dan digabungkan dengan header yang dihasilkan dari ekspresi binding.

Anda dapat menentukan binding pesan saat mengonfigurasi pipeline di Konsol Google Cloud atau menggunakan gcloud CLI.

Konsol

Di konsol Google Cloud, buka halaman Eventarc > Pipelines.

Buka Pipeline
Anda dapat membuat pipeline atau, jika Anda mengupdate pipeline, klik nama pipeline.

Perhatikan bahwa mengupdate pipeline mungkin memerlukan waktu lebih dari 10 menit.
Di halaman Detail pipeline, klik Edit.
Di panel Destination, terapkan Message binding yang merupakan ekspresi CEL yang ditulis dalam JSON. Hal ini menghasilkan permintaan HTTP yang baru dibuat yang kemudian dikirim ke tujuan pipeline.

Untuk mengetahui informasi selengkapnya, lihat bagian Mengakses pesan masuk dan Membuat permintaan HTTP dalam dokumen ini.
Klik Simpan.

gcloud

Buka terminal.
Anda dapat membuat pipeline atau memperbarui pipeline menggunakan perintah gcloud beta eventarc pipelines update:
```
gcloud beta eventarc pipelines update PIPELINE_NAME \
    --location=REGION \
    --destinations=http_endpoint_message_binding_template='MESSAGE_BINDING'
```
Ganti kode berikut:
- PIPELINE_NAME: ID pipeline atau nama yang sepenuhnya memenuhi syarat
- REGION: Lokasi Eventarc Advanced yang didukung
  
  Atau, Anda dapat menetapkan properti lokasi gcloud CLI:
```
gcloud config set eventarc/location REGION
```
- MESSAGE_BINDING: ekspresi CEL yang ditulis dalam JSON yang menghasilkan permintaan HTTP yang baru dibuat, yang kemudian dikirim ke tujuan pipeline.
  
  Untuk informasi selengkapnya, lihat bagian Mengakses pesan masuk dan Membuat permintaan HTTP dalam dokumen ini.
Contoh:
```
gcloud beta eventarc pipelines create my-pipeline \
    --location=us-central1 \
    --destinations=http_endpoint_uri='https://example-endpoint.com',network_attachment=my-network-attachment, \
http_endpoint_message_binding_template='{"headers":{"new-header-key": "new-header-value"}}'
```
Perhatikan bahwa jika menggunakan kunci http_endpoint_message_binding_template, Anda juga harus menetapkan kunci http_endpoint_uri dan network_attachment.

Mengakses pesan masuk

Anda dapat menggunakan ekspresi CEL untuk mengakses pesan CloudEvents masuk sebagai berikut:

Gunakan nilai message.data untuk mengakses kolom data pesan masuk.
Gunakan nilai message.key (dengan key adalah nama atribut) untuk mengakses atribut pesan masuk.
Gunakan variabel headers untuk mengakses header apa pun yang ditambahkan ke permintaan HTTP oleh mediasi sebelumnya dalam rantai pemrosesan. Variabel ini menentukan peta pasangan nilai kunci yang sesuai dengan header HTTP tambahan, bukan dengan header asli dari permintaan masuk awal.

Misalnya, ekspresi CEL berikut dapat digunakan untuk membuat permintaan HTTP khusus header dengan menambahkan header tambahan ke header yang ditambahkan dalam mediasi pipeline sebelumnya:

{"headers": headers.merge({"new-header-key": "new-header-value"})}

Membuat permintaan HTTP

Hasil ekspresi CEL harus berupa peta pasangan nilai kunci yang kolom headers dan body-nya digunakan untuk membuat permintaan HTTP sebagai berikut.

Untuk kolom headers:

Jika peta headers ada sebagai hasil dari ekspresi CEL, pasangan nilai kuncinya akan dipetakan langsung ke header permintaan HTTP, dan nilainya akan dibuat menggunakan enkode string kanonis dari jenis data yang sesuai.
Jika kolom headers tidak ada, permintaan HTTP yang dihasilkan tidak akan berisi header apa pun.

Untuk kolom body:

Jika kolom body ada sebagai hasil dari ekspresi CEL, nilainya akan langsung dipetakan ke isi permintaan HTTP.
Jika nilai kolom body berjenis bytes atau string, nilai tersebut akan digunakan sebagai isi permintaan HTTP apa adanya; jika tidak, nilai tersebut akan dikonversi menjadi string JSON.
Jika kolom body tidak ada, isi permintaan HTTP yang dihasilkan adalah isi binding pesan HTTP CloudEvents akhir dalam mode konten biner.

Kolom lain sebagai hasil dari ekspresi CEL akan diabaikan.

Fungsi ekstensi

Eventarc Advanced mendukung fungsi ekstensi berikut yang dapat digunakan untuk mengubah data peristiwa saat menentukan binding pesan.

Fungsi	Deskripsi
`merge`	Menggabungkan peta CEL yang diteruskan ke peta CEL tempat fungsi diterapkan. Jika kunci yang sama ada di kedua peta, atau jika nilai kunci adalah jenis `map`, kedua peta akan digabungkan; jika tidak, nilai dari peta yang diteruskan akan digunakan. Contoh: `map1.merge(map2) -> map3`
`toBase64`	Mengonversi nilai CEL ke string yang dienkode URL base64. Contoh: `map.toBase64() -> string`
`toCloudEventJsonWithPayloadFormat`	Mengonversi pesan ke peta CEL yang sesuai dengan representasi JSON pesan CloudEvents, dan menerapkan `toDestinationPayloadFormat` ke data pesan. Juga menetapkan `datacontenttype` peristiwa ke format keluar yang ditentukan (`output_payload_format_*`). Jika format keluar tidak ditetapkan, `datacontenttype` yang ada akan digunakan; jika tidak, `datacontenttype` tidak ditetapkan. Jika pesan tidak mematuhi spesifikasi CloudEvents, fungsi akan gagal. Perhatikan bahwa untuk mengonversi data ke string JSON, Anda dapat menggunakan `toJsonString`. Contoh: `message.toCloudEventJsonWithPayloadFormat() -> map.toJsonString() -> string`
`toDestinationPayloadFormat`	Mengonversi `message.data` ke format keluar yang ditentukan (`output_payload_format_*`). Jika format keluar tidak ditetapkan, `message.data` akan ditampilkan tanpa perubahan. Contoh: `message.data.toDestinationPayloadFormat() -> string or bytes`
`toJsonString`	Mengonversi nilai CEL menjadi string JSON. Misalnya: `map.toJsonString() -> string`
`toMap`	Mengonversi daftar CEL peta CEL menjadi satu peta CEL. Contoh: `list(map).toMap() -> map`

Contoh: Mempertahankan header, menambahkan header baru, menetapkan isi ke format tujuan

gcloud beta eventarc pipelines create my-pipeline \
    --location=us-central1 \
    --input-payload-format-json='{}' \
    --destinations=http_endpoint_uri='https://example-endpoint.com',network_attachment=my-network-attachment,http_endpoint_message_binding_template='{"headers": headers.merge({"content-type":"application/avro"}), "body": message.data.toDestinationPayloadFormat()"}',output_payload_format_avro_schema_definition='{"schema_definition": "{"type":"record","name":"myrecord","fields":[{"name":"name","type":"string"},{"name":"account_late","type":"boolean"}]}"}'

Mengubah peristiwa yang diterima

Menetapkan format data input dan output

Ekspresi transformasi

Contoh: Memformat nilai atribut

Contoh: Memetakan array ke array objek

Mengonfigurasi pipeline untuk mengubah peristiwa

Konsol

gcloud

Fungsi ekstensi

Contoh: Menambahkan atribut ke payload peristiwa tanpa mengubah data lain

Contoh: Mendenormalisasi daftar item dari payload peristiwa

Contoh: Menghapus kolom dari payload peristiwa

Menentukan binding pesan

Konsol

gcloud

Mengakses pesan masuk

Membuat permintaan HTTP

Fungsi ekstensi

Contoh: Mempertahankan header, menambahkan header baru, menetapkan isi ke format tujuan

Langkah berikutnya