HTTP v2

In diesem Dokument finden Sie eine Anleitung zur Integration von HTTP v2 in das SOAR-Modul von Google Security Operations und zur Verwendung der Aktion HTTP-Anfrage ausführen.

Integrationsversion: 5.0

Übersicht

Mit HTTP v2 können Sie Drittanbieterprodukte einbinden, ohne Code schreiben zu müssen. Außerdem lassen sich Anwendungsfälle wie das Ausführen von API-Anfragen, das Arbeiten mit Dateien und das Verwalten asynchroner Abläufe lösen.

Authentifizierungsabläufe

Je nach dem Produkt, bei dem Sie sich authentifizieren, unterstützt HTTP v2 die folgenden Authentifizierungsabläufe:

  • Ablauf der Basisauthentifizierung
  • Ablauf für API-Schlüssel
  • Dedizierter Authentifizierungsablauf

Ablauf der Basisauthentifizierung

Bei der Basisauthentifizierung erfolgt die Authentifizierung über die Parameter Test URL, Basic Auth Username und Basic Auth Password.

Ablauf für API-Schlüssel

Bei der Authentifizierung mit dem API-Schlüssel-Ablauf werden die Parameter Test URL, API Key Field Name und API Key Field Value verwendet.

Dedizierter Authentifizierungsablauf

Im dedizierten Authentifizierungsablauf wird die folgende zweistufige Authentifizierung verwendet:

  1. Durch eine Aktion wird ein Zugriffstoken generiert.

    Wenn entweder Ping oder die Aktion HTTP-Anfrage ausführen ausgeführt wird, ruft die Integration die für die Authentifizierung erforderlichen Parameter ab.

  2. Eine Aktion verwendet das generierte Zugriffstoken, um API-Anfragen zu authentifizieren.

Für den dedizierten Authentifizierungsablauf sind die folgenden Integrationsparameter erforderlich:

  • Dedicated Auth API Request Method
  • Dedicated Auth API Request URL
  • Dedicated Auth API Request Headers
  • Dedicated Auth API Request Body
  • Dedicated Auth API Request Token Field Name

Weitere Informationen zu den Integrationsparametern finden Sie unter HTTP v2 in Google SecOps einbinden.

Wenn Sie das Token aus der Antwort verwenden möchten, geben Sie den Schlüsselnamen im Parameter Dedicated Auth API Request Token Field Name an. Im folgenden Beispiel für eine Antwort ist der Schlüsselname access_token:

{
   "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCIO4",
   "expires_in": 1799,
   "token_type": "bearer"
}

Damit das Token angewendet werden kann, ist in der Integration der folgende spezielle Platzhalter erforderlich: {{integration.token}}. Wenn Sie diesen Platzhalter in der Nutzlast angeben, verwendet die Integration das generierte Token.

Wenn der Schlüssel access_token in der JSON-Antwort verschachtelt ist, geben Sie den vollständigen Token-Speicherort für den Parameterwert Dedicated Auth API Request Token Field Name an. Geben Sie beispielsweise anstelle von access_token den data_access_token-Schlüssel für die verschachtelte Antwort an:

{
   "data": {
       "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCIZMI3DQAQsYibMpO4",
       "expires_in": 1799,
       "token_type": "bearer"
   }
}

Das folgende Beispiel zeigt die Anfrage für den dedizierten Authentifizierungsablauf an die Crowdstrike API:

POST /falconx/entities/submissions/v1 HTTP/1.1
Host: api.crowdstrike.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6
Content-Length: 209

{
   "sandbox": [{
       "sha256": "9854c9dfded29d8442499daba01082ba5d164aa02e44",
       "environment_id": 100,
       "submit_name": "filename.pdf"
   }]
}

Im Beispiel wird der Authorization-Header mit einem Bearer-Token verwendet, um sich bei der API zu authentifizieren. Damit die Kopfzeile mit den richtigen Informationen gefüllt werden kann, sind für die HTTP v2-Integration die folgenden Eingaben erforderlich: Authorization: Bearer {{integration.token}}.

HTTP v2 in Google SecOps einbinden

Für die Integration sind die folgenden Parameter erforderlich:

Parameter Beschreibung
Test URL Optional

Eine Test-URL, die für die einfache Authentifizierung oder den API-Schlüssel-Authentifizierungsablauf verwendet werden soll.
Basic Auth Username Optional

Ein Parameter, der jeder Aktionsausführung zusammen mit dem Parameter Passwort für die Basisauthentifizierung als Header für die Basisauthentifizierung hinzugefügt werden soll.

Geben Sie sowohl den Parameter Nutzername für die Basisauthentifizierung als auch den Parameter Passwort für die Basisauthentifizierung an.
Basic Auth Password Optional

Ein Parameter, der jeder Ausführung einer Aktion zusammen mit dem Parameter Nutzername für die Basisauthentifizierung als grundlegender Authentifizierungsheader hinzugefügt werden soll.

Geben Sie sowohl den Parameter Nutzername für die Basisauthentifizierung als auch den Parameter Passwort für die Basisauthentifizierung an.
API Key Field Name Optional

Der Name des Headers, der den API-Schlüssel enthält.

Geben Sie sowohl den Parameter API Key Field Name als auch den Parameter API Key Secret an, um sie jeder Ausführung der Aktion hinzuzufügen.
API Key Secret Optional

Der Secret-Wert des API-Schlüssels.

Geben Sie sowohl den Parameter API Key Field Name als auch den Parameter API Key Secret an, um sie jeder Ausführung der Aktion hinzuzufügen.
Dedicated Auth API Request Method Optional

Die Methode, die im dedizierten Authentifizierungs-API-Ablauf zum Generieren des Zugriffstokens verwendet werden soll.

Der Standardwert ist POST.

Dedicated Auth API Request URL Optional

Die API-Anfrage, die im dedizierten Authentifizierungs-API-Ablauf verwendet werden soll, um das Zugriffstoken zu generieren, z. B. https://api.crowdstrike.com/oauth2/token.
Dedicated Auth API Request Headers Optional

Header, die im dedizierten Authentifizierungs-API-Ablauf zum Generieren des Zugriffstokens verwendet werden sollen.

Geben Sie Header als JSON-Objekt an, z. B.:

    {
    "Content-type": "application/x-www-form-urlencoded"
    }
Dedicated Auth API Request Body Optional

Der Anfragetext, der im dedizierten Authentifizierungs-API-Ablauf zum Generieren des Zugriffstokens verwendet werden soll. Geben Sie den Parameterwert als JSON-Objekt an, z. B.:

    {
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET"
    }
Dedicated Auth API Request Token Field Name
 Optional

Der Name des Felds, das das generierte Zugriffstoken enthält. Wenn Sie das Zugriffstoken in Aktionen verwenden möchten, verwenden Sie den folgenden Platzhalter: {{integration.token}}.

In der Antwort für die Tokengenerierung wird der Unterstrich (_) als Trennzeichen verwendet.
CA Certificate Optional

Das Zertifizierungsstellenzertifikat, das zum Validieren der sicheren Verbindung verwendet werden soll.

Wenn Sie einen Remote-Agent verwenden, um eine Verbindung zu einem On-Premise-Produkt herzustellen, können Sie eine zusätzliche Sicherheitsebene hinzufügen, indem Sie das CA-Zertifikat für die Integration bereitstellen, um die Integrität der Verbindung zu gewährleisten. Nachdem Sie ein CA-Zertifikat angegeben haben, wird es für alle API-Anfragen verwendet.

Dieser Parameter akzeptiert das CA-Zertifikat in Form einer base64-codierten Zeichenfolge.
Verify SSL Erforderlich

Wenn diese Option ausgewählt ist, prüft das System, ob das SSL-Zertifikat für alle Integrationsverbindungen gültig ist.

Standardmäßig ausgewählt.

Es empfiehlt sich, für jedes Drittanbieterprodukt, das Sie in Ihre Umgebung einbinden, eine separate Instanz der HTTP v2-Integration zu erstellen. Weitere Informationen zu mehreren Integrationsinstanzen finden Sie unter Mehrere Instanzen unterstützen.

HTTP v2-Integration verwenden

In diesem Abschnitt wird beschrieben, wie Sie die HTTP v2-Integration verwenden, indem Sie die Aktionsparameter für „HTTP-Anfrage ausführen“ ändern.

Mit dem Parameter „Body Payload“ arbeiten

Damit der Textkörper korrekt erstellt wird, geben Sie den richtigen Content-Type-Header im Parameter Headers an. Mit der Aktion HTTP-Anfrage ausführen werden für dieselbe folgende Parametereingabe unterschiedliche Nutzlasten generiert:

{
  "Id": "123123",
  "sorting": "asc"
}

Für den Headerwert "Content-Type:" "application/x-www-form-urlencoded" ist die generierte Nutzlast Id=123123&sorting=asc.

Für den Headerwert "Content-Type": "application/json" sieht die generierte Nutzlast so aus:

{
  "Id": "123123",
  "sorting": "asc"
}

Wenn Sie mit XML arbeiten, geben Sie eine XML-formatierte Eingabe wie die folgende an:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
   <NumberToWords xmlns="http://www.dataaccess.com/webservicesserver/">
     <ubiNum>500</ubiNum>
   </NumberToWords>
 </soap:Body>
</soap:Envelope>

Mit dem asynchronen Ablauf arbeiten

Bei asynchronen API-Abläufen wie dem Erstellen und Ausführen eines Suchjobs muss gewartet werden, bis die Verarbeitung des Ergebnisses abgeschlossen ist, bevor die nächste API-Anfrage ausgeführt wird. Sie können beispielsweise einen Suchauftrag in Google SecOps SIEM erstellen, warten, bis der Suchauftrag abgeschlossen ist, und dann Ergebnisse mit dem Parameter Expected Response Values abrufen.

Im folgenden Beispiel für eine Antwort kann der Schlüssel state den Wert error, in_progress oder finished enthalten:

{
   "state": "in_progress",
   "percentage": "10"
}

Sie können festlegen, dass die Aktion „HTTP-Anfrage ausführen“ im asynchronen Modus ausgeführt wird, bis die Antwort den Status finished enthält. Dazu müssen Sie den Parameter Expected Response Values auf den folgenden Wert festlegen:

{
   "state": "finished"
}

Wenn Sie nicht bis zum Zeitüberschreitungsfehler warten möchten, geben Sie im Parameterwert eine zusätzliche Bedingung an. Im folgenden Eingabebeispiel wird die Ausführung der Aktion beendet, wenn der Status entweder finished oder error ist:

{
   "state": [
       "finished",
       "error"
   ]
}

Im folgenden Beispiel wird die Ausführung der Aktion beendet, wenn der Status finished und der Schlüsselwert für den Prozentsatz 100 ist:

{
   "state": "finished",
   "percentage": "100"
}

Sie können mehrere Schlüsselbedingungen in einer Eingabe kombinieren, z. B.:

{
   "state": [
       "finished",
       "error"
   ],
   "percentage": "100"
}

Sie können den Parameter Expected Response Values so konfigurieren, dass eine Ausgabe für ein bestimmtes Schlüssel/Wert-Paar erwartet wird. Bei der Aktion „HTTP-Anfrage ausführen“ wird das gesamte JSON-Antwortobjekt nach einem bestimmten Schlüssel durchsucht. Der erwartete Output wird nur erreicht, wenn Sie alle übereinstimmenden Schlüsselnamen auf einen identischen erwarteten Schlüsselwert festlegen. Wenn Sie beispielsweise möchten, dass die Aktion in der JSON-Antwort nach dem Status finished sucht und alle anderen Status ignoriert, legen Sie alle state-Schlüssel in der Expected Response Values-Parametereingabe auf den Wert finished fest:

{
"data": {
  "state": "finished"
  },
  "state": "finished"
}

Mit dem Parameter Expected Response Values wird der erforderliche Wert aus dem verschachtelten JSON-Objekt abgerufen. Geben Sie für das folgende Beispiel nur den Schlüssel state an, nicht data_state oder data-state:

{
   "data": {
       "state": [
           "finished",
           "error"
       ],
       "percentage": "100"
   }
}

Mit Dateien arbeiten

Die Arbeit mit Dateien umfasst zwei separate Workflows:

  • Datei herunterladen
  • Datei hochladen

Dateien herunterladen

Mit der Aktion „HTTP-Anfrage ausführen“ können Dateien als Base64-Ausgabe im JSON-Objekt zurückgegeben oder als ZIP-Dateien in der Fallwand gespeichert werden.

Wenn Sie die Daten als Teil eines JSON-Ergebnisses im Base64-Format zurückgeben möchten, wählen Sie den Parameter Base64 Output aus. Wenn Sie Dateien in der Case Wall speichern möchten, wählen Sie den Parameter Save To Case Wall aus.

Wenn Sie mit sensiblen Dateien wie Malware arbeiten, wählen Sie den Parameter Password Protect Zip aus. Bei allen passwortgeschützten ZIP-Dateien wird das Passwort automatisch auf infected gesetzt.

Dateien hochladen

Wenn Sie Dateien hochladen möchten, müssen Sie sie in das Base64-Format konvertieren und als Teil des Parameterwerts Body Payload einreichen. Hier sehen Sie ein Beispiel für eine Bilddatei, die in das Base64-Format konvertiert wurde:

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

Weitere Informationen zur Verwendung des Parameters Body Payload finden Sie im Abschnitt Mit dem Parameter „Body Payload“ arbeiten in diesem Dokument.

Blocks-as-Code

Mit der HTTP v2-Integration und der Playbook-Blockfunktion in Google SecOps können Sie wiederverwendbare Inhalte erstellen. Sie können beispielsweise einen Playbook-Block mit einer HTTP v2-Aktion erstellen und eine Integration so konfigurieren, dass die Aktionsergebnisse als Blockeingaben verwendet werden. Weitere Informationen zu Playbook-Blöcken finden Sie unter Mit Playbook-Blöcken arbeiten.

Playbook-Blöcke erstellen

So erstellen Sie einen Playbook-Block:

  1. Klicken Sie in Google SecOps auf Reaktion > Playbooks.
  2. Wählen Sie in der Navigationsleiste der Seite Playbooks die Option Hinzufügen Neues Playbook oder Block hinzufügen aus. Das Fenster Neu erstellen wird geöffnet.
  3. Legen Sie im Fenster Neu erstellen den Parameter Type auf Block fest.
  4. Wählen Sie für den Parameter Choose Folder den Ordner aus, in dem der neue Block gespeichert werden soll.
  5. Wählen Sie für den Parameter Environment Ihre Umgebung aus.
  6. Klicken Sie auf Erstellen. Die Seite Neuer Block wird geöffnet. Konfigurieren Sie den neuen Playbook-Block, damit er in mehreren Playbooks verwendet werden kann.

Im folgenden Abschnitt finden Sie ein Beispiel für die Konfiguration eines Playbook-Blocks.

Beispiel für die Konfiguration eines Playbook-Blocks

Das folgende Beispiel ist eine benutzerdefinierte Aktion vom Typ „HTTP-Anfrage ausführen“, mit der Kommentare an ServiceNow gesendet werden. Für die Aktion werden die Parameter comment, sys_id und table_name verwendet, die vom benutzerdefinierten Playbook-Block als Eingabeparameter erstellt wurden. Führen Sie die folgenden Schritte aus, um die Parameter der Aktion zu konfigurieren:

  1. Setzen Sie den Parameter Method auf PUT.

  2. Legen Sie für den Parameter URL Path den folgenden Wert fest:

    https://SERVICE_NOW_INSTANCE.service-now.com/api/now/table/[Input.table_name]/[Input.sys_id]

  3. Legen Sie für den Parameter Headers den folgenden Wert fest:

    {"Content-type": "application/json; charset=utf-8",
"Accept": "application/json", "User-Agent": "GoogleSecops"}

  4. Legen Sie für den Parameter Body Payload den folgenden Wert fest:

    {
"work_notes": "[Input.comment]"
}

Wenn Sie die für die Blockeingaben bereitgestellten Werte als Platzhalter für die Aktion verwenden möchten, müssen die Platzhalter vor dem Parameternamen das Präfix Input. enthalten. Wenn die Eingabe für den Block keyname ist, lautet der Platzhalter dafür [Input.keyname].

Aktionen

Die HTTP v2-Integration umfasst die folgenden Aktionen:

HTTP-Anfrage ausführen

Führen Sie eine HTTP-Anfrage mit der HTTP v2-Integration aus.

Mit dieser Aktion können Sie eine benutzerdefinierte HTTP-Anfrage erstellen und Informationen dazu zurückgeben. Alle Parameter in dieser Aktion können geändert werden.

Diese Aktion wird nicht für Elemente ausgeführt.

Aktionseingaben

Für die Aktion „HTTP-Anfrage ausführen“ sind die folgenden Parameter erforderlich:

Parameter Beschreibung
Method
 Optional

Die in der Anfrage zu verwendende Methode.

Der Standardwert ist GET.

Mögliche Werte:
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • HEAD
  • OPTIONS
URL Path
 Optional

Die auszuführende URL.
URL Params Optional

Die URL-Parameter.

Die Aktion verwendet alle Werte, die neben den Werten angegeben werden, die direkt im Parameter URL-Pfad angegeben sind.

Der String ?parameter=value&sorting=asc im Backend bedeutet beispielsweise, dass die Eingabe so aussieht: 
    {
    "parameter": "value",
    "sorting": "asc"
    }

Für diesen Parameter ist das JSON-Objektformat als Eingabe erforderlich. Der Standardwert ist:

{
    "URL Field Name": "URL_FIELD_VALUE"
    }
Headers
 Optional

Header, die in der HTTP-Anfrage verwendet werden sollen.

Für die HTTP-Anfrage mit den Headern Accept und User-Agent ist beispielsweise die folgende Eingabe erforderlich:

    {
    "Accept": "application/json",
    "User-Agent": "Google Secops"
    }

Für diesen Parameter ist das JSON-Objektformat als Eingabe erforderlich. Der Standardwert ist:

{
    "Content-Type": "application/json; charset=utf-8",
    "Accept": "application/json",
    "User-Agent" : "GoogleSecOps"
    }
Cookie Optional

Die Parameter, die im Cookie-Header verwendet werden sollen.

Dieser Parameter überschreibt den im Parameter Headers angegebenen Cookie.

Wenn Sie beispielsweise einen Cookie-Header mit dem Wert PHPSESSID=298zf09hf012fh2; csrftoken=u32t4o3tb3gg43; einfügen möchten, ist für die HTTP-Anfrage die folgende Eingabe erforderlich:

    {
    "PHPSESSID": "298zf09hf012fh2",
    "csrftoken": "u32t4o3tb3gg43"
    }

Für diesen Parameter ist das JSON-Objektformat als Eingabe erforderlich. Der Standardwert ist:

{
    "Cookie_1": "COOKIE_1_VALUE"
    }
Body Payload
 Optional

Der Text für die HTTP-Anfrage. Die Aktion erstellt je nach Content-Type-Headerwert, der im Parameter Headers angegeben ist, unterschiedliche Nutzlasten.

Für diesen Parameter ist das JSON-Objektformat als Eingabe erforderlich, es sei denn, für ein Drittanbieterprodukt ist XML oder der multipart/form-data-Inhalt erforderlich. Wenn Sie eine Datei über die API-Anfrage senden oder hochladen, geben Sie die base64-codierte Version der Datei im Parameter Body Payload an und legen Sie den Header auf "Content-type": "multipart/form-data" fest.

Der Standardwert ist:

{
    "Body Field Name": "BODY_FIELD_VALUE"
    }
Expected Response Values
 Optional

Die erwarteten Antwortwerte.

Wenn dieser Parameter angegeben wird, wird die Aktion im asynchronen Modus ausgeführt, bis die erwarteten Werte empfangen werden oder bis das Zeitlimit überschritten wird.
Save To Case Wall
 Optional

Wenn diese Option ausgewählt ist, wird die Datei gespeichert und an das Fall-Repository angehängt. Die Datei wird mit der Erweiterung .zip archiviert. Die Datei .zip ist nicht passwortgeschützt.

Diese Option ist standardmäßig nicht ausgewählt.
Password Protect Zip
 Optional

Wenn diese Option ausgewählt ist, wird der .zip-Datei, die mit dem Parameter Save To Case Wall erstellt wurde, ein Passwort hinzugefügt. Das Passwort lautet: infected.

Verwenden Sie diesen Parameter, wenn Sie mit verdächtigen Dateien arbeiten.

Standardmäßig ausgewählt.
Follow Redirects Optional

Wenn diese Option ausgewählt ist, folgt die Aktion den Weiterleitungen.

Standardmäßig ausgewählt.
Fail on 4xx/5xx Optional

Wenn diese Option ausgewählt ist, schlägt die Aktion fehl, wenn der Statuscode der Antwort ein 4xx- oder 5xx-Fehler ist.

Standardmäßig ausgewählt.
Base64 Output
 Optional

Wenn diese Option ausgewählt ist, wird die Antwort in das Base64-Format konvertiert.

Verwenden Sie diesen Parameter beim Herunterladen von Dateien.

Das JSON-Ergebnis darf nicht größer als 15 MB sein.

Diese Option ist standardmäßig nicht ausgewählt.
Fields To Return Erforderlich

Die zurückzugebenden Felder. Folgende Werte sind möglich:

  • response_data
  • redirects
  • response_code
  • response_cookies
  • response_headers
  • apparent_encoding
Request Timeout Erforderlich

Die Zeit, die gewartet werden soll, bis der Server Daten sendet, bevor die Aktion fehlschlägt.

Der Standardwert beträgt 120 Sekunden.

Aktionsausgaben

Die Aktion „HTTP-Anfrage ausführen“ bietet die folgenden Ausgaben:

Ausgabetyp der Aktion Verfügbarkeit
Anhang im Fall-Repository Nicht verfügbar
Link zum Fall‑Repository Nicht verfügbar
Tabelle „Fall-Repository“ Nicht verfügbar
Anreicherungstabelle Nicht verfügbar
JSON-Ergebnis Verfügbar
Ausgabemeldungen Verfügbar
Scriptergebnis Verfügbar
JSON-Ergebnis

Im folgenden Beispiel wird die JSON-Ergebnisausgabe beschrieben, die bei Verwendung der Aktion „HTTP-Anfrage ausführen“ empfangen wird:

{
   "response_data": {
       "data": {
           "relationships": {
               "comment": [
                   {
                       "name": "item",
                       "description": "Object to which the comment belongs to."
                   },
                   {
                       "name": "author",
                       "description": "User who wrote the comment."
                   }
               ]
           }
       }
   },
   "redirects": [],
   "response_code": 200,
   "cookies": {},
   "response_headers": {
       "Content-Type": "application/json",
       "X-Cloud-Trace-Context": "1ca450b35c66634a2ae01248cca50b19",
       "Date": "Fri, 03 Nov 2023 16:14:13 GMT",
       "Server": "Google Frontend",
       "Content-Length": "36084"
   },
   "apparent_encoding": "ascii"
}
Ausgabemeldungen

In einer Case Wall gibt die Aktion „HTTP-Anfrage ausführen“ die folgenden Ausgabenachrichten aus:

Ausgabemeldung Nachrichtenbeschreibung

Successfully executed API request.

Successfully executed API request, but status code STATUS_CODE was in response.

Aktion erfolgreich.

Failed to execute API request. Error: ERROR_REASON

Failed to execute API request. Error: Invalid parameter "PARAMETER_NAME".

The JSON structure is invalid. Wrong value provided: VALUE

Aktion fehlgeschlagen.

Prüfen Sie die Verbindung zum Server, die Eingabeparameter, den Wert der JSON-Datei oder die Anmeldedaten.
Scriptergebnis

In der folgenden Tabelle werden die Werte für die Ausgabe des Skriptergebnisses bei Verwendung der Aktion „HTTP-Anfrage ausführen“ beschrieben:

Name des Scriptergebnisses Wert
is_success True oder False

Ping

Mit dieser Aktion können Sie die Verbindung testen.

Aktionseingaben

Keine.

Aktionsausgaben

Die Aktion „Ping“ liefert die folgenden Ausgaben:

Ausgabetyp der Aktion Verfügbarkeit
Anhang im Fall-Repository Nicht verfügbar
Link zum Fall‑Repository Nicht verfügbar
Tabelle „Fall-Repository“ Nicht verfügbar
Anreicherungstabelle Nicht verfügbar
JSON-Ergebnis Nicht verfügbar
Ausgabemeldungen Verfügbar
Scriptergebnis Verfügbar
Ausgabemeldungen

In einer Fallwand werden bei der Ping-Aktion die folgenden Ausgabenachrichten angezeigt:

Ausgabemeldung Nachrichtenbeschreibung
Successfully tested connectivity. Aktion erfolgreich.
Failed to test connectivity.

Aktion fehlgeschlagen.

Überprüfen Sie die Verbindung zum Server, die Eingabeparameter oder die Anmeldedaten.
Scriptergebnis

In der folgenden Tabelle werden die Werte für die Ausgabe des Skriptergebnisses bei Verwendung der Aktion „Ping“ beschrieben:

Name des Scriptergebnisses Wert
is_success True oder False

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