Formattare gli eventi ricevuti

Una pipeline collega un bus a una destinazione target e instrada i messaggi di evento a quella destinazione. Puoi configurare una pipeline in modo che preveda dati sugli eventi in un formato specifico oppure, prima che gli eventi vengano inviati a una destinazione, puoi convertire i dati sugli eventi da un formato supportato a un altro. Ad esempio, potresti dover inoltrare gli eventi a un endpoint che accetta solo dati Avro.

Formati supportati

Sono supportate le seguenti conversioni di formato:

  • Avro to JSON
  • Da Avro a Protobuf
  • Da JSON ad Avro
  • JSON to Protobuf
  • Da Protobuf ad Avro
  • Protobuf to JSON

Tieni presente quanto segue:

  • Quando converti il formato degli eventi, viene convertito solo il payload dell'evento e non l'intero messaggio dell'evento.

  • Se per una pipeline è specificato un formato di dati in entrata, tutti gli eventi devono corrispondere a quel formato. Eventuali eventi che non corrispondono al formato previsto vengono trattati come errori permanenti.

  • Se per una pipeline non è specificato un formato dei dati in entrata, non è possibile impostare un formato in uscita.

  • Prima che un formato di evento venga convertito per una destinazione specifica, viene applicata qualsiasi trasformazione dei dati configurata.

  • Gli eventi vengono sempre pubblicati in un formato CloudEvents utilizzando una richiesta HTTP in modalità di contenuti binari a meno che non specifichi una associazione di messaggi.

  • Gli schemi JSON vengono rilevati dinamicamente. Per le definizioni dello schema protobuf, puoi definire un solo tipo di primo livello e le istruzioni di importazione che fanno riferimento ad altri tipi non sono supportate. Per le definizioni dello schema senza un identificatore syntax, viene utilizzato per impostazione predefinita proto2. Tieni presente che esiste un limite di dimensioni dello schema.

Configurare una pipeline per formattare gli eventi

Puoi configurare una pipeline in modo che preveda dati sugli eventi in un formato specifico o per convertire i dati sugli eventi da un formato all'altro nella console Google Cloud o utilizzando il gcloud CLI.

Console

  1. Nella console Google Cloud, vai alla pagina Eventarc > Pipeline.

    Vai a Pipeline

  2. Puoi creare una pipeline o, se stai aggiornando una pipeline, fai clic sul nome della pipeline.

    Tieni presente che l'aggiornamento di una pipeline potrebbe richiedere più di 10 minuti.

  3. Nella pagina Dettagli della pipeline, fai clic su Modifica.

  4. Nel riquadro Mediazione eventi, segui questi passaggi:

    1. Seleziona la casella di controllo Applica una trasformazione.

    2. Nell'elenco Formato in entrata, seleziona il formato applicabile.

      Tieni presente che se per una pipeline è specificato un formato dei dati in entrata, tutti gli eventi devono corrispondere a quel formato. Tutti gli eventi che non corrispondono al formato previsto vengono trattati come errori permanenti.

    3. Per i formati Avro o Protobuf, devi specificare uno schema in entrata. Se vuoi, anziché specificarlo direttamente, puoi caricare uno schema di importazione.

    4. Nel campo Espressione CEL, scrivi un'espressione di trasformazione utilizzando CEL.

    5. Fai clic su Continua.

  5. Nel riquadro Destinazione, segui questi passaggi:

    1. Se applicabile, seleziona un formato nell'elenco Formato in uscita.

      Tieni presente che se per una pipeline non è specificato un formato dei dati in entrata, non è possibile impostare un formato in uscita.

    2. (Facoltativo) Applica una associazione messaggio. Per ulteriori informazioni, consulta la sezione Associazione dei messaggi.

  6. Fai clic su Salva.

gcloud

  1. Apri un terminale.

  2. Puoi creare una pipeline o aggiornarla utilizzando il comando gcloud beta eventarc pipelines update:

    Tieni presente che l'aggiornamento di una pipeline potrebbe richiedere più di 10 minuti.

    gcloud beta eventarc pipelines update PIPELINE_NAME \
    --location=REGION \
    --INPUT_PAYLOAD_FLAG \
    --destinations=OUTPUT_PAYLOAD_KEY

    Sostituisci quanto segue:

    • PIPELINE_NAME: l'ID della pipeline o un nome completamente qualificato

    • REGION: un'ubicazione Eventarc Advanced supportata

      In alternativa, puoi impostare la proprietà della posizione gcloud CLI:

      gcloud config set eventarc/location REGION

    • INPUT_PAYLOAD_FLAG: un flag per il formato dei dati di input che può essere uno dei seguenti:

      • --input-payload-format-avro-schema-definition
      • --input-payload-format-json
      • --input-payload-format-protobuf-schema-definition

      Tieni presente che se per una pipeline è specificato un formato dei dati di input, tutti gli eventi devono corrispondere a quel formato. Tutti gli eventi che non corrispondono al formato previsto vengono trattati come errori permanenti.

    • OUTPUT_PAYLOAD_KEY: una chiave del formato dei dati di output che può essere una delle seguenti:

      • output_payload_format_avro_schema_definition
      • output_payload_format_json
      • output_payload_format_protobuf_schema_definition

      Tieni presente che se imposti una chiave del formato dei dati di output, devi anche specificare un flag del formato dei dati di input.

    Esempi:

    L'esempio seguente utilizza un --input-payload-format-protobuf-schema-definition flag per specificare che la pipeline deve attendere eventi in un formato di dati Protobuf con uno schema specifico:

    gcloud beta eventarc pipelines update my-pipeline \
    --input-payload-format-protobuf-schema-definition \
'
  syntax = "proto3";
  message schema {
    string name = 1;
    string severity = 2;
  }
'

    L'esempio seguente utilizza una chiave output_payload_format_avro_schema_definition e un flag --input-payload-format-avro-schema-definition per creare una pipeline che si aspetta eventi in formato Avro e li estrae nello stesso formato:

    gcloud beta eventarc pipelines create my-pipeline \
    --location=us-central1 \
    --destinations=http_endpoint_uri='https://example-endpoint.com',output_payload_format_avro_schema_definition='{"type": "record", "name": "my_record", "fields": [{"name": "my_field", "type": "string"}]}' \
    --input-payload-format-avro-schema-definition='{"type": "record", "name": "my_record", "fields": [{"name": "my_field", "type": "string"}]}'

    L'esempio seguente utilizza una chiave output_payload_format_protobuf_schema_definition e un flag --input-payload-format-avro-schema-definition per aggiornare una pipeline e convertire i relativi dati sugli eventi da Avro a Protobuf utilizzando le definizioni dello schema:

    gcloud beta eventarc pipelines update my-pipeline \
    --location=us-central1 \
    --destinations=output_payload_format_protobuf_schema_definition='message MessageProto {string prop1 = 1; string prop2 = 2;}' \
    --input-payload-format-avro-schema-definition= \
    '
    {
      "type": "record",
      "name": "MessageProto",
      "fields": [
        { "name" : "prop1", "type": "string" },
        { "name" : "prop2", "type": "string" },
      ]
    }
    '