Defender for Cloud Apps REST API

Článek
01/23/2024

Tento článek popisuje, jak používat Defender for Cloud Apps přes HTTPS.

Rozhraní MICROSOFT Defender for Cloud Apps API poskytuje programový přístup k Defenderu for Cloud Apps prostřednictvím koncových bodů rozhraní REST API. Aplikace můžou pomocí rozhraní API provádět operace čtení a aktualizace v defenderu pro data a objekty Cloud Apps. Rozhraní API Defenderu for Cloud Apps například podporuje následující běžné operace pro objekt uživatele:

Nahrání souborů protokolu pro cloud discovery
Generování blokových skriptů
Zobrazení seznamu aktivit a upozornění
Zavření nebo řešení výstrah

Struktura adres URL rozhraní API

Pokud chcete použít rozhraní API Defenderu for Cloud Apps, musíte nejprve získat adresu URL rozhraní API ze svého tenanta. Adresa URL rozhraní API používá následující formát: https://<portal_url>/api/<endpoint>.

Pokud chcete získat adresu URL rozhraní API Služby Defender for Cloud Apps pro vašeho tenanta, postupujte následovně:

Na portálu Microsoft Defender vyberte Nastavení. Pak zvolte Cloud Apps. V části Systém vyberte O produktu.
Na obrazovce Defender for Cloud Apps uvidíte adresu URL rozhraní API.

Jakmile budete mít adresu URL rozhraní API, přidejte k ní příponu /api , abyste získali adresu URL rozhraní API. Pokud je například adresa URL https://mytenant.us2.contoso.comvašeho portálu , adresa URL vašeho rozhraní API je https://mytenant.us2.portal.cloudappsecurity.com/api.

Tokeny rozhraní API

Defender for Cloud Apps vyžaduje token rozhraní API v hlavičce všech požadavků rozhraní API na server, například následující:

Authorization: Token <your_token_key>

Kde <your_token_key> je váš osobní token rozhraní API.

Další informace o tokenech rozhraní API najdete v tématu Správa tokenů rozhraní API.

Tokeny rozhraní API – příklad

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

Jaké akce se podporují?

Následující tabulka popisuje podporované akce:

Prostředek	Příkazy HTTP	Trasy URI
Aktivity	GET nebo POST	/api/v1/activities/
Výstrahy	GET nebo POST	/api/v1/alerts/
Rozšiřování dat	GET, POST nebo DELETE	/api/subnet/
Entity	GET nebo POST	/api/v1/entities/
Soubory	GET nebo POST	/api/v1/files/

Where Resource představuje skupinu souvisejících entit.

Jaké typy polí jsou podporované?

Následující tabulka popisuje podporované typy polí:

Pole	Popis
string	Textový řetězec
boolean	Logická hodnota představující hodnotu true/false
integer	32bitové celé číslo se signedm
časové razítko	Milisekundy od epochy

Časová razítka

Zmínky o časových razítkech v rozhraní API Defenderu for Cloud Apps odkazují na časové razítko unixu v milisekundách. Toto časové razítko je určeno počtem milisekund od roku 1970-01-01 0:00:00. Pomocí rutiny PowerShellu get-date můžete převést data na časová razítka.

Omezení

Své požadavky můžete omezit zadáním parametru limitu v požadavku.

Pro poskytnutí parametru limitu se podporují následující metody:

Kódovaná adresa URL (se záhlavím Content-Type: application/x-www-form-urlencoded )
Data formuláře
Text JSON (s Content-Type: multipart/form-data odpovídající hlavičkou hranice)

Poznámka:

Pokud není zadaný žádný limit, nastaví se výchozí hodnota 100.
Odpovědi na všechny požadavky provedené pomocí tokenu rozhraní API jsou omezené na maximálně 100 položek.
Limit omezení pro všechny požadavky rozhraní API je 30 požadavků za minutu na tenanta.

Filtry

Pokud máte velký počet výsledků, budete moct požadavky vyladit pomocí filtrů. Tato část popisuje strukturu a operátory, které lze použít s filtry.

Struktura

Některé koncové body rozhraní API podporují filtry při provádění dotazů. V příslušných částech najdete odkaz se seznamem všech dostupných filtrovatelných polí a podporovaných operátorů pro daný prostředek.

Většina filtrů podporuje více hodnot, aby vám poskytovala výkonné dotazy. Při kombinování filtrů a operátorů používáme operátor AND jako logický operátor mezi filtry.

Filtry – příklad

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

Operátory

Poznámka:

Ne všechny operátory jsou kompatibilní se všemi filtry.

Následující tabulka popisuje podporované operátory:

Operátor	Typ odpovědi	Popis
obsahuje	seznam řetězců	Vrátí všechny relevantní záznamy obsahující jeden z poskytnutých řetězců.
deq	seznam hodnot	Vrátí všechny záznamy, které obsahují jednu hodnotu, která se nerovná zadané hodnotě.
potomek	seznam hodnot	Vrátí všechny relevantní záznamy odpovídající hodnoty nebo jejich potomky.
doesnotstartwith	seznam řetězců	Vrátí všechny relevantní záznamy, které nezačíná s jednotlivými zadanými řetězci.
endswith	seznam řetězců	Vrátí všechny relevantní záznamy končící jedním z poskytnutých řetězců.
eq	seznam hodnot	Vrátí všechny relevantní záznamy obsahující jednu z zadaných hodnot.
gt	jedna hodnota	Vrátí všechny záznamy, jejichž hodnota je větší než zadaná hodnota.
gte	jedna hodnota	Vrátí všechny záznamy, jejichž hodnota je větší nebo rovna zadané hodnotě.
gte_ndays	Číslo	Vrátí všechny záznamy s datem pozdějším než před N dny.
isnotset	boolean	Pokud je nastavená hodnota true, vrátí všechny relevantní záznamy, které nemají v zadaném poli hodnotu.
isset	boolean	Pokud je nastavená hodnota true, vrátí všechny relevantní záznamy, které mají hodnotu v zadaném poli.
lt	jedna hodnota	Vrátí všechny záznamy, jejichž hodnota je menší než zadaná hodnota.
lte	jedna hodnota	Vrátí všechny záznamy, jejichž hodnota je menší nebo rovna zadané hodnotě.
lte_ndays	Číslo	Vrátí všechny záznamy s datem dřívějším než před N dny.
ncontains	seznam řetězců	Vrátí všechny relevantní záznamy, které neobsahují jeden z poskytnutých řetězců.
ndescendantof	seznam hodnot	Vrátí všechny relevantní záznamy, které neodpovídají hodnotám nebo následníkům.
neq	seznam hodnot	Vrátí všechny relevantní záznamy, které neobsahují všechny zadané hodnoty.
range	seznam objektů obsahujících pole Start a End	Vrátí všechny záznamy v jedné z poskytnutých oblastí.
startswith	seznam řetězců	Vrátí všechny relevantní záznamy začínající jedním ze zadaných řetězců.
startwithsingle	string	Vrátí všechny relevantní záznamy začínající zadaným řetězcem.
text	string	Provede fulltextové vyhledávání všech záznamů.

Další kroky

Ověřování rozhraní API

Pokud narazíte na nějaké problémy, jsme tady, abychom vám pomohli. Pokud chcete získat pomoc nebo podporu k problému s produktem, otevřete lístek podpory.

Sdílet prostřednictvím