Transformar eventos recebidos

É possível transformar os dados de eventos escrevendo expressões de transformação usando a CEL. Por exemplo, é possível modificar os payloads de eventos para atender a um contrato de API específico de um destino.

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.

Definir os formatos de dados de entrada e saída

Além de escrever uma expressão de transformação em CEL, você pode especificar o formato dos dados de eventos recebidos. Isso permite que o Eventarc Advanced saiba como analisar o payload do evento. Você também pode converter os dados de um formato para outro.

Os formatos compatíveis são Avro, JSON e Protobuf. Para mais informações, consulte Formatar eventos recebidos.

Expressões de transformação

Ao transformar eventos, todos os atributos podem ser acessados em uma expressão CEL como variáveis usando um objeto message predefinido. Essas variáveis são preenchidas com valores com base nos dados do evento no tempo de execução. Exemplo:

• message.id retorna o atributo id do evento.
• message.data retorna uma representação de valor CEL do payload do evento.
• message.data.some-key retorna o conteúdo de um campo chamado some-key do payload do evento.

Os campos em message.data são sempre representados como tipos String, e os valores são mapeados do evento original usando o esquema especificado ao definir o formato dos dados de entrada.

A expressão de transformação precisa expressar um evento completo que inclua os atributos de contexto e o payload de dados do evento. As expressões são escritas em JSON, mas as funções, macros e operadores CEL predefinidos, bem como as expressões regulares usando RE2, são compatíveis. O Eventarc Advanced também é compatível com algumas funções de extensão que podem ser usadas para transformar os dados de eventos.

A seguir, há dois exemplos de uso de expressões CEL para transformar seus dados de eventos. Para mais casos de uso e exemplos, consulte Exemplos de transformação.

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

Configurar um pipeline para transformar eventos

É possível configurar um pipeline para transformar dados de eventos no console do Google Cloud ou usando a CLI gcloud.

Apenas uma mediação por pipeline é aceita.

Funções de extensão

O Eventarc Advanced é compatível com as seguintes funções de extensão, que podem ser usadas para transformar os dados de eventos recebidos por um barramento.

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

Definir uma vinculação de mensagem

Por padrão, os eventos são sempre entregues a um destino em um formato CloudEvents usando uma solicitação HTTP no modo de conteúdo binário. Também é possível definir uma vinculação de mensagens e criar uma nova solicitação HTTP para modificar esse comportamento.

Todos os cabeçalhos HTTP introduzidos por outras políticas ou controles (por exemplo, tokens OAuth ou OIDC) são preservados e mesclados com os cabeçalhos resultantes da expressão de vinculação.

É possível definir uma vinculação de mensagem ao configurar um pipeline no console doGoogle Cloud ou usando a CLI gcloud.

Acessar mensagens recebidas

É possível usar uma expressão CEL para acessar uma mensagem CloudEvents de entrada da seguinte maneira:

• Use o valor message.data para acessar o campo data da mensagem de entrada.
• Use os valores message.key (em que key é o nome do atributo) para acessar os atributos da mensagem recebida.

• Use uma variável headers para acessar os cabeçalhos adicionados à solicitação HTTP por mediações anteriores na cadeia de processamento. Essa variável define um mapa de pares de chave-valor correspondentes aos cabeçalhos HTTP adicionais e não aos cabeçalhos originais da solicitação de entrada inicial.

  Por exemplo, a expressão CEL a seguir pode ser usada para construir uma solicitação HTTP somente de cabeçalhos adicionando um cabeçalho extra aos cabeçalhos adicionados em mediações de pipeline anteriores:

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

Criar solicitações HTTP

O resultado da expressão CEL precisa ser um mapa de pares de chave-valor em que os campos headers e body são usados para construir a solicitação HTTP da seguinte maneira.

Para campos headers:

• Se um mapa headers existir como resultado da expressão CEL, os pares chave-valor serão mapeados diretamente para os cabeçalhos de solicitação HTTP, e os valores serão construídos usando a codificação de string canônica do tipo de dados correspondente.
• Se um campo headers não existir, a solicitação HTTP resultante não vai conter nenhum cabeçalho.

Para campos body:

• Se um campo body existir como resultado da expressão CEL, o valor dele será mapeado diretamente para o corpo da solicitação HTTP.
• Se o valor do campo body for do tipo bytes ou string, ele será usado como o corpo da solicitação HTTP. Caso contrário, será convertido em uma string JSON.
• Se o campo body não existir, o corpo da solicitação HTTP resultante será o corpo da vinculação final da mensagem HTTP do CloudEvents no modo de conteúdo binário.

Todos os outros campos resultantes da expressão CEL são ignorados.

Funções de extensão

O Eventarc Advanced é compatível com as seguintes funções de extensão, que podem ser usadas para transformar os dados de eventos ao especificar uma vinculação de mensagem.

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

A seguir

• Formatar eventos recebidos
• Exemplos de transformação