EventBridge event transformation types - EventBridge: Central de Documentação do Alibaba Cloud

Métodos de transformação

O EventBridge oferece quatro métodos de transformação. Cada um proporciona um nível diferente de controle sobre o payload do evento entregue ao destino.

Método	Comportamento	Quando usar
Complete Event	Entrega o payload completo do CloudEvents sem alterações	O destino aceita CloudEvents nativamente
Partial Event	Extrai um único valor com uma expressão JSONPath	O destino precisa apenas de um campo do evento
Constant	Entrega uma string fixa e ignora o conteúdo do evento	O evento serve apenas como gatilho e o destino requer um payload estático
Template	Extrai múltiplos valores via JSONPath e os monta em uma string personalizada ou estrutura JSON	O destino exige um formato específico de payload

Os exemplos a seguir usam um evento CloudEvents de amostra:

{
    "id": "7adc8c1a-645d-4476-bdef-5d6fb57f****",
    "source": "acs.oss",
    "specversion": "1.0",
    "type": "oss:ObjectCreated:PostObject",
    "datacontenttype": "application/json",
    "dataschema": "http://example.com/test.json",
    "subject": "acs:oss:cn-hangzhou:1234567:xls-papk/game_apk/123.jpg",
    "time": "2020-08-17T16:04:46.149Asia/Shanghai",
    "aliyuneventbusname": "demo-bus",
    "aliyunregionid": "Shanghai",
    "data": {
        "name": "test",
        "scope": 100
    }
}

Complete Event

O EventBridge entrega o payload inteiro do CloudEvents ao destino exatamente como foi recebido. Não é necessária nenhuma configuração.

Saída:

{
    "id": "7adc8c1a-645d-4476-bdef-5d6fb57f****",
    "source": "acs.oss",
    "specversion": "1.0",
    "type": "oss:ObjectCreated:PostObject",
    "datacontenttype": "application/json",
    "dataschema": "http://example.com/test.json",
    "subject": "acs:oss:cn-hangzhou:1234567:xls-papk/game_apk/123.jpg",
    "time": "2020-08-17T16:04:46.149Asia/Shanghai",
    "aliyuneventbusname": "demo-bus",
    "aliyunregionid": "Shanghai",
    "data": {
        "name": "test",
        "scope": 100
    }
}

Partial Event

Uma única expressão JSONPath extrai um valor do evento.

Configuração:

$.data.name

Saída:

test

Observações de uso:

Apenas uma expressão JSONPath é permitida por configuração de Partial Event.
O valor pode ter até 10.240 caracteres.

Constant

Uma string fixa substitui o payload do evento. O evento funciona exclusivamente como gatilho.

Configuração:

test1

Saída:

test1

Observações de uso:

O valor pode ter até 10.240 caracteres.

Template

O método Template é o mais flexível e funciona em duas partes:

Variable — Um objeto JSON que mapeia nomes de variáveis para expressões JSONPath (ou valores fixos). Cada expressão JSONPath extrai um valor do evento.
Template — Uma string ou estrutura JSON que referencia as variáveis usando a sintaxe ${variableName}.

Configuração:

Variable:

{
    "name": "$.data.name",
    "constant": "Please deal with it timely."
}

Template:

The instance is broken, which name is ${name}, ${constant}

Saída:

The instance is broken, which name is test, Please deal with it timely.

Observações de uso:

Os valores das variáveis podem ser expressões JSONPath ou strings fixas.
As definições de variáveis não aceitam estruturas aninhadas.
O valor da variável pode ter até 10.240 caracteres.
O valor do template pode ter até 10.240 caracteres.

Formatos de saída do Template

Os templates aceitam quatro formatos de saída: strings simples, JSON simples, JSON com variáveis e constantes mistas e JSON aninhado. Os exemplos de string simples, JSON simples e JSON com variáveis e constantes usam o mesmo evento de amostra mostrado acima, mas com "state": "RUNNING" no lugar de "scope": 100 no campo data. O exemplo de JSON aninhado usa um evento de amostra diferente.

String simples

Variable:

{
    "name": "$.data.name",
    "state": "$.data.state"
}

Template:

"name ${name} is in ${state}"

Saída:

"name test is in RUNNING"

JSON simples

Variable:

{
    "name": "$.data.name",
    "state": "$.data.state"
}

Template:

{
    "name": "${name}",
    "state": "${state}"
}

Saída:

{
    "name": "test",
    "state": "RUNNING"
}

JSON com variáveis e constantes

Combine valores extraídos com constantes fixas, arrays e diferentes tipos de dados em um único template.

Variable:

{
    "name": "$.data.name",
    "state": "$.data.state"
}

Template:

{
    "name": "${name}",
    "state": [
        9,
        "${state}",
        true
    ],
    "Transformed": "Yes"
}

Saída:

{
    "name": "test",
    "state": [
        9,
        "RUNNING",
        true
    ],
    "Transformed": "Yes"
}

JSON aninhado

Para repassar objetos ou arrays aninhados do evento, referencie a variável sem aspas para que o EventBridge injete a estrutura JSON bruta.

O exemplo a seguir usa um evento de amostra diferente:

{
    "id": "45ef4dewdwe1-7c35-447a-bd93-fab****",
    "source": "acs.imm",
    "specversion": "1.0",
    "subject": "acs.imm:cn-hangzhou:123456789098****:215672",
    "time": "2020-11-19T21:04:41+08:00",
    "type": "imm:FileMeta:Index",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2020-11-19T21:04:42.179PRC",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "ProjectName": "test_project",
        "DatasetName": "test_dataset",
        "RequestId": "D2A3AE88-D17C-4CCC-B149-6651115C****",
        "StartTime": "2021-07-22T14:03:15.489885+08:00",
        "EndTime": "2021-07-22T14:05:15.489885+08:00",
        "Message": "InvalidParameter",
        "Success": false,
        "Files": [
            {
                "URI": "oss://bucket/file",
                "CustomId": "defaultId",
                "CustomLabels": {
                    "Key1": "Val1",
                    "Key2": "Val2"
                },
                "Error": "InternalError"
            }
        ]
    }
}

Variable:

{
    "ProjectName": "$.data.ProjectName",
    "Files": "$.data.Files"
}

Template (${Files} está sem aspas porque referencia um array):

{
    "ProjectName": "${ProjectName}",
    "Files": ${Files}
}

Saída:

{
    "ProjectName": "test_project",
    "Files": [
        {
            "URI": "oss://bucket/file",
            "CustomId": "defaultId",
            "CustomLabels": {
                "Key1": "Val1",
                "Key2": "Val2"
            },
            "Error": "InternalError"
        }
    ]
}

Nota

Use "${variableName}" (com aspas) quando o valor extraído for uma string. Use ${variableName} (sem aspas) quando for um objeto JSON ou array.

Funções de escape

O EventBridge fornece duas funções integradas para escapar caracteres especiais em variáveis de template: jsonEscape() e htmlEscape().

jsonEscape()

Escapa caracteres especiais em strings JSON para evitar que caracteres incorporados quebrem a estrutura JSON.

Variable:

{
    "var": "\"abc\""
}

Template:

{
    "text": "var is ${jsonEscape(var)}"
}

Saída:

{
    "text": "var is \"abc\""
}

htmlEscape()

Escapa caracteres especiais HTML para renderizá-los como texto simples. Use esta função para prevenir injeção de scripts ao incorporar dados de eventos em saídas HTML.

Variable:

{
    "var": "<script>alert('unsafe');</script>"
}

Template:

<p>User Input: ${htmlEscape(var)}</p>

Saída:

<p>User Input: &lt;script&gt;alert('unsafe');&lt;/script&gt;</p>

Limites

Item	Limite
Comprimento do valor no Partial Event	Até 10.240 caracteres
Comprimento do valor constante	Até 10.240 caracteres
Comprimento do valor da variável no Template	Até 10.240 caracteres
Comprimento do valor do Template	Até 10.240 caracteres
Variáveis de Partial Event por regra	1
Estruturas aninhadas em definições de variáveis	Não suportado

Problemas comuns

Problema	Causa	Solução
A saída JSON está malformada	Uma variável string foi referenciada sem aspas ou uma variável objeto/array foi referenciada com aspas	Use `"${var}"` para strings e `${var}` para objetos e arrays
O valor da variável está vazio na saída	A expressão JSONPath não corresponde a nenhum campo no evento	Verifique a expressão JSONPath em relação à estrutura real do evento
Caracteres especiais quebram a saída JSON	O valor da variável contém caracteres, como aspas duplas, que entram em conflito com a estrutura JSON	Envolva a referência da variável com `jsonEscape()`: `${jsonEscape(var)}`
O HTML renderiza scripts injetados	Os dados do evento contêm HTML ou JavaScript não escapado antes da incorporação	Envolva a referência da variável com `htmlEscape()`: `${htmlEscape(var)}`