SOAR-Endpunkte zu Chronicle API migrieren

Unterstützt in:

Dieses Dokument gilt für Sie, wenn Sie die SOAR API programmatisch über Integrationen, benutzerdefinierte Skripts oder benutzerdefinierte Aktionen aufrufen. In diesem Dokument werden die Schritte und Überlegungen beschrieben, die Ihnen helfen, programmatische API-Referenzen auf die neuen SOAR API-Endpunkte als Teil der Chronicle API zu aktualisieren.

Die Chronicle API-Oberfläche bietet mehrere Verbesserungen, die den Entwicklungsprozess optimieren sollen. Außerdem werden Einschränkungen und Komplexitäten der älteren API behoben.

Die Legacy-SOAR API und API-Schlüssel sind bis zum 30. September 2026 verfügbar. Danach funktionieren sie nicht mehr.

Vorbereitung

Bevor Sie die SOAR API migrieren, müssen Sie Folgendes tun:

Wichtige Änderungen und Verbesserungen

In der folgenden Tabelle werden die wichtigsten Unterschiede zwischen der alten und der neuen API Oberfläche aufgeführt:

Funktionsbereich Alte API Neue API Details
Authentifizierung API-Token OAuth 2.0 Die neue Authentifizierungsmethode bietet erweiterte Sicherheitsfunktionen und standardisiert den Prozess.
Datenmodelle Einfache Strukturen Ressourcenorientiertes Design Dieses neue Design verbessert die Datenkonsistenz und vereinfacht die Objektbearbeitung.
Endpunktbenennung Uneinheitlich RESTful und standardisiert Eine konsistente Benennung macht die API intuitiver und einfacher zu integrieren.

Zeitplan für die Einstellung

Die alte API-Oberfläche für SOAR wird voraussichtlich am 30. September 2026 vollständig eingestellt. Wir empfehlen, die Migration vor diesem Datum abzuschließen, um Dienstunterbrechungen zu vermeiden.

Migrationsschritte

In diesem Abschnitt werden die Schritte beschrieben, die für die Migration Ihrer Anwendungen zu Chronicle API erforderlich sind:

Dokumentation lesen

Machen Sie sich mit der umfassenden Dokumentation für die neue API vertraut, einschließlich des Chronicle API-Referenzhandbuchs.

Endpunkte der neuen API-Oberfläche zuordnen

Ermitteln Sie die entsprechenden neuen Endpunkte für jeden der alten API-Aufrufe Ihrer Anwendung. Ordnen Sie die alten Datenmodelle den neuen zu und berücksichtigen Sie dabei alle strukturellen Änderungen oder neuen Felder. Weitere Informationen finden Sie in der Tabelle zur Zuordnung von API-Endpunkten.

Optional: Staging-Integration erstellen

Wenn Sie eine benutzerdefinierte Integration oder eine Komponente einer kommerziellen Integration bearbeiten, empfehlen wir, die Änderungen zuerst in eine Staging-Integration zu übertragen. So können Sie Tests durchführen, ohne Ihre Produktionsautomatisierungsabläufe zu beeinträchtigen. Wenn Sie eine benutzerdefinierte Anwendung migrieren, die die SOAR API verwendet, können Sie mit dem nächsten Schritt fortfahren. Weitere Informationen zum Staging von Integrationen finden Sie unter Integrationen im Staging-Modus testen.

Dienstendpunkt und URLs aktualisieren

Ein Dienstendpunkt ist die Basis-URL, die die Netzwerkadresse eines API Dienstes angibt. Ein einzelner Dienst kann mehrere Dienstendpunkte haben. Chronicle ist ein regionaler Dienst und unterstützt nur regionale Endpunkte.

Alle neuen Endpunkte verwenden ein einheitliches Präfix, sodass die endgültige Endpunktadresse vorhersehbar ist. Das folgende Beispiel zeigt die neue Endpunkt-URL-Struktur:

[api_version]/projects/[project_id]/locations/[location]/instances[instance_id]/...

Diese Struktur ergibt die folgende endgültige Adresse für den Endpunkt:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Wobei:

  • service_endpoint: Eine regionale Dienstadresse
  • api_version: Die API-Version, die abgefragt werden soll. Kann v1alpha, v1beta oder v1 sein.
  • project_id: Ihre Projekt-ID (dasselbe Projekt, das Sie für Ihre IAM-Berechtigungen definiert haben)
  • location: Der Standort Ihres Projekts (Region), entspricht den regionalen Endpunkten
  • instance_id: Ihre Google Security Operations SIEM-Kunden-ID.

Regionale Adressen:

  • africa-south1: https://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1: https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12: https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2: https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3: https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6: https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9: https://chronicle.europe-west9.rep.googleapis.com

  • me-central1: https://chronicle.me-central1.rep.googleapis.com

  • me-central2: https://chronicle.me-central2.rep.googleapis.com

  • me-west1: https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

  • us: https://chronicle.us.rep.googleapis.com

  • eu: https://chronicle.eu.rep.googleapis.com

Beispiel: So rufen Sie eine Liste aller Fälle in einem Projekt in den USA ab:

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

Authentifizierungsmethode aktualisieren

Die neue API verwendet Google Cloud IAM zur Authentifizierung. Sie müssen Ihre Anwendungs- oder Antwortintegration aktualisieren, um diesen neuen Authentifizierungsablauf zu implementieren. Achten Sie darauf, dass der Nutzer, der das Skript ausführt, die richtigen Berechtigungen für die Endpunkte hat, auf die er zugreifen möchte. Um diesen neuen Ablauf zu implementieren, müssen Sie Ihre Antwortintegrationen oder -anwendungen aktualisieren. Achten Sie darauf, dass der Nutzer, der das Skript ausführt, die erforderlichen Berechtigungen für die Zielendpunkte hat. Eine detaillierte Anleitung finden Sie auf der Seite Authentifizierung bei der Chronicle API.

Dienstkonto oder Workload Identity SOAR-Parametern zuordnen

Wenn Sie ein Dienstkonto oder die Workload Identity Federation zur Authentifizierung bei der Chronicle API verwenden, müssen Sie es auf der Plattform autorisieren, damit es erfolgreich mit Google SecOps kommunizieren kann. Diese Zuordnung ist erforderlich, um dem Dienstkonto oder der Workload Identity den erforderlichen Zugriff auf SOC-Rollen und -Umgebungen zu gewähren.

So ordnen Sie Ihr Dienstkonto zu:

  1. Gehen Sie zu SOAR-Einstellungen > Erweitert > Gruppenzuordnung.

  2. Klicken Sie auf „ Hinzufügen Hinzufügen“.

  3. Geben Sie im Dialogfeld Rolle hinzufügen die vollständige E-Mail-Adresse Ihres Dienstkontos oder die Hauptkonto-String von Workload Identity in das Feld IAM-Rolle / IdP-Gruppe ein.

  4. Wählen Sie die entsprechenden SOC-Rollen und Umgebungen aus.

  5. Klicken Sie auf Hinzufügen.

Weitere Informationen zum Zuordnen von Nutzern und Dienstkonten finden Sie unter Nutzer auf der Plattform mithilfe von Identitäten des Drittanbieters zuordnen oder Nutzer auf der Plattform mithilfe von Cloud Identity zuordnen.

API-Logik aktualisieren

Analysieren Sie die neuen Datenmodelle und Endpunktstrukturen, die in der API Referenz angegeben sind. Nicht alle Methoden haben sich wesentlich geändert und einige vorhandene Code können wiederverwendet werden. Das Hauptziel besteht darin, die neue Referenz dokumentation zu lesen und für jeden spezifischen Anwendungsfall die erforderlichen Änderungen an Feldnamen und Datenstrukturen in der Logik Ihrer Anwendung zu ermitteln und zu implementieren.

Integration testen

Testen Sie Ihre aktualisierte Anwendung in einer Staging-Integration, bevor Sie sie in der Produktion bereitstellen:

  1. Testplan erstellen: Definieren Sie Testfälle, die alle migrierten Funktionen abdecken.
  2. Tests ausführen: Führen Sie automatisierte und manuelle Tests durch, um Genauigkeit und Gültigkeit zu bestätigen.
  3. Leistung beobachten: Bewerten Sie die Leistung Ihrer Anwendung mit der neuen API.

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