REST API för Defender för Cloud Apps

Artikel
08/19/2024

Den här artikeln beskriver hur du interagerar med Defender for Cloud Apps via HTTPS.

API:et För Microsoft Defender för molnappar ger programmatisk åtkomst till Defender for Cloud Apps via REST API-slutpunkter. Program kan använda API:et för att utföra läs- och uppdateringsåtgärder på Data och objekt i Defender för Cloud Apps. Till exempel stöder Defender for Cloud Apps API följande vanliga åtgärder för ett användarobjekt:

Ladda upp loggfiler för molnidentifiering
Generera blockskript
Visa en lista över aktiviteter och aviseringar
Stänga eller lösa aviseringar

API-URL-struktur

Om du vill använda API:et defender för molnappar måste du först hämta API-URL:en från din klientorganisation. API-URL:en använder följande format: https://<portal_url>/api/<endpoint>.

Utför följande steg för att hämta URL:en för API:et för Defender for Cloud Apps för din klientorganisation:

I Microsoft Defender-portalen väljer du Inställningar. Välj sedan Cloud Apps. Under System väljer du Om.
På skärmen Defender för Molnappar om kan du se API-URL:en.

När du har API-URL:en lägger du till suffixet /api i den för att hämta DIN API-URL. Om portalens URL till exempel är https://mytenant.us2.contoso.comär https://mytenant.us2.portal.cloudappsecurity.com/apiAPI-URL:en .

API-token

Defender för Cloud Apps kräver en API-token i rubriken för alla API-begäranden till servern, till exempel följande:

Authorization: Token <your_token_key>

Var <your_token_key> finns din personliga API-token.

Mer information om API-token finns i Hantera API-token.

API-token – exempel

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

Vilka åtgärder stöds?

I följande tabell beskrivs de åtgärder som stöds:

Resurs	HTTP-verb	URI-vägar
Aktiviteter	GET eller POST	/api/v1/activities/
Aviseringar	GET eller POST	/api/v1/alerts/
Databerikning	GET, POST eller DELETE	/api/undernät/
Entiteter	GET eller POST	/api/v1/entiteter/
Filer	GET eller POST	/api/v1/files/

Där Resurs representerar en grupp med relaterade entiteter.

Vilka fälttyper stöds?

I följande tabell beskrivs de fälttyper som stöds:

Fält	beskrivning
sträng	En textsträng
boolean	Ett booleskt värde som representerar sant/falskt
integer	32-bitars signerat heltal
timestamp	Millisekunder sedan epoken

Tidsstämplar

Omnämnanden av tidsstämplar i API:et defender för molnappar refererar till Unix-tidsstämpeln i millisekunder. Tidsstämpeln bestäms av antalet millisekunder sedan 1970-01-01 0:00:00. Du kan använda PowerShell-cmdleten get-date för att konvertera datum till tidsstämplar.

Gränser

Du kan välja att begränsa dina begäranden genom att ange en gränsparameter i begäran.

Följande metoder stöds för att tillhandahålla gränsparametern:

URL-kodad (med Content-Type: application/x-www-form-urlencoded sidhuvud)
Formulärdata
JSON-brödtext (med Content-Type: multipart/form-data och ett lämpligt gränshuvud)

Kommentar

Om ingen gräns anges anges standardvärdet 100.
Svar för alla begäranden som görs med API-token är begränsade till högst 100 objekt.
Begränsningsgränsen för alla API-begäranden är 30 begäranden per minut per klientorganisation.

Filter

När du har ett stort antal resultat är det bra att finjustera begäranden med hjälp av filter. I det här avsnittet beskrivs strukturen för filter och operatorer som kan användas med.

Struktur

Vissa av våra API-slutpunkter stöder filter när du utför frågor. I relevanta avsnitt hittar du en referens som visar alla tillgängliga filterbara fält och operatorer som stöds för den resursen.

De flesta filter stöder flera värden för att ge dig kraftfulla frågor. När vi kombinerar filter och operatorer använder vi AND som logisk operator mellan filtren.

Filter – exempel

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
}'

Operatorer

Kommentar

Alla operatorer är inte kompatibla med alla filter.

I följande tabell beskrivs operatorerna som stöds:

Operator	Svarstyp	beskrivning
innehåller	lista över strängar	Returnerar alla relevanta poster som innehåller en av de angivna strängarna
deq	lista med värden	Returnerar alla poster som innehåller ett värde som inte är lika med ett angivet värde
descendantof	lista med värden	Returnerar alla relevanta poster som matchar värden eller underordnade poster
doesnotstartwith	lista över strängar	Returnerar alla relevanta poster som inte börjar med var och en av de angivna strängarna
endswith	lista över strängar	Returnerar alla relevanta poster som slutar med en av de angivna strängarna
eq	lista med värden	Returnerar alla relevanta poster som innehåller ett av de angivna värdena
gt	enskilt värde	Returnerar alla poster vars värde är större än det angivna värdet
gte	enskilt värde	Returnerar alla poster vars värde är större än eller lika med det angivna värdet
gte_ndays	Nummer	Returnerar alla poster med datum senare än N dagar sedan
isnotset	boolean	När värdet är "true" returneras alla relevanta poster som inte har något värde i det angivna fältet
isset	boolean	När värdet är "true" returneras alla relevanta poster som har ett värde i det angivna fältet
lt	enskilt värde	Returnerar alla poster vars värde är mindre än det angivna värdet
lte	enskilt värde	Returnerar alla poster vars värde är mindre än eller lika med det angivna värdet
lte_ndays	Nummer	Returnerar alla poster med datumet tidigare än N dagar sedan
ncontains	lista över strängar	Returnerar alla relevanta poster som inte innehåller någon av de angivna strängarna
ndescendantof	lista med värden	Returnerar alla relevanta poster som inte matchar värden eller underordnade poster
neq	lista med värden	Returnerar alla relevanta poster som inte innehåller alla angivna värden
intervall	lista över objekt som innehåller fälten "start" och "end"	Returnerar alla poster inom ett av de angivna intervallen
startswith	lista över strängar	Returnerar alla relevanta poster som börjar med en av de angivna strängarna
startswithsingle	sträng	Returnerar alla relevanta poster som börjar med den angivna strängen
text	sträng	Utför en fulltextsökning av alla poster

Nästa steg

API-autentisering

Om du stöter på problem är vi här för att hjälpa till. Om du vill få hjälp eller support för ditt produktproblem öppnar du ett supportärende.

Dela via