Defender for Cloud Apps-REST-API

Artikel
12/29/2023

Klassisches Portal – In diesem Artikel wird beschrieben, wie Sie mit Defender for Cloud Apps über HTTPS interagieren.

Die Microsoft Defender for Cloud Apps-API bietet programmgesteuerten Zugriff auf Defender for Cloud Apps über REST-API-Endpunkte. Anwendungen können die API zum Durchführen von Lese- und Aktualisierungsvorgängen für Defender for Cloud Apps-Daten und -Objekte verwenden. Die Defender for Cloud Apps-API unterstützt z.B. die folgenden häufigen Vorgänge für ein Benutzerobjekt:

Protokolldateien für Cloud Discovery hochladen
Blockskripts generieren
Auflisten von Aktivitäten und Warnungen
Warnungen verwerfen oder auflösen

Die API-URL-Struktur

Um die Defender for Cloud Apps-API zu verwenden, müssen Sie zuerst die API-URL von Ihrem Mandanten abrufen. Die API URL verwendet das folgende Format: https://<portal_url>/api/<endpoint>.

Führen Sie die folgenden Schritte aus, um die Defender for Cloud Apps-API-URL für Ihren Mandanten abzurufen:

Wählen Sie im Microsoft Defender-Portal Einstellungen aus. Wählen Sie dann Cloud-Apps aus. Wählen Sie unter System die Option Info aus.
Auf dem Info-Bildschirm von Defender for Cloud Apps wird die API-URL angezeigt.

Nachdem Sie über die API-URL verfügen, fügen Sie das /api Suffix hinzu, um Ihre API-URL abzurufen. Wenn die URL Ihres Portals beispielsweise https://mytenant.us2.contoso.com lautet, lautet ihre API-URL https://mytenant.us2.portal.cloudappsecurity.com/api.

API-Token

Defender für Cloud-Apps erfordert ein API-Token im Header aller API-Anforderungen an den Server, z. B. folgendes:

Authorization: Token <your_token_key>

Wo <your_token_key> befindet sich Ihr persönliches API-Token.

Weitere Informationen zu API-Token finden Sie unter Verwalten von API-Token.

API-Token – Beispiel

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"

Welche Aktionen werden unterstützt?

In der folgenden Tabelle werden die unterstützten Aktionen beschrieben:

Resource	HTTP-Verben	URI-Routen
Aktivitäten	GET oder POST	/api/v1/activities/
Alerts	GET oder POST	/api/v1/alerts
Datenanreicherung	GET, POST oder DELETE.	/api/subnet/
Entitäten	GET oder POST	/api/v1/entities/
Dateien	GET oder POST	/api/v1/files/

Wobei Ressource eine Gruppe von verbundenen Entitäten darstellt.

Welche Feldtypen werden unterstützt?

Die folgende Tabelle beschreibt die unterstützten Feldtypen:

Feld	Beschreibung
string	Eine textbezogene Zeichenfolge
boolean	Ein boolescher Wert der „wahr“ oder „falsch“ darstellt.
integer	32-Bit-Ganzzahl mit Vorzeichen
Zeitstempel	Millisekunden seit Epoche

Zeitstempel

Erwähnungen von Zeitstempeln in der Defender for Cloud Apps-API beziehen sich auf den Unix-Zeitstempel in Millisekunden. Dieser Zeitstempel wird durch die Anzahl der Millisekunden seit 1970-01-01 0:00:00 bestimmt. Sie können das PowerShell-Cmdlet get-date verwenden, um Datumsangaben in Zeitstempel zu konvertieren.

Grenzwerte

Sie können ihre Anforderungen einschränken, indem Sie einen Grenzwertparameter in der Anforderung angeben.

Die folgenden Methoden werden für die Bereitstellung des Grenzparameters unterstützt:

URL-codiert (mit Content-Type: application/x-www-form-urlencoded Header)
Formulardaten
JSON-Textkörper (mit Content-Type: multipart/form-data und einem geeigneten Begrenzungsheader)

Hinweis

Wenn kein Grenzwert angegeben wird, wird ein Standardwert von 100 festgelegt.
Antworten auf alle Anforderungen, die mit dem API-Token vorgenommen wurden, sind auf maximal 100 Elemente beschränkt.
Der Drosselungsgrenzwert für alle API-Anforderungen beträgt 30 Anforderungen pro Minute pro Mandant.

Filter

Wenn Sie eine große Anzahl von Ergebnissen erhalten, ist es hilfreich, Anforderungen mithilfe von Filtern zu optimieren. In diesem Abschnitt wird die Struktur von Filtern beschrieben, sowie Operatoren, die mit ihnen verwendet werden können.

Struktur

Einige unserer API-Endpunkte unterstützen Filter beim Ausführen von Abfragen. In den relevanten Abschnitten finden Sie einen Verweis, in dem alle verfügbaren filterbaren Felder und unterstützten Operatoren für diese Ressource aufgelistet sind.

Die meisten Filter unterstützen mehrere Werte, um leistungsstarke Abfragen bereitzustellen. Beim Kombinieren von Filtern und Operatoren verwenden wir AND als logischen Operator zwischen den Filtern.

Filter - Beispiel

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
  "filters": {
    "some.field": {
      "eq": ["value1", "value2"],
      "isset": true
    },
    "some.field2": {
      "gte": 5
    }
  },
  "skip": 5,
  "limit": 10
}'

Operatoren

Hinweis

Nicht alle Operatoren sind mit allen Filtern kompatibel.

Die folgende Tabelle beschreibt die unterstützten Operatoren:

Operator	Antworttyp	Beschreibung
contains	Eine Liste von Zeichenfolgen	Gibt alle relevanten Datensätze zurück, die eine der bereitgestellten Zeichenfolgen enthalten.
Deq	Liste der Werte	Gibt alle Datensätze zurück, die einen Wert enthalten, der nicht den angegebenen Werten entspricht.
descendantof	Liste der Werte	Gibt alle relevanten Datensätze zurück, die mit Werten oder deren Nachfolgern übereinstimmen
doesnotstartwith	Eine Liste von Zeichenfolgen	Gibt alle relevanten Datensätze zurück, die nicht mit jeder der bereitgestellten Zeichenfolgen beginnen.
endswith	Eine Liste von Zeichenfolgen	Gibt alle relevanten Datensätze zurück, die mit einer der bereitgestellten Zeichenfolgen enden.
eq	Liste der Werte	Gibt alle relevanten Datensätze zurück, die einen der bereitgestellten Werte enthalten.
gt	Einzelwert	Gibt alle Datensätze zurück, deren Wert größer als der angegebene Wert ist.
gte	Einzelwert	Gibt alle Datensätze zurück, deren Wert größer oder gleich dem angegebenen Wert ist.
gte_ndays	Zahl	Sendet alle Datensätze zurück, deren Datum nach N Tagen liegt.
isnotset	boolean	Wenn dieser Wert auf „true" festgelegt ist, werden alle relevanten Datensätze zurückgegeben, die keinen Wert im angegebenen Feld haben.
Isset	boolean	Wenn dieser Wert auf „true" festgelegt ist, werden alle relevanten Datensätze zurückgegeben, die einen Wert im angegebenen Feld haben.
lt	Einzelwert	Gibt alle Datensätze zurück, deren Wert kleiner als der angegebene Wert ist.
lte	Einzelwert	Gibt alle Datensätze zurück, deren Wert kleiner oder gleich dem angegebenen Wert ist.
lte_ndays	Zahl	Sendet alle Datensätze zurück, deren Datum vor N Tagen liegt.
ncontains	Eine Liste von Zeichenfolgen	Gibt alle relevanten Datensätze zurück, die keine der bereitgestellten Zeichenfolgen enthalten
ndescendantof	Liste der Werte	Gibt alle relevanten Datensätze zurück, die nicht mit Werten oder deren Nachfolgern übereinstimmen
NEQ	Liste der Werte	Gibt alle relevanten Datensätze zurück, die nicht alle bereitgestellten Werte enthalten
range	Liste der Objekte, die die Felder „start" und „end" enthalten	Gibt alle Datensätze innerhalb eines der bereitgestellten Bereiche zurück.
startswith	Eine Liste von Zeichenfolgen	Gibt alle relevanten Datensätze zurück, die mit einer der bereitgestellten Zeichenfolgen beginnen.
startswithsingle	Zeichenfolge	Gibt alle relevanten Datensätze zurück, die mit der bereitgestellten Zeichenfolge beginnen.
Text	Zeichenfolge	Führt eine Volltextsuche aller Datensätze aus.

Nächste Schritte

API-Authentifizierung

Sollten Sie Probleme haben, helfen wir Ihnen gerne weiter. Um Unterstützung oder Support für Ihr Produktproblem zu erhalten, öffnen Sie bitte ein Supportticket.

Freigeben über