EventBridge event transformation types - EventBridge - Centro de documentación de Alibaba Cloud

EventBridge transforma los eventos del formato estándar CloudEvents 1.0 a la estructura que espera su destino de evento. Configure un método de transformación en cada regla de evento para controlar qué datos llegan al destino: el evento completo, un solo campo extraído, una carga útil estática o una estructura personalizada ensamblada a partir de valores del evento.

Métodos de transformación

EventBridge ofrece cuatro métodos de transformación. Cada uno proporciona un nivel diferente de control sobre la carga útil del evento que se entrega al destino.

Método	Comportamiento	Cuándo utilizarlo
Complete Event	Entrega la carga útil completa de CloudEvents sin modificaciones	El destino admite CloudEvents de forma nativa
Partial Event	Extrae un único valor mediante una expresión JSONPath	El destino solo necesita un campo del evento
Constant	Entrega una cadena fija e ignora el contenido del evento	El evento funciona únicamente como activador y el destino requiere una carga útil estática
Template	Extrae varios valores con JSONPath y los ensambla en una cadena personalizada o estructura JSON	El destino exige un formato específico de carga útil

A continuación se presentan ejemplos basados en un evento de CloudEvents de muestra:

{
    "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

La carga útil completa de CloudEvents se entrega al destino tal cual. No se requiere ninguna configuración.

Salida:

{
    "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

Una única expresión JSONPath extrae un valor del evento.

Configuración:

$.data.name

Salida:

test

Notas de uso:

Solo se permite una expresión JSONPath por configuración de Partial Event.
El valor puede tener una longitud máxima de 10,240 caracteres.

Constant

Una cadena fija reemplaza la carga útil del evento. El evento en sí actúa exclusivamente como activador.

Configuración:

test1

Salida:

test1

Notas de uso:

El valor puede tener una longitud máxima de 10,240 caracteres.

Template

Template es el método más flexible y funciona en dos partes:

Variable: objeto JSON que asigna nombres de variables a expresiones JSONPath (o valores fijos). Cada expresión JSONPath extrae un valor del evento.
Plantilla: cadena o estructura JSON que referencia las variables mediante la sintaxis ${variableName}.

Configuración:

Variable:

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

Plantilla:

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

Salida:

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

Notas de uso:

Los valores de las variables pueden ser expresiones JSONPath o cadenas fijas.
No se admiten estructuras anidadas en las definiciones de variables.
El valor de la variable puede tener una longitud máxima de 10,240 caracteres.
El valor de la plantilla puede tener una longitud máxima de 10,240 caracteres.

Formatos de salida de plantillas

Las plantillas admiten cuatro formatos de salida: cadenas simples, JSON simple, JSON con variables y constantes combinadas, y JSON anidado. Los ejemplos de cadena simple, JSON simple y JSON con variables y constantes utilizan el mismo evento de muestra mostrado anteriormente, pero con "state": "RUNNING" en lugar de "scope": 100 en el campo data. El ejemplo de JSON anidado utiliza un evento de muestra diferente.

Cadena simple

Variable:

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

Plantilla:

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

Salida:

"name test is in RUNNING"

JSON simple

Variable:

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

Plantilla:

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

Salida:

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

JSON con variables y constantes

Combine valores extraídos con constantes fijas, arreglos y distintos tipos de datos en una sola plantilla.

Variable:

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

Plantilla:

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

Salida:

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

JSON anidado

Para transferir objetos o arreglos anidados desde el evento, referencie la variable sin comillas para que EventBridge inyecte la estructura JSON sin procesar.

El siguiente ejemplo utiliza un evento de muestra 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"
}

Plantilla (${Files} no lleva comillas porque referencia un arreglo):

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

Salida:

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

Nota

Utilice "${variableName}" (con comillas) cuando el valor extraído sea una cadena. Utilice ${variableName} (sin comillas) cuando sea un objeto JSON o un arreglo.

Funciones de escape

EventBridge proporciona dos funciones integradas para escapar caracteres especiales en las variables de plantilla: jsonEscape() y htmlEscape().

jsonEscape()

Escapa caracteres especiales en cadenas JSON para evitar que los caracteres incrustados rompan la estructura JSON.

Variable:

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

Plantilla:

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

Salida:

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

htmlEscape()

Escapa caracteres especiales de HTML para que se muestren como texto plano. Utilice esta función para prevenir la inyección de scripts cuando los datos del evento se insertan en una salida HTML.

Variable:

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

Plantilla:

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

Salida:

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

Límites

Elemento	Límite
Longitud del valor de Partial Event	Hasta 10,240 caracteres
Longitud del valor de Constant	Hasta 10,240 caracteres
Longitud del valor de variable de plantilla	Hasta 10,240 caracteres
Longitud del valor de plantilla	Hasta 10,240 caracteres
Variables de Partial Event por regla	1
Estructuras anidadas en definiciones de variables	No compatible

Problemas comunes

Problema	Causa	Solución
La salida JSON tiene un formato incorrecto	Se referencia una variable de cadena sin comillas, o se referencia una variable de objeto o arreglo con comillas	Utilice `"${var}"` para cadenas y `${var}` para objetos y arreglos
El valor de la variable aparece vacío en la salida	La expresión JSONPath no coincide con ningún campo del evento	Compruebe la expresión JSONPath con respecto a la estructura real del evento
Caracteres especiales dañan la salida JSON	El valor de la variable contiene caracteres como comillas dobles que entran en conflicto con la estructura JSON	Envuelva la referencia de la variable con `jsonEscape()`: `${jsonEscape(var)}`
El HTML renderiza scripts inyectados	Los datos del evento contienen HTML o JavaScript que no se escapó antes de insertarse	Envuelva la referencia de la variable con `htmlEscape()`: `${htmlEscape(var)}`