Trasforma gli eventi ricevuti

Puoi trasformare i dati degli eventi scrivendo espressioni di trasformazione utilizzando CEL. Ad esempio, puoi modificare i payload degli eventi in modo da soddisfare il contratto API specifico di una destinazione.

Tieni presente che gli eventi vengono sempre pubblicati in un formato CloudEvents utilizzando una richiesta HTTP in modalità di contenuti binari a meno che tu non specifichi un collegamento del messaggio.

Impostare i formati dei dati di input e output

Oltre a scrivere un'espressione di trasformazione in CEL, puoi specificare facoltativamente il formato dei dati degli eventi in entrata. In questo modo, Eventarc Advanced sa come analizzare il payload dell'evento. Puoi anche convertire i dati da un formato a un altro.

Sono supportati i seguenti formati: Avro, JSON e Protobuf. Per maggiori informazioni, vedi Formattare gli eventi ricevuti.

Espressioni di trasformazione

Quando trasformi gli eventi, puoi accedere a tutti gli attributi degli eventi in un'espressione CEL come variabili tramite un oggetto message predefinito. Queste variabili vengono compilate con valori basati sui dati sugli eventi in fase di runtime. Ad esempio:

• message.id restituisce l'attributo id dell'evento
• message.data restituisce una rappresentazione del valore CEL del payload dell'evento
• message.data.some-key restituisce il contenuto di un campo denominato some-key dal payload dell'evento

I campi in message.data sono sempre rappresentati come tipi String e i valori vengono mappati dall'evento originale utilizzando lo schema specificato durante l'impostazione del formato dei dati di input.

L'espressione di trasformazione deve esprimere un evento completo che includa gli attributi del contesto dell'evento e il payload dei dati sugli eventi. Le espressioni sono scritte in JSON, ma sono supportate funzioni, macro e operatori CEL predefiniti, nonché espressioni regolari che utilizzano RE2. Eventarc Advanced supporta anche alcune funzioni di estensione che possono essere utilizzate per trasformare i dati degli eventi.

Di seguito sono riportati due esempi di utilizzo delle espressioni CEL per trasformare i dati degli eventi. Per altri casi d'uso ed esempi, vedi Esempi di trasformazione.

  // 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})"
                      )
    )
  }

  // 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
              }
          )
    }
  }

Configurare una pipeline per trasformare gli eventi

Puoi configurare una pipeline per trasformare i dati degli eventi nella console Google Cloud o utilizzando gcloud CLI.

Tieni presente che è supportata una sola mediazione per pipeline.

Funzioni di estensione

Eventarc Advanced supporta le seguenti funzioni di estensione che possono essere utilizzate per trasformare i dati sugli eventi ricevuti tramite un bus.

// 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"
    }
  )
}

// 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())

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

Definisci un binding del messaggio

Per impostazione predefinita, gli eventi vengono sempre pubblicati in una destinazione in un formato CloudEvents utilizzando una richiesta HTTP in modalità di contenuti binari. Facoltativamente, puoi ignorare questo comportamento definendo un collegamento del messaggio e creando una nuova richiesta HTTP.

Tutte le intestazioni HTTP introdotte da altri criteri o controlli (ad esempio, token OAuth o OIDC) vengono conservate e unite alle intestazioni risultanti dall'espressione di binding.

Puoi definire un binding del messaggio quando configuri una pipeline nella consoleGoogle Cloud o utilizzando gcloud CLI.

Accedere ai messaggi in entrata

Puoi utilizzare un'espressione CEL per accedere a un messaggio CloudEvents in entrata nel seguente modo:

• Utilizza il valore message.data per accedere al campo data del messaggio in entrata.
• Utilizza i valori message.key (dove key è il nome dell'attributo) per accedere agli attributi del messaggio in entrata.

• Utilizza una variabile headers per accedere a qualsiasi intestazione aggiunta alla richiesta HTTP dalle mediazioni precedenti nella catena di elaborazione. Questa variabile definisce una mappa di coppie chiave-valore corrispondenti alle intestazioni HTTP aggiuntive e non alle intestazioni originali della richiesta in entrata iniziale.

  Ad esempio, la seguente espressione CEL può essere utilizzata per creare una richiesta HTTP solo con intestazioni aggiungendo un'intestazione aggiuntiva a quelle aggiunte nelle mediazioni della pipeline precedenti:

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

Creare richieste HTTP

Il risultato dell'espressione CEL deve essere una mappa di coppie chiave-valore i cui campi headers e body vengono utilizzati per creare la richiesta HTTP nel seguente modo.

Per i campi headers:

• Se esiste una mappa headers come risultato dell'espressione CEL, le coppie chiave-valore vengono mappate direttamente alle intestazioni di richiesta HTTP e i valori vengono costruiti utilizzando la codifica di stringa canonica del tipo di dati corrispondente.
• Se un campo headers non esiste, la richiesta HTTP risultante non conterrà alcuna intestazione.

Per i campi body:

• Se esiste un campo body come risultato dell'espressione CEL, il suo valore viene mappato direttamente al corpo della richiesta HTTP.
• Se il valore del campo body è di tipo bytes o string, viene utilizzato come corpo della richiesta HTTP così com'è; altrimenti, viene convertito in una stringa JSON.
• Se il campo body non esiste, il corpo della richiesta HTTP risultante è il corpo dell'associazione del messaggio HTTP CloudEvents finale in modalità di contenuti binari.

Eventuali altri campi risultanti dall'espressione CEL vengono ignorati.

Funzioni di estensione

Eventarc Advanced supporta le seguenti funzioni di estensione che possono essere utilizzate per trasformare i dati degli eventi quando viene specificato un binding del messaggio.

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

Passaggi successivi

• Formattare gli eventi ricevuti
• Esempi di trasformazione