Defender for Cloud Apps REST API

Artikel
11/28/2024

In dit artikel wordt beschreven hoe u via HTTPS met Defender for Cloud Apps communiceert.

De Microsoft Defender for Cloud Apps-API biedt programmatische toegang tot Defender for Cloud Apps via REST API-eindpunten. Toepassingen kunnen de API gebruiken om lees- en updatebewerkingen uit te voeren op Defender for Cloud Apps gegevens en objecten. De Defender for 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 for Cloud Apps-API wilt gebruiken, moet u eerst de API-URL van uw tenant ophalen. De API-URL gebruikt de volgende indeling: https://<portal_url>/api/<endpoint>.

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

Selecteer instellingen in de Microsoft Defender Portal. Kies vervolgens Cloud-apps. Selecteer onder Systeemde optie Info.
In het scherm Defender for 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 op te halen. 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 for Cloud Apps vereist een API-token in de header van alle API-aanvragen naar de server, zoals het volgende:

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:

Resource	HTTP-werkwoorden	URI-routes
Activiteiten	GET of POST	/api/v1/activities/
Waarschuwingen	GET of POST	/api/v1/alerts/
Gegevensverrijking	OPHALEN, POSTEN of VERWIJDEREN	/api/subnet/
Entiteiten	GET of POST	/api/v1/entities/
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
booleaans	Een Booleaanse waarde die waar/onwaar vertegenwoordigt
geheel getal	32-bits ondertekend geheel getal
tijdstempel	Milliseconden sinds epoch

Tijdstempels

Vermeldingen van tijdstempels in de Defender for 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 PowerShell-cmdlet get-date gebruiken om datums te converteren naar tijdstempels.

Grens

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

De volgende methoden worden ondersteund voor het opgeven van de limietparameter:

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

Opmerking

Als er geen limiet wordt opgegeven, wordt de standaardwaarde 100 ingesteld.
Antwoorden voor alle aanvragen die met het API-token worden gedaan, 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 van en-operators beschreven die kunnen worden gebruikt met filters.

Structuur

Sommige van onze 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
}'

Exploitanten

Opmerking

Niet alle operators zijn compatibel met alle filters.

In de volgende tabel worden de ondersteunde operators beschreven:

Bediener	Antwoordtype	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
descendantvan	lijst met waarden	Retourneert alle relevante records die overeenkomen met waarden of afstammelingen ervan
doesnotstartwith	lijst met tekenreeksen	Retourneert alle relevante records die niet beginnen met elk van de opgegeven tekenreeksen
endswith	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	getal	Retourneert alle records met een datum later dan N dagen geleden
isnotset	booleaans	Wanneer deze optie is ingesteld op 'true', worden alle relevante records geretourneerd die geen waarde in het opgegeven veld hebben
isset	booleaans	Wanneer deze optie is ingesteld op 'true', worden alle relevante records geretourneerd die een waarde in het opgegeven veld hebben
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	getal	Retourneert alle records met een datum eerder 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 ervan
neq	lijst met waarden	Retourneert alle relevante records die niet alle opgegeven waarden bevatten
bereik	lijst met objecten die de velden 'start' en 'end' 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	reeks	Een zoekopdracht in volledige tekst van alle records uitvoeren

Volgende stappen

API-verificatie

Als u problemen ondervindt, zijn wij er om u te helpen. Open een ondersteuningsticket om hulp of ondersteuning te krijgen voor uw productprobleem.

Delen via