Funciones de transformación personalizadas y operadores lógicos

Se admite en los siguientes sistemas operativos:

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

Cómo crear un paquete de extensiones

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

  1. Ve a Respuesta > IDE.
  2. Haz clic en add Create New Item.
  3. En el menú desplegable, selecciona Paquete de extensión.
  4. Proporciona un Nombre único para el paquete de extensión.
  5. Haz clic en Guardar.

Carga 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 extensiones 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 operadores lógicos y transformadores incluidos en este paquete de extensión específico.

Importar y exportar

Puedes importar y exportar paquetes de extensiones de forma manual directamente desde la interfaz del IDE.

Transformers personalizados

Los transformadores personalizados son funciones de Python definidas por el usuario que extienden las funciones prediseñadas en el Creador de expresiones. Puedes crearlas 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, busca 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. Se muestra cuando colocas el cursor sobre el transformador personalizado en el Compilador 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.
    • El script debe devolver un resultado al compilador 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 convertirlo al tipo esperado en tu función main.
    • Solo puedes usar un subconjunto de los métodos del SDK dentro del IDE para los transformadores:
      • transformer.extract_param("ParamName"): Para recuperar valores de entrada.
      • transformer.LOGGER: Para escribir registros para la depuración.
      • transformer.end(result): Para devolver el valor transformado.
  7. Crea parámetros:
    • Cada función de transformación personalizada incluye un parámetro Input predeterminado. Este parámetro representa los datos de entrada, que son 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 dentro de tu función.
  8. Documentación (opcional): Define la documentación integrada 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 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 playbook. Esto te permite verificar que tu secuencia de comandos de Python controle 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

Usa transformadores personalizados en el generador de expresiones

Una vez guardados, los transformadores personalizados aparecerán en la lista de funciones del Compilador 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 Playbook, incluidos los resultados que no son de JSON.

Para los marcadores de posición que no son JSON, haz lo siguiente:

  • Puedes ingresar datos de muestra de forma manual en el compilador 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 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 del playbook 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 del playbook, 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 operador lógico nuevo, 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 Playbooks.
  5. Define la lógica de la secuencia de comandos con Python. Puedes usar la plantilla predefinida proporcionada como punto de partida.
    • El guion debe incluir una función main.
    • El script debe devolver 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 dentro del IDE para los 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 devuelva el resultado booleano correcto (verdadero o falso) según las condiciones que definiste.

Parámetros

Los operadores lógicos personalizados aceptan dos parámetros: Lado izquierdo (obligatorio y no editable) y Lado derecho (opcional y 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 del playbook que use ese operador. 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 las funciones de transformación personalizadas ni los operadores lógicos en los activadores ni los webhooks.

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