REST API voor Defender voor Cloud-apps

Artikel
01/23/2024

In dit artikel wordt beschreven hoe u kunt communiceren met Defender voor Cloud-apps via HTTPS.

De MICROSOFT DEFENDER VOOR CLOUD Apps-API biedt programmatische toegang tot Defender voor Cloud Apps via REST API-eindpunten. Toepassingen kunnen de API gebruiken om lees- en updatebewerkingen uit te voeren op Defender voor Cloud Apps-gegevens en -objecten. De DEFENDER VOOR CLOUD Apps-API ondersteunt bijvoorbeeld de volgende algemene bewerkingen voor een gebruikersobject:

Logboekbestanden uploaden voor clouddetectie
Blokscripts genereren
Activiteiten en waarschuwingen weergeven
Waarschuwingen sluiten of oplossen

API-URL-structuur

Als u de DEFENDER VOOR CLOUD Apps-API wilt gebruiken, moet u eerst de API-URL van uw tenant verkrijgen. De API-URL gebruikt de volgende indeling: https://<portal_url>/api/<endpoint>.

Voer de volgende stappen uit om de API-URL van Defender voor Cloud Apps voor uw tenant te verkrijgen:

Selecteer Instellingen in de Microsoft Defender-portal. Kies vervolgens Cloud Apps. Selecteer Onder Systeem de optie Info.
In het scherm Defender voor Cloud Apps over, ziet u de API-URL.

Zodra u de API-URL hebt, voegt u het /api achtervoegsel eraan toe om uw API-URL te verkrijgen. Als de URL van uw portal bijvoorbeeld is https://mytenant.us2.contoso.com, is https://mytenant.us2.portal.cloudappsecurity.com/apiuw API-URL.

API-tokens

Defender voor Cloud Apps vereist een API-token in de header van alle API-aanvragen naar de server, zoals:

Authorization: Token <your_token_key>

Waar <your_token_key> is uw persoonlijke API-token.

Zie API-tokens beheren voor meer informatie over API-tokens.

API-tokens - voorbeeld

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

Welke acties worden ondersteund?

In de volgende tabel worden de ondersteunde acties beschreven:

Bron	HTTP-woorden	URI-routes
Activiteiten	GET of POST	/api/v1/activities/
Waarschuwingen	GET of POST	/api/v1/alerts/
Gegevensverrijking	GET, POST of DELETE	/api/subnet/
Entiteiten	GET of POST	/api/v1/entiteiten/
Bestanden	GET of POST	/api/v1/files/

Waarbij Resource een groep gerelateerde entiteiten vertegenwoordigt.

Welke veldtypen worden ondersteund?

In de volgende tabel worden de ondersteunde veldtypen beschreven:

Veld	Beschrijving
tekenreeks	Een tekstuele tekenreeks
boolean	Een Booleaanse waarde die waar/onwaar vertegenwoordigt
geheel getal	32-bits geheel getal ondertekend
timestamp	Milliseconden sinds epoch

Timestamps

Vermeldingen van tijdstempels in de DEFENDER VOOR CLOUD Apps-API verwijzen naar de Unix-tijdstempel in milliseconden. Deze tijdstempel wordt bepaald door het aantal milliseconden sinds 1970-01-01 0:00:00. U kunt de cmdlet get-date PowerShell gebruiken om datums te converteren naar tijdstempels.

Limieten

U kunt ervoor kiezen om uw aanvragen te beperken door een limietparameter op te geven in de aanvraag.

De volgende methoden worden ondersteund om de limietparameter op te geven:

URL-gecodeerd (met Content-Type: application/x-www-form-urlencoded header)
Formuliergegevens
JSON-hoofdtekst (met Content-Type: multipart/form-data en een geschikte grensheader)

Notitie

Als er geen limiet wordt opgegeven, wordt een standaardwaarde van 100 ingesteld.
Antwoorden voor alle aanvragen die zijn gedaan met het API-token, zijn beperkt tot maximaal 100 items.
De beperkingslimiet voor alle API-aanvragen is 30 aanvragen per minuut per tenant.

Filters

Wanneer u een groot aantal resultaten hebt, is het handig om aanvragen af te stemmen met behulp van filters. In deze sectie wordt de structuur beschreven van en operators die kunnen worden gebruikt met filters.

Structuur

Sommige api-eindpunten ondersteunen filters bij het uitvoeren van query's. In de relevante secties vindt u een verwijzing met alle beschikbare filterbare velden en ondersteunde operators voor die resource.

De meeste filters ondersteunen meerdere waarden om u krachtige query's te bieden. Bij het combineren van filters en operators gebruiken we AND als logische operator tussen de filters.

Filters - voorbeeld

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

Operators

Notitie

Niet alle operators zijn compatibel met alle filters.

In de volgende tabel worden de ondersteunde operators beschreven:

Operator	Reactietype	Beschrijving
bevat	lijst met tekenreeksen	Retourneert alle relevante records die een van de opgegeven tekenreeksen bevatten
deq	lijst met waarden	Retourneert alle records die één waarde bevatten die niet gelijk is aan één van de opgegeven waarden
afstammeling van	lijst met waarden	Retourneert alle relevante records die overeenkomen met waarden of afstammelingen van deze records
doesnotstartwith	lijst met tekenreeksen	Retourneert alle relevante records die niet beginnen met elk van de opgegeven tekenreeksen
eindigt op	lijst met tekenreeksen	Retourneert alle relevante records die eindigen op een van de opgegeven tekenreeksen
eq	lijst met waarden	Retourneert alle relevante records die een van de opgegeven waarden bevatten
gt	enkele waarde	Retourneert alle records waarvan de waarde groter is dan de opgegeven waarde
gte	enkele waarde	Retourneert alle records waarvan de waarde groter is dan of gelijk is aan de opgegeven waarde
gte_ndays	Nummer	Retourneert alle records met een datum later dan N dagen geleden
isnotset	boolean	Als deze waarde is ingesteld op 'true', worden alle relevante records geretourneerd die geen waarde hebben in het opgegeven veld
isset	boolean	Als deze waarde is ingesteld op 'true', worden alle relevante records geretourneerd met een waarde in het opgegeven veld
lt	enkele waarde	Retourneert alle records waarvan de waarde kleiner is dan de opgegeven waarde
lte	enkele waarde	Retourneert alle records waarvan de waarde kleiner is dan of gelijk is aan de opgegeven waarde
lte_ndays	Nummer	Retourneert alle records met een datum die ouder is dan N dagen geleden
ncontains	lijst met tekenreeksen	Retourneert alle relevante records die geen van de opgegeven tekenreeksen bevatten
ndescendantof	lijst met waarden	Retourneert alle relevante records die niet overeenkomen met waarden of afstammelingen van deze records
neq	lijst met waarden	Retourneert alle relevante records die niet alle opgegeven waarden bevatten
range	lijst met objecten die velden 'begin' en 'eind' bevatten	Retourneert alle records binnen een van de opgegeven bereiken
startswith	lijst met tekenreeksen	Retourneert alle relevante records die beginnen met een van de opgegeven tekenreeksen
startswithsingle	tekenreeks	Retourneert alle relevante records die beginnen met de opgegeven tekenreeks
sms verzenden	tekenreeks	Voert een zoekopdracht in volledige tekst uit van alle records

Volgende stappen

API-verificatie

Als u problemen ondervindt, zijn we hier om u te helpen. Als u hulp of ondersteuning voor uw productprobleem wilt krijgen, opent u een ondersteuningsticket.

Delen via