Defender for Cloud Apps REST API

Artikel
11/28/2024

I denne artikel beskrives det, hvordan du interagerer med Defender for Cloud Apps via HTTPS.

MICROSOFT DEFENDER FOR CLOUD APPS-API'en giver programmatisk adgang til Defender for Cloud Apps via REST API-slutpunkter. Programmer kan bruge API'en til at udføre læse- og opdateringshandlinger på Defender for Cloud Apps data og objekter. Den Defender for Cloud Apps API understøtter f.eks. følgende almindelige handlinger for et brugerobjekt:

Overfør logfiler til registrering i skyen
Generér blokscripts
Vis aktiviteter og beskeder
Afvis eller løs beskeder

STRUKTUR FOR API-URL-adresse

Hvis du vil bruge API'en Defender for Cloud Apps, skal du først hente API-URL-adressen fra din lejer. URL-adressen til API'en har følgende format: https://<portal_url>/api/<endpoint>.

Benyt følgende fremgangsmåde for at hente URL-adressen til Defender for Cloud Apps-API'en for din lejer:

Vælg Indstillinger i Microsoft Defender Portal. Vælg derefter Cloud Apps. Under System skal du vælge Om.
I Defender for Cloud Apps om skærmen kan du se API-URL-adressen.

Når du har URL-adressen til API'en, skal du føje suffikset /api til den for at få DIN API-URL-adresse. Hvis portalens URL-adresse f.eks. er https://mytenant.us2.contoso.com, er https://mytenant.us2.portal.cloudappsecurity.com/apiDIN API-URL-adresse .

API-tokens

Defender for Cloud Apps kræver et API-token i headeren for alle API-anmodninger til serveren, f.eks. følgende:

Authorization: Token <your_token_key>

Hvor <your_token_key> er dit personlige API-token.

Du kan få flere oplysninger om API-tokens under Administration af API-tokens.

API-tokens – eksempel

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

Hvilke handlinger understøttes?

I følgende tabel beskrives de handlinger, der understøttes:

Ressource	HTTP-verber	URI-ruter
Aktiviteter	GET eller POST	/api/v1/activities/
Beskeder	GET eller POST	/api/v1/alerts/
Dataforbedring	GET, POST eller DELETE	/api/undernet/
Enheder	GET eller POST	/api/v1/entities/
ﬁler	GET eller POST	/api/v1/files/

Hvor Ressourcen repræsenterer en gruppe relaterede objekter.

Hvilke felttyper understøttes?

I følgende tabel beskrives de understøttede felttyper:

Mark	Beskrivelse
streng	En tekststreng
Boolesk	En boolesk værdi, der repræsenterer true/false
heltal	32-bit heltal med fortegn
tidsstempel	Millisekunder siden epoken

Tidsstempler

Omtale af tidsstempler i API'en for Defender for Cloud Apps refererer til Unix-tidsstemplet i millisekunder. Dette tidsstempel bestemmes af antallet af millisekunder siden 1970-01-01 0:00:00. Du kan bruge PowerShell-cmdlet'en hent dato til at konvertere datoer til tidsstempler.

Grænser

Du kan vælge at begrænse dine anmodninger ved at angive en grænseparameter i anmodningen.

Følgende metoder understøttes til angivelse af grænseparameteren:

URL-kodet (med Content-Type: application/x-www-form-urlencoded header)
Formulardata
JSON-brødtekst (med Content-Type: multipart/form-data og en passende grænseoverskrift)

Bemærk!

Hvis der ikke er angivet en grænse, angives standarden 100.
Svar på alle anmodninger, der er foretaget med API-tokenet, er begrænset til maksimalt 100 elementer.
Begrænsningsgrænsen for alle API-anmodninger er 30 anmodninger pr. minut pr. lejer.

Filtre

Når du har et stort antal resultater, kan du finde det nyttigt at finjustere anmodninger ved hjælp af filtre. I dette afsnit beskrives strukturen af og de operatorer, der kan bruges sammen med filtre.

Struktur

Nogle af vores API-slutpunkter understøtter filtre, når der udføres forespørgsler. I deres relevante afsnit finder du en reference, der viser alle tilgængelige felter, der kan filtreres, og understøttede operatorer for den pågældende ressource.

De fleste filtre understøtter flere værdier for at give dig effektive forespørgsler. Når vi kombinerer filtre og operatorer, bruger vi AND som den logiske operator mellem filtrene.

Filtre – eksempel

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

Bemærk!

Ikke alle operatorer er kompatible med alle filtre.

I følgende tabel beskrives de understøttede operatorer:

Operatør	Svartype	Beskrivelse
Indeholder	liste over strenge	Returnerer alle relevante poster, der indeholder en af de angivne strenge
deq	liste over værdier	Returnerer alle poster, der indeholder én værdi, som ikke er lig med en af de angivne værdier
underordnet af	liste over værdier	Returnerer alle relevante poster, der stemmer overens med værdier eller underordnede værdier for dem
ikke startes med	liste over strenge	Returnerer alle relevante poster, der ikke starter med hver af de angivne strenge
endswith	liste over strenge	Returnerer alle relevante poster, der slutter med en af de angivne strenge
Eq	liste over værdier	Returnerer alle relevante poster, der indeholder en af de angivne værdier
Gt	enkelt værdi	Returnerer alle poster, hvis værdi er større end den angivne værdi
Gte	enkelt værdi	Returnerer alle poster, hvis værdi er større end eller lig med den angivne værdi
gte_ndays	tal	Returnerer alle poster med en dato, der er senere end N dage siden
isnotset	Boolesk	Når den er angivet til "true", returneres alle relevante poster, der ikke har en værdi i det angivne felt
isset	Boolesk	Når den er angivet til "true", returneres alle relevante poster, der har en værdi i det angivne felt
lt	enkelt værdi	Returnerer alle poster, hvis værdi er mindre end den angivne værdi
lte	enkelt værdi	Returnerer alle poster, hvis værdi er mindre end eller lig med den angivne værdi
lte_ndays	tal	Returnerer alle poster med en dato, der er tidligere end N dage siden
ncontains	liste over strenge	Returnerer alle relevante poster, der ikke indeholder en af de angivne strenge
ndescendantof	liste over værdier	Returnerer alle relevante poster, der ikke stemmer overens med værdier eller underordnede værdier for dem
neq	liste over værdier	Returnerer alle relevante poster, der ikke indeholder alle de angivne værdier
interval	liste over objekter, der indeholder felterne "start" og "end"	Returnerer alle poster inden for et af de angivne områder
startswith	liste over strenge	Returnerer alle relevante poster, der starter med en af de angivne strenge
starter med	streng	Returnerer alle relevante poster, der starter med den angivne streng
Tekst	streng	Udfører en fuldtekstsøgning af alle poster

Næste trin

API-godkendelse

Hvis du støder på problemer, er vi her for at hjælpe. Hvis du vil have hjælp eller support til dit produktproblem, skal du åbne en supportanmodning.

Del via