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 Cloud Discovery
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/
Files	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