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:

Ressource	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