Funciones de transformación y operadores lógicos personalizados

Disponible en:

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 prácticos 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 personalizadas y operadores lógicos. A diferencia de las integraciones estándar, los paquetes de extensiones no requieren configuración de instancias y se pueden crear directamente desde el IDE.

Prácticas recomendadas para los paquetes de extensiones

  • Consolidación: crea un paquete de extensiones principal y añádele varias funciones de transformación u operadores lógicos.
  • Separación: crea un paquete de extensión cuando necesites un conjunto diferente de bibliotecas de Python (dependencias) que puedan entrar en conflicto con el paquete principal.

Crear un paquete de extensiones

Para crear un paquete de extensiones, sigue estos pasos:

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

Subir dependencias

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

Para gestionar tus bibliotecas, sigue estos pasos:

  1. Abre los ajustes del paquete de extensiones en el IDE.
  2. Añade las bibliotecas de Python necesarias desde PyPi o súbelas desde tu ordenador.

Estas dependencias están disponibles para todos los transformadores y operadores lógicos incluidos en este paquete de extensiones específico.

Importar y exportar

Puedes importar y exportar manualmente paquetes de extensiones directamente en la interfaz del IDE.

Transformadores personalizados

Las transformaciones personalizadas son funciones de Python definidas por el usuario que amplían las funciones precompiladas del generador de expresiones. Puedes crearlas directamente en el IDE para extraer y manipular datos, y se pueden usar junto con las funciones integradas.

Crear un transformador personalizado

Para definir un nuevo transformador personalizado, sigue estos pasos:

  1. En el IDE, busca el paquete de extensión de destino.
  2. Selecciona el paquete de extensiones de destino para añadir un nuevo elemento.
  3. Selecciona Función de transformación personalizada.
  4. Ponle un nombre.
  5. Opcional: Añade una descripción. Se muestra al colocar 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 que se proporciona 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 devolver un resultado al creador de expresiones mediante la función end del SDK.
    • La entrada del transformador personalizado puede ser de diferentes tipos (por ejemplo, cadena o lista). Asegúrate de convertirlo al tipo esperado en tu función main.
    • Solo puede usar un subconjunto de los métodos del SDK en el IDE para transformadores:
      • transformer.extract_param("ParamName"): para obtener los valores de entrada.
      • transformer.LOGGER: para escribir registros para depuración.
      • transformer.end(result): para devolver el valor transformado.
  7. Crea los parámetros:
    • Cada función de transformación personalizada 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 eliminar este parámetro.
    • Además, puede añadir parámetros opcionales que se usen en su función.
  8. Documentación (opcional): define la documentación del producto para el Generador de expresiones:
    • Entrada esperada: describe el tipo de datos que la función espera recibir para este transformador (por ejemplo, "String" o "List of strings").
    • Salida esperada: describe el tipo de datos que la función espera devolver 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 un cuaderno de estrategias. De esta forma, puedes verificar que tu secuencia de comandos de Python gestione correctamente varios tipos de entrada y parámetros, y que devuelva los resultados esperados.

Tiempo de espera

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

Usar transformadores personalizados en el generador de expresiones

Una vez guardadas, las transformaciones personalizadas aparecen en la lista de funciones del generador de expresiones junto con las funciones integradas. Se identifican con el formato: ExtensionPackName.TransformerName. Al colocar 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 que se muestran en el diseñador de Playbook, incluidos los resultados que no son JSON.

Para los marcadores de posición que no son JSON:

  • Puedes introducir manualmente datos de muestra en el creador 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 devuelva 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 cadenas o listas en función de su cantidad (por ejemplo, entity.identifier). En estos casos, se recomienda tratar siempre la entrada como una lista.

Gestión de errores

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

Operadores lógicos personalizados

Los operadores lógicos personalizados le permiten definir su propia lógica booleana para comparar valores.

Crear un operador lógico personalizado

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

  1. En el IDE, busca el paquete de extensiones de destino.
  2. Selecciona Operador lógico personalizado.
  3. Ponle un nombre.
  4. Opcional: Añade una descripción del menú de operadores lógicos en el diseñador de manuales.
  5. Define la lógica de la secuencia de comandos con Python. Puedes usar la plantilla predefinida que se proporciona como punto de partida.
    • La secuencia de comandos debe incluir una función main.
    • La secuencia de comandos debe devolver un resultado booleano a la condición mediante 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 obtener los valores de entrada.
      • logical_operator.LOGGER: para escribir registros de 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 introducir valores de prueba para los argumentos y verificar que la función devuelve el resultado booleano correcto (True o False) en función de las condiciones que hayas definido.

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 (no hay lado derecho).

Tiempo de espera

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

Usar en guías

Los operadores lógicos personalizados aparecen en el menú de operadores de Condiciones de manual de respuestas, Condiciones de acción anterior y Selección de entidad.

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

Gestión de errores

Si una función de operador lógico personalizado detecta un error durante la ejecución, la condición o el paso del cuaderno de estrategias que utilice ese operador fallará. El mensaje de error que devuelve la secuencia de comandos de Python se muestra en la vista de ejecución del playbook para ayudar a solucionar problemas.

Limitaciones

  • No se admiten funciones de transformación personalizadas ni operadores lógicos en Activadores ni Webhooks.

¿Necesitas más ayuda? Recibe respuestas de los miembros de la comunidad y de los profesionales de Google SecOps.