DEFENDER VOOR CLOUD APPS REST API

  • Artikel
  • 5 minuten om te lezen

Notitie

We hebben de naam van Microsoft Cloud App Security gewijzigd. Het heet nu Microsoft Defender for Cloud Apps. In de komende weken worden de schermafbeeldingen en instructies hier en op gerelateerde pagina's bijgewerkt. Zie deze aankondiging voor meer informatie over de wijziging. Zie het Microsoft Ignite Security-blog voor meer informatie over de recente hernoeming van Microsoft-beveiligingsservices.

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

De Microsoft Defender for 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 voor Cloud Discovery Upload
  • Blokscripts genereren
  • Activiteiten en waarschuwingen weergeven
  • Waarschuwingen sluiten of oplossen

API URL-structuur

Als u de API voor Defender voor Cloud Apps wilt gebruiken, moet u eerst de API-URL van uw tenant verkrijgen. De API-URL maakt gebruik van de volgende indeling: https://<portal_url>/api/<endpoint>.

Voer de volgende stappen uit om de URL van de Defender voor Cloud Apps-portal voor uw tenant op te halen:

  1. Selecteer in de Defender voor Cloud Apps-portal het vraagtekenpictogram in de menubalk. Selecteer Vervolgens Info.

    Select About.

  2. In het scherm Defender voor Cloud Apps over het scherm ziet u de URL van de portal.

    View your data center.

Zodra u de portal-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.contoso.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.

Voorbeeld

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

Welke acties worden ondersteund?

In de volgende tabel worden de ondersteunde acties beschreven:

Resource HTTP-woorden URI-routes
Activiteiten GET of POST /api/v1/activities/
Waarschuwingen GET of POST /api/v1/alerts/
Cloud Discovery GET, POST of PUT /api/v1/discovery/
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 Description
tekenreeks Een teksttekenreeks
booleaans Een Booleaanse waarde die waar/onwaar vertegenwoordigt
geheel getal 32-bits ondertekend geheel getal
tijdstempel Milliseconden sinds epoch

Timestamps

Vermeldingen van tijdstempels in de DEFENDER VOOR CLOUD Apps-API verwijzen naar de Unix-tijdstempel in milliseconden. Dit 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.

Limieten

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

De volgende methoden worden ondersteund om de parameter limiet 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 is opgegeven, wordt een standaardwaarde van 100 ingesteld.
  • Antwoorden voor alle aanvragen die met het API-token zijn 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 beschreven van en operators 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.

Voorbeeld

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.contoso.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 Antwoordtype Description
bevat lijst met tekenreeksen Retourneert alle relevante records die een van de opgegeven tekenreeksen bevatten
deq lijst met waarden Geeft als resultaat 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
endswith lijst met tekenreeksen Retourneert alle relevante records die eindigen op een van de opgegeven tekenreeksen
eq lijst met waarden Geeft als resultaat alle relevante records die een van de opgegeven waarden bevatten
Gt enkele waarde Geeft als resultaat alle records waarvan de waarde groter is dan de opgegeven waarde
Gte enkele waarde Geeft als resultaat alle records waarvan de waarde groter is dan of gelijk is aan de opgegeven waarde
gte_ndays getal Retourneert alle records met datum later dan N dagen geleden
isnotset booleaans Als deze optie is ingesteld op 'true', worden alle relevante records geretourneerd die geen waarde hebben in het opgegeven veld
Isset booleaans Als deze optie is ingesteld op 'true', worden alle relevante records geretourneerd met een waarde in het opgegeven veld
lt enkele waarde Geeft als resultaat alle records waarvan de waarde kleiner is dan de opgegeven waarde
Lte enkele waarde Geeft als resultaat alle records waarvan de waarde kleiner is dan of gelijk is aan de opgegeven waarde
lte_ndays getal Retourneert alle records met datum ouder 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
Bereik lijst met objecten met velden 'begin' en 'eind'. 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
tekst 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.