Benutzerdefinierte Transformer entwickeln

Unterstützt in:

Sie können benutzerdefinierte Python-basierte Transformationsfunktionen und logische Operatoren direkt in der IDE erstellen und in Ihren Playbooks für komplexe und vielseitige Anwendungsfälle verwenden.

Erweiterungspakete

Ein Erweiterungspaket ist ein spezieller Integrationstyp, der als Container für benutzerdefinierte Transformationsfunktionen und logische Operatoren dient. Im Gegensatz zu Standardintegrationen erfordern Erweiterungspakete keine Instanzkonfiguration und können direkt in der IDE erstellt werden.

Best Practices für Erweiterungspakete

  • Konsolidierung: Erstellen Sie ein Haupt-Erweiterungspaket und fügen Sie ihm mehrere Transformationsfunktionen oder logische Operatoren hinzu.
  • Trennung: Erstellen Sie ein neues Erweiterungspaket, wenn Sie einen anderen Satz von Python-Bibliotheken (Abhängigkeiten) benötigen, die mit dem Haupt paket in Konflikt stehen könnten.

Erweiterungspaket erstellen

So erstellen Sie ein neues Erweiterungspaket:

  1. Rufen Sie Antwort > IDE auf.
  2. Klicken Sie auf Hinzufügen Neues Element erstellen.
  3. Wählen Sie im Drop-down-Menü die Option Erweiterungspaket aus.
  4. Geben Sie einen eindeutigen Namen für das Erweiterungspaket an.
  5. Klicken Sie auf Speichern.

Abhängigkeiten hochladen

Wie Standardintegrationen werden Erweiterungspakete in einer virtuellen Umgebung ausgeführt, in der Sie Python-Bibliotheken verwalten können.

So verwalten Sie Ihre Bibliotheken:

  1. Öffnen Sie die Einstellungen für Erweiterungspakete in der IDE.
  2. Fügen Sie die erforderlichen Python-Bibliotheken aus PyPi hinzu oder laden Sie sie von Ihrem Computer hoch.

Diese Abhängigkeiten sind für alle Transformer und logischen Operatoren verfügbar, die in diesem Erweiterungspaket enthalten sind.

Importieren und exportieren

Sie können Erweiterungspakete direkt in der IDE-Oberfläche manuell importieren und exportieren.

Benutzerdefinierte Transformer

Benutzerdefinierte Transformer sind benutzerdefinierte Python-Funktionen, die die vordefinierten Funktionen im Ausdrucks-Editor erweitern. Sie können direkt in der IDE erstellt werden, um Daten zu extrahieren und zu bearbeiten, und können neben vorhandenen integrierten Funktionen verwendet werden.

Benutzerdefinierten Transformer erstellen

So definieren Sie einen neuen benutzerdefinierten Transformer:

  1. Suchen Sie in der IDE nach dem Ziel-Erweiterungspaket.
  2. Wählen Sie das Ziel-Erweiterungspaket aus, um ein neues Element unter dem Paket hinzuzufügen.
  3. Wählen Sie Benutzerdefinierte Transformationsfunktion aus.
  4. Geben Sie einen Namen an.
  5. Optional: Fügen Sie eine Beschreibung hinzu. Diese wird angezeigt, wenn Sie im Ausdrucks-Editor mit dem Mauszeiger auf den benutzerdefinierten Transformer zeigen.
  6. Definieren Sie die Skriptlogik mit Python. Sie können die bereitgestellte Standard Vorlage als Ausgangspunkt verwenden.
    • Das Skript muss eine main Funktion enthalten, wie in der vordefinierten Vorlage gezeigt.
    • Das Skript muss mit der SDK-Funktion end ein Ergebnis an den Ausdrucks-Editor zurückgeben.
    • Die Eingabe des benutzerdefinierten Transformers kann verschiedene Typen haben (z. B. String oder Liste). Achten Sie darauf, dass Sie sie in Ihrer main Funktion in den erwarteten Typ konvertieren.
    • Sie können in der IDE nur eine Teilmenge der SDK-Methoden für Transformer verwenden:
      • transformer.extract_param("ParamName"): Zum Abrufen von Eingabewerten.
      • transformer.LOGGER: Zum Schreiben von Logs für Debugging.
      • transformer.end(result): Zum Zurückgeben des transformierten Werts.
  7. Parameter erstellen:
    • Jede benutzerdefinierte Transformer-Funktion enthält einen Standardparameter für die Eingabe. Dieser Parameter stellt die Eingabedaten dar, also den Platzhalter, auf den die Funktion angewendet wird. Sie können diesen Parameter nicht löschen.
    • Außerdem können Sie optionale Parameter hinzufügen, die in Ihrer Funktion verwendet werden sollen.
  8. Dokumentation (optional): Definieren Sie die In-Product-Dokumentation für den Ausdrucks-Editor:
    • Erwartete Eingabe: Beschreiben Sie den Datentyp, den die Funktion erhalten soll (z. B. „String“ oder „Liste von Strings“).
    • Erwartete Ausgabe: Beschreiben Sie den Datentyp, den die Funktion zurückgeben soll (z. B. „boolesch“).
    • Verwendungsbeispiel: Geben Sie ein Beispiel dafür, wie die Funktion aufgerufen wird (z. B. if_empty("new_value")).

Sie können die Logik Ihrer benutzerdefinierten Transformationsfunktion direkt in der IDE testen, bevor Sie sie in einem Playbook verwenden. So können Sie prüfen, ob Ihr Python-Skript verschiedene Eingabetypen und Parameter korrekt verarbeitet und die erwarteten Ergebnisse zurückgibt.

Zeitüberschreitung

  • Standardzeitüberschreitung:1 Minute.
  • Maximale Zeitüberschreitung:3 Minuten.

Benutzerdefinierte Transformer im Ausdrucks-Editor verwenden

Nach dem Speichern werden benutzerdefinierte Transformer in der Funktionsliste des Ausdrucks-Editors neben den integrierten Funktionen angezeigt. Sie werden im Format ExtensionPackName.TransformerName identifiziert. Wenn Sie mit dem Mauszeiger auf die Funktion zeigen, wird die Dokumentation angezeigt, die aus Ihren Parameterbeschreibungen generiert wurde.

Unterstützung für alle Platzhalter (JSON und nicht JSON)

Der Ausdrucks-Editor unterstützt alle Platzhalter, die im Playbook-Designer verfügbar sind, einschließlich nicht JSON-Ergebnissen.

Für nicht JSON-Platzhalter:

  • Sie können Beispieldaten manuell in den Ausdrucks-Editor eingeben, um die Logik für verschiedene Eingabetypen zu testen: String, Liste (kommagetrennte Werte) und JSON.
  • Wenn Sie mit einem Eingabetyp testen, wird nicht garantiert, dass der Platzhalter zur Laufzeit diesen bestimmten Typ zurückgibt.
  • Die meisten Platzhalter werden als Strings aufgelöst, mit Ausnahme bestimmter Typen, die als String oder Liste aufgelöst werden (z. B. entity.identifier). Für diese Typen wird empfohlen, die Eingabe immer als Liste zu behandeln.

Fehlerbehandlung

Wenn bei der Ausführung einer benutzerdefinierten Transformationsfunktion ein Fehler auftritt, schlägt die Playbook-Aktion fehl, die diesen Transformer verwendet. Die vom Python-Skript generierte Fehlermeldung wird in der Playbook-Ausführung angezeigt, sodass Sie die Logik direkt beheben können.

Benutzerdefinierte logische Operatoren

Mit benutzerdefinierten logischen Operatoren können Sie Ihre eigene boolesche Logik zum Vergleichen von Werten definieren.

Benutzerdefinierten logischen Operator erstellen

So definieren Sie einen neuen logischen Operator:

  1. Suchen Sie in der IDE nach dem Ziel-Erweiterungspaket.
  2. Wählen Sie Benutzerdefinierter logischer Operator aus.
  3. Geben Sie einen Namen an.
  4. Optional: Fügen Sie eine Beschreibung für das Menü der logischen Operatoren im Playbook-Designer hinzu.
  5. Definieren Sie die Skriptlogik mit Python. Sie können die bereitgestellte vordefinierte Vorlage als Start verwenden.
    • Das Skript muss eine main-Funktion enthalten.
    • Das Skript muss mit der SDK-end Funktion ein boolesches Ergebnis an die Bedingung zurückgeben.
    • Sie können in der IDE nur eine Teilmenge der SDK-Methoden für logische Operatoren verwenden:
      • logical_operator.extract_param("ParamName"): Zum Abrufen von Eingabewerten.
      • logical_operator.LOGGER: Zum Schreiben von Logs für Debugging.
      • logical_operator.end(result): Das Ergebnis ist ein boolescher Wert (true oder false).

Sie können die Logik Ihres benutzerdefinierten logischen Operators direkt in der IDE testen. So können Sie Testwerte für die Argumente eingeben und prüfen, ob die Funktion basierend auf den von Ihnen definierten Bedingungen das richtige boolesche Ergebnis (True oder False) zurückgibt.

Parameter

Benutzerdefinierte logische Operatoren akzeptieren zwei Parameter: Linke Seite (erforderlich und nicht bearbeitbar) und Rechte Seite (optional; kann vom Nutzer deaktiviert werden).

  • Beispiel 1:if [left side] not in [right side].
  • Beispiel 2: if [left side] is greater than 80 (keine rechte Seite).

Zeitüberschreitung

  • Standardzeitüberschreitung:1 Minute.
  • Maximale Zeitüberschreitung:3 Minuten.

In Playbooks verwenden

Benutzerdefinierte logische Operatoren werden im Menü der Operatoren unter Playbook Bedingungen, Bedingungen für vorherige Aktionen und Entitätsauswahl angezeigt.

Benutzerdefinierte logische Operatoren können neben Standardoperatoren (z. B. „Gleich“ oder „Enthält“) ausgewählt werden.

Fehlerbehandlung

Wenn bei der Ausführung einer benutzerdefinierten logischen Operatorfunktion ein Fehler auftritt, schlägt die Playbook-Bedingung oder der Playbook-Schritt fehl, die bzw. der diesen Operator verwendet. Die vom Python-Skript zurückgegebene Fehlermeldung wird in der Playbook-Ausführung angezeigt, um die Fehlerbehebung zu erleichtern.

Beschränkungen

  • Benutzerdefinierte Transformationsfunktionen und logische Operatoren werden nicht unterstützt in Triggern oder Webhooks.

Benötigen Sie weitere Hilfe? Erhalten Sie Antworten von Community-Mitgliedern und Google SecOps-Experten.