Formatar eventos recebidos

Um pipeline conecta um barramento a um destino de destino e encaminha mensagens de evento para esse destino. É possível configurar um pipeline para esperar dados de eventos em um formato específico ou, antes que os eventos sejam entregues a um destino, é possível converter dados de eventos de um formato compatível para outro. Por exemplo, talvez seja necessário encaminhar eventos para um endpoint que só aceita dados do Avro.

Formatos compatíveis

As seguintes conversões de formato são compatíveis:

  • Avro para JSON
  • Avro para Protobuf
  • JSON para Avro
  • JSON para Protobuf
  • Protobuf para Avro
  • Protobuf para JSON

Observe o seguinte:

  • Quando você converte o formato de eventos, somente o payload do evento é convertido, e não toda a mensagem do evento.

  • Se um formato de dados de entrada for especificado para um pipeline, todos os eventos precisarão corresponder a esse formato. Todos os eventos que não correspondem ao formato esperado são tratados como erros persistentes.

  • Se um formato de dados de entrada não for especificado para um pipeline, não será possível definir um formato de saída.

  • Antes que um formato de evento seja convertido para um destino específico, qualquer transformação de dados configurada é aplicada primeiro.

  • Os eventos são sempre entregues em um formato CloudEvents usando uma solicitação HTTP no modo de conteúdo binário, a menos que você especifique uma vinculação de mensagens.

  • Os esquemas JSON são detectados de forma dinâmica. Para definições de esquema do Protobuf, é possível definir apenas um tipo de nível superior, e as instruções de importação que se referem a outros tipos não são compatíveis. As definições de esquema sem um identificador syntax usam proto2 como padrão. Há um limite de tamanho do esquema.

Configurar um pipeline para formatar eventos

É possível configurar um pipeline para esperar dados de eventos em um formato específico ou converter dados de um formato para outro no console do Google Cloud ou usando a CLI gcloud.

Console

  1. No console do Google Cloud, acesse a página Eventarc > Pipelines.

    Acessar "Pipelines"

  2. Você pode criar um pipeline ou, se estiver atualizando um, clique no nome dele.

    A atualização de um pipeline pode levar mais de 10 minutos.

  3. Na página Detalhes do pipeline, clique em Editar.

  4. No painel Mediação de eventos, faça o seguinte:

    1. Marque a caixa de seleção Aplicar uma transformação.

    2. Na lista Formato de entrada, selecione o formato aplicável.

      Se um formato de dados de entrada for especificado para um pipeline, todos os eventos precisarão corresponder a esse formato. Todos os eventos que não correspondem ao formato esperado são tratados como erros persistentes.

    3. Para formatos Avro ou Protobuf, é necessário especificar um esquema de entrada. Como alternativa, em vez de especificar diretamente, você pode fazer upload de um esquema de entrada.

    4. No campo Expressão CEL, escreva uma expressão de transformação usando CEL.

    5. Clique em Continuar.

  5. No painel Destino, faça o seguinte:

    1. Se aplicável, selecione um formato na lista Formato de saída.

      Se um formato de dados de entrada não for especificado para um pipeline, não será possível definir um formato de saída.

    2. Opcional: aplique uma Vinculação de mensagens. Para mais informações, consulte Vinculação de mensagens.

  6. Clique em Salvar.

gcloud

  1. Abra um terminal.

  2. É possível criar um pipeline ou atualizar um usando o comando gcloud beta eventarc pipelines update:

    A atualização de um pipeline pode levar mais de 10 minutos.

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

    Substitua:

    • PIPELINE_NAME: o ID do pipeline ou um nome totalmente qualificado

    • REGION: um local do Eventarc Advanced compatível.

      Como alternativa, defina a propriedade de local da CLI gcloud:

      gcloud config set eventarc/location REGION

    • INPUT_PAYLOAD_FLAG: uma flag de formato de dados de entrada que pode ser um dos seguintes:

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

      Se um formato de dados de entrada for especificado para um pipeline, todos os eventos precisarão corresponder a esse formato. Todos os eventos que não correspondem ao formato esperado são tratados como erros persistentes.

    • OUTPUT_PAYLOAD_KEY: uma chave de formato de dados de saída que pode ser uma das seguintes:

      • output_payload_format_avro_schema_definition
      • output_payload_format_json
      • output_payload_format_protobuf_schema_definition

      Se você definir uma chave de formato de dados de saída, também precisará especificar uma flag de formato de dados de entrada.

    Exemplos:

    O exemplo a seguir usa uma flag --input-payload-format-protobuf-schema-definition para especificar que o pipeline deve esperar eventos em um formato de dados Protobuf com um esquema específico:

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

    O exemplo a seguir usa uma chave output_payload_format_avro_schema_definition e uma flag --input-payload-format-avro-schema-definition para criar um pipeline que espera eventos em um formato Avro e os gera no mesmo 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"}]}'

    O exemplo a seguir usa uma chave output_payload_format_protobuf_schema_definition e uma flag --input-payload-format-avro-schema-definition para atualizar um pipeline e converter os dados de evento de Avro para Protobuf usando definições de esquema:

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