Defender für Cloud-Apps REST-API

Artikel
11/28/2024

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 verwenden, um Lese- und Aktualisierungsvorgänge für Defender for Cloud Apps Daten und Objekte auszuführen. Beispielsweise unterstützt die Defender for Cloud Apps-API die folgenden allgemeinen Vorgänge für ein Benutzerobjekt:

Hochladen von Protokolldateien für cloud discovery
Generieren von Blockskripts
Auflisten von Aktivitäten und Warnungen
Schließen oder Auflösen von Warnungen

API-URL-Struktur

Um die Defender for Cloud Apps-API verwenden zu können, 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 die Option Einstellungen aus. Wählen Sie dann Cloud-Apps aus. Wählen Sie unter System die Option Info aus.
Im Defender for Cloud Apps Info-Bildschirm wird die API-URL angezeigt.

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

API-Token

Defender for Cloud Apps erfordert ein API-Token im Header aller API-Anforderungen an den Server, z. B. die folgenden:

Authorization: Token <your_token_key>

Wo <your_token_key> ist 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/
Warnungen	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 Resource eine Gruppe verwandter Entitäten darstellt.

Welche Feldtypen werden unterstützt?

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

Feld	Beschreibung
string	Eine Textzeichenfolge
Boolescher Wert	Ein boolescher Wert, der true/false darstellt
ganze Zahl	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.

Einschränkungen

Sie können Ihre Anforderungen einschränken, indem Sie einen Limit-Parameter in der Anforderung angeben.

Die folgenden Methoden werden für die Bereitstellung des limit-Parameters unterstützt:

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

Hinweis

Wenn kein Grenzwert angegeben wird, wird der Standardwert 100 festgelegt.
Antworten für alle Anforderungen, die mit dem API-Token vorgenommen werden, sind auf maximal 100 Elemente beschränkt.
Das Drosselungslimit für alle API-Anforderungen beträgt 30 Anforderungen pro Minute und Mandant.

Filter

Wenn Sie über eine große Anzahl von Ergebnissen verfügen, ist es hilfreich, Anforderungen mithilfe von Filtern zu optimieren. In diesem Abschnitt wird die Struktur von - und -Operatoren beschrieben, die mit Filtern verwendet werden können.

Structure

Einige unserer API-Endpunkte unterstützen Filter beim Ausführen von Abfragen. In den entsprechenden Abschnitten finden Sie eine Referenz, die alle verfügbaren filterbaren Felder und unterstützten Operatoren für diese Ressource auflistet.

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.

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

Operator	Antworttyp	Beschreibung
contains	Liste der 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 einem der angegebenen Werte entspricht.
descendantof	Liste der Werte	Gibt alle relevanten Datensätze zurück, die Werte oder Nachfolger davon übereinstimmen
doesnotstartwith	Liste der Zeichenfolgen	Gibt alle relevanten Datensätze zurück, die nicht mit jeder der bereitgestellten Zeichenfolgen beginnen.
endswith	Liste der Zeichenfolgen	Gibt alle relevanten Datensätze zurück, die mit einer der angegebenen Zeichenfolgen enden.
eq	Liste der Werte	Gibt alle relevanten Datensätze zurück, die einen der angegebenen Werte enthalten.
gt	Einzelner Wert	Gibt alle Datensätze zurück, deren Wert größer als der angegebene Wert ist.
Gte	Einzelner Wert	Gibt alle Datensätze zurück, deren Wert größer oder gleich dem angegebenen Wert ist.
gte_ndays	number	Gibt alle Datensätze mit einem Datum zurück, das älter als vor N Tagen ist.
isnotset	Boolescher Wert	Gibt bei Festlegung auf "true" alle relevanten Datensätze zurück, die keinen Wert im angegebenen Feld haben.
isset	Boolescher Wert	Gibt bei Festlegung auf "true" alle relevanten Datensätze zurück, die einen Wert im angegebenen Feld aufweisen.
lt	Einzelner Wert	Gibt alle Datensätze zurück, deren Wert kleiner als der angegebene Wert ist.
lte	Einzelner Wert	Gibt alle Datensätze zurück, deren Wert kleiner oder gleich dem angegebenen Wert ist.
lte_ndays	number	Gibt alle Datensätze zurück, deren Datum vor N Tagen liegt.
ncontains	Liste der 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 Nachfolgern von ihnen übereinstimmen.
neq	Liste der Werte	Gibt alle relevanten Datensätze zurück, die nicht alle angegebenen Werte enthalten.
range	Liste der Objekte, die die Felder "start" und "end" enthalten	Gibt alle Datensätze innerhalb eines der angegebenen Bereiche zurück.
startswith	Liste der Zeichenfolgen	Gibt alle relevanten Datensätze zurück, die mit einer der bereitgestellten Zeichenfolgen beginnen.
startswithsingle	string	Gibt alle relevanten Datensätze zurück, beginnend mit der angegebenen Zeichenfolge.
text	string	Führt eine Volltextsuche für alle Datensätze aus.

Nächste Schritte

API-Authentifizierung

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

Freigeben über