Desarrolla transformadores personalizados

Compatible con:

Puedes crear funciones de transformación y operadores lógicos personalizados basados en Python directamente en el IDE y usarlos en tus guías para casos de uso complejos y versátiles.

Paquetes de extensión

Un paquete de extensión es un tipo de integración especializado diseñado para actuar como contenedor de funciones de transformación y operadores lógicos personalizados. A diferencia de las integraciones estándar, los paquetes de extensión no requieren configuración de instancias y se pueden crear directamente desde el IDE.

Prácticas recomendadas para paquetes de extensión

  • Consolidación: Crea un paquete de extensión principal y agrégale varias funciones de transformación u operadores lógicos.
  • Separación: Crea un paquete de extensión nuevo cuando necesites un conjunto diferente de bibliotecas de Python (dependencias) que puedan entrar en conflicto con el paquete principal.

Crea un paquete de extensión

Para crear un paquete de extensión nuevo, sigue estos pasos:

  1. Ve a Respuesta > IDE.
  2. Haz clic en add Crear elemento nuevo.
  3. Selecciona Paquete de extensión en el menú desplegable.
  4. Proporciona un nombre único para el paquete de extensión.
  5. Haz clic en Guardar.

Sube dependencias

Al igual que las integraciones estándar, los paquetes de extensión se ejecutan en un entorno virtual en el que puedes administrar bibliotecas de Python.

Para administrar tus bibliotecas, sigue estos pasos:

  1. Abre la configuración del paquete de extensión en el IDE.
  2. Agrega las bibliotecas de Python requeridas desde PyPi o súbelas desde tu computadora.

Estas dependencias están disponibles para todos los transformadores y operadores lógicos que contiene este paquete de extensión específico.

Importar y exportar

Puedes importar y exportar paquetes de extensión de forma manual directamente en la interfaz del IDE.

Transformadores personalizados

Los transformadores personalizados son funciones de Python definidas por el usuario que extienden las funciones precompiladas en el Generador de expresiones. Puedes crearlos directamente en el IDE para extraer y manipular datos, y se pueden usar junto con las funciones integradas existentes.

Crea un transformador personalizado

Para definir un nuevo transformador personalizado, sigue estos pasos:

  1. En el IDE, ubica el paquete de extensión de destino.
  2. Selecciona el paquete de extensión de destino para agregar un elemento nuevo en el paquete.
  3. Selecciona Función de transformación personalizada.
  4. Asígnale un nombre.
  5. Opcional: agrega una descripción. Esta se muestra cuando colocas el cursor sobre el transformador personalizado en el Generador de expresiones.
  6. Define la lógica de la secuencia de comandos con Python. Puedes usar la plantilla predeterminada proporcionada como punto de partida.
    • La secuencia de comandos debe incluir una función main, como se muestra en la plantilla predefinida.
    • La secuencia de comandos debe mostrar un resultado al generador de expresiones con la función end del SDK.
    • La entrada del transformador personalizado puede ser de diferentes tipos (por ejemplo, cadena o lista). Asegúrate de convertirla al tipo esperado type en tu main función.
    • Solo puedes usar un subconjunto de los métodos del SDK en el IDE para transformadores:
      • transformer.extract_param("ParamName"): Para recuperar valores de entrada.
      • transformer.LOGGER: Para escribir registros para la depuración.
      • transformer.end(result): Para mostrar el valor transformado.
  7. Crea parámetros:
    • Cada función de transformador personalizado incluye un parámetro Input predeterminado. Este parámetro representa los datos de entrada, que es el marcador de posición al que se aplica la función. No puedes borrar este parámetro.
    • Además, puedes agregar parámetros opcionales para usarlos en tu función.
  8. Documentación (opcional): Define la documentación en el producto para el Generador de expresiones:
    • Entrada esperada: Describe el tipo de datos que la función espera recibir para este transformador (por ejemplo, "Cadena" o "Lista de cadenas").
    • Salida esperada: Describe el tipo de datos que la función espera mostrar para este transformador (por ejemplo, "booleano").
    • Ejemplo de uso: Proporciona un ejemplo de cómo invocar la función (por ejemplo, if_empty("new_value")).

Puedes probar la lógica de tu función de transformación personalizada directamente en el IDE antes de usarla en una guía. Esto te permite verificar que tu secuencia de comandos de Python controle correctamente varios tipos y parámetros de entrada, y que muestre los resultados esperados.

Tiempo de espera

  • Tiempo de espera predeterminado: 1 minuto
  • Tiempo de espera máximo: 3 minutos

Usa transformadores personalizados en el Generador de expresiones

Una vez guardados, los transformadores personalizados aparecen en la lista de funciones del Generador de expresiones junto con las funciones integradas. Se identifican con el formato ExtensionPackName.TransformerName. Si colocas el cursor sobre la función, se muestra la documentación generada a partir de las descripciones de los parámetros.

Compatibilidad con todos los marcadores de posición (JSON y no JSON)

El Generador de expresiones admite todos los marcadores de posición expuestos en el Diseñador de guías, incluidos los resultados no JSON.

Para los marcadores de posición no JSON:

  • Puedes ingresar datos de muestra de forma manual en el Generador de expresiones para probar la lógica con varios tipos de entrada: cadena, lista (valores separados por comas), y JSON.
  • Las pruebas con un tipo de entrada no garantizan que el marcador de posición muestre ese tipo específico en el tiempo de ejecución.
  • La mayoría de los marcadores de posición se resuelven como cadenas, excepto los tipos específicos que se resuelven como una cadena o una lista según su cantidad (por ejemplo, entity.identifier). Para estos, se recomienda tratar siempre la entrada como una lista.

Manejo de errores

Si una función de transformación personalizada encuentra un error durante la ejecución, falla la acción de la guía que usa ese transformador. El mensaje de error específico que genera la secuencia de comandos de Python se muestra en la pantalla dentro de la vista de ejecución de la guía, lo que te permite solucionar problemas de la lógica directamente.

Operadores lógicos personalizados

Los operadores lógicos personalizados te permiten definir tu propia lógica booleana para comparar valores.

Crea un operador lógico personalizado

Para definir un nuevo operador lógico, sigue estos pasos:

  1. En el IDE, ubica el paquete de extensión de destino.
  2. Selecciona Operador lógico personalizado.
  3. Asígnale un nombre.
  4. Opcional: Agrega una descripción para el menú de operadores lógicos en el Diseñador de guías.
  5. Define la lógica de la secuencia de comandos con Python. Puedes usar la plantilla predefinida proporcionada como punto de partida.
    • La secuencia de comandos debe incluir una función main.
    • La secuencia de comandos debe mostrar un resultado booleano a la condición con la función end del SDK.
    • Solo puedes usar un subconjunto de los métodos del SDK en el IDE para operadores lógicos:
      • logical_operator.extract_param("ParamName"): Para recuperar valores de entrada.
      • logical_operator.LOGGER: Para escribir registros para la depuración.
      • logical_operator.end(result): El resultado es un valor booleano (true o false).

Puedes probar la lógica de tu operador lógico personalizado directamente en el IDE. Esto te permite ingresar valores de prueba para los argumentos y verificar que la función muestre el resultado booleano correcto (True o False) según las condiciones definidas.

Parámetros

Los operadores lógicos personalizados aceptan dos parámetros: Lado izquierdo (obligatorio y no editable) y Lado derecho (opcional; el usuario puede inhabilitarlo).

  • Ejemplo 1: if [left side] not in [right side]
  • Ejemplo 2: if [left side] is greater than 80 (sin lado derecho)

Tiempo de espera

  • Tiempo de espera predeterminado: 1 minuto
  • Tiempo de espera máximo: 3 minutos

Uso en guías

Los operadores lógicos personalizados aparecen en el menú de operadores dentro de Condiciones de la guía, Condiciones de la acción anterior y Selección de entidades.

Los operadores lógicos personalizados se pueden seleccionar junto con los operadores estándar (por ejemplo, "Es igual a" o "Contiene").

Manejo de errores

Si una función de operador lógico personalizada encuentra un error durante la ejecución, fallará la condición o el paso de la guía que usa ese operador. El mensaje de error que muestra la secuencia de comandos de Python se muestra en la vista de ejecución de la guía para ayudar a solucionar problemas.

Limitaciones

  • Las funciones de transformación personalizadas y los operadores lógicos no son compatibles con en Activadores ni Webhooks.

¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.