Defender for Cloud Apps REST API

Artikel
11/28/2024

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

MICROSOFT DEFENDER FOR CLOUD APPS-API:et 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å Defender for Cloud Apps data och objekt. Till exempel stöder Defender for Cloud Apps-API:et följande vanliga åtgärder för ett användarobjekt:

Ladda upp loggfiler för molnidentifiering
Generera blockskript
Lista aktiviteter och aviseringar
Stäng eller lösa aviseringar

API-URL-struktur

Om du vill använda Defender for Cloud Apps-API:et 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 Defender for Cloud Apps API-URL:en 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 for Cloud Apps om kan du se API-URL:en.

När du har API-URL:en lägger du till suffixet /api 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/apiDIN API-URL .

API-token

Defender for Cloud Apps kräver en API-token i huvudet 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
Verksamhet	GET eller POST	/api/v1/activities/
Varningar	GET eller POST	/api/v1/alerts/
Databerikning	GET, POST eller DELETE	/api/undernät/
Enheter	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
boolesk	Ett booleskt värde som representerar sant/falskt
heltal	32-bitars signerat heltal
Tidsstämpel	Millisekunder sedan epoken

Tidsstämplar

Omnämnanden av tidsstämplar i Defender for Cloud Apps-API:et 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)

Obs!

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 användbart att finjustera begäranden med hjälp av filter. I det här avsnittet beskrivs strukturen för och operatorerna som kan användas med filter.

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

Operatörer

Obs!

Alla operatorer är inte kompatibla med alla filter.

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

Operatör	Svarstyp	Beskrivning
Innehåller	lista över strängar	Returnerar alla relevanta poster som innehåller en av de angivna strängarna
deq	lista över värden	Returnerar alla poster som innehåller ett värde som inte är lika med ett angivet värde
descendantof	lista över värden	Returnerar alla relevanta poster som matchar värden eller underordnade till dem
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 över 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	boolesk	När värdet är "true" returneras alla relevanta poster som inte har något värde i det angivna fältet
isset	boolesk	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 ett tidigare datum än för 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 över värden	Returnerar alla relevanta poster som inte matchar värden eller underordnade till dem
neq	lista över värden	Returnerar alla relevanta poster som inte innehåller alla angivna värden
sortiment	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
SMS	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 ha hjälp eller support för ditt produktproblem öppnar du ett supportärende.

Dela via