API REST di Defender for Cloud Apps

Articolo
11/28/2024

Questo articolo descrive come interagire con Defender for Cloud Apps tramite HTTPS.

L'API Microsoft Defender for Cloud Apps consente l'accesso a livello di codice ai Defender for Cloud Apps tramite gli endpoint dell'API REST. Le applicazioni possono usare l'API per eseguire operazioni di lettura e aggiornamento su dati e oggetti Defender for Cloud Apps. Ad esempio, l'API Defender for Cloud Apps supporta le operazioni comuni seguenti per un oggetto utente:

Caricare i file di log per l'individuazione cloud
Generare script in blocchi
Elencare attività e avvisi
Ignorare o risolvere gli avvisi

Struttura dell'URL dell'API

Per usare l'API Defender for Cloud Apps, è prima necessario ottenere l'URL dell'API dal tenant. L'URL API usa il formato seguente: https://<portal_url>/api/<endpoint>.

Per ottenere l'URL dell'API Defender for Cloud Apps per il tenant, seguire questa procedura:

Nel portale Microsoft Defender selezionare Impostazioni. Scegliere quindi App cloud. In Sistema selezionare Informazioni.
Nella schermata Defender for Cloud Apps informazioni su è possibile visualizzare l'URL dell'API.

Dopo aver ottenuto l'URL dell'API, aggiungervi il /api suffisso per ottenere l'URL dell'API. Ad esempio, se l'URL del portale è https://mytenant.us2.contoso.com, l'URL DELL'API è https://mytenant.us2.portal.cloudappsecurity.com/api.

Token API

Defender for Cloud Apps richiede un token API nell'intestazione di tutte le richieste API al server, ad esempio:

Authorization: Token <your_token_key>

Dove <your_token_key> si trova il token API personale.

Per altre informazioni sui token API, vedere Gestione dei token API.

Token API - esempio

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

Quali azioni sono supportate?

Nella tabella seguente vengono descritte le azioni supportate:

Risorsa	Verbi HTTP	Route URI
Attività	GET o POST	/api/v1/activities/
Avvisi	GET o POST	/api/v1/alerts/
Arricchimento dei dati	GET, POST o DELETE	/api/subnet/
Entità	GET o POST	/api/v1/entities/
File	GET o POST	/api/v1/files/

Dove Risorsa rappresenta un gruppo di entità correlate.

Quali tipi di campo sono supportati?

Nella tabella seguente vengono descritti i tipi di campo supportati:

Campo	Descrizione
stringa	Stringa testuale
booleano	Valore booleano che rappresenta true/false
integer	Intero con segno a 32 bit
Timestamp	Millisecondi dall'epoca

Timestamp

Le menzioni dei timestamp nell'API Defender for Cloud Apps fanno riferimento al timestamp Unix in millisecondi. Questo timestamp è determinato dal numero di millisecondi dal 1970-01-01 0:00:00. È possibile usare il cmdlet di PowerShell get-date per convertire le date in timestamp.

Limiti

È possibile scegliere di limitare le richieste specificando un parametro limite nella richiesta.

Per fornire il parametro limit sono supportati i metodi seguenti:

Codificato con URL (con Content-Type: application/x-www-form-urlencoded intestazione)
Dati moduli
Corpo JSON (con Content-Type: multipart/form-data e un'intestazione di limite appropriata)

Nota

Se non viene specificato alcun limite, verrà impostato un valore predefinito pari a 100.
Le risposte per tutte le richieste effettuate con il token API sono limitate a un massimo di 100 elementi.
Il limite di limitazione per tutte le richieste API è di 30 richieste al minuto per ogni tenant.

Filtri

Quando si ha un numero elevato di risultati, sarà utile ottimizzare le richieste usando i filtri. Questa sezione descrive la struttura degli operatori e che possono essere usati con i filtri.

Struttura

Alcuni degli endpoint API supportano i filtri durante l'esecuzione di query. Nelle sezioni pertinenti è disponibile un riferimento che elenca tutti i campi filtrabili disponibili e gli operatori supportati per tale risorsa.

La maggior parte dei filtri supporta più valori per fornire query avanzate. Quando si combinano filtri e operatori, viene usato AND come operatore logico tra i filtri.

Filtri - esempio

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

Operatori

Nota

Non tutti gli operatori sono compatibili con tutti i filtri.

Nella tabella seguente vengono descritti gli operatori supportati:

Operatore	Tipo di risposta	Descrizione
Contiene	elenco di stringhe	Restituisce tutti i record rilevanti contenenti una delle stringhe specificate
deq	elenco di valori	Restituisce tutti i record che contengono un valore diverso da uno dei valori specificati
discendente	elenco di valori	Restituisce tutti i record pertinenti corrispondenti a valori o discendenti di essi
doesnotstartwith	elenco di stringhe	Restituisce tutti i record rilevanti che non iniziano con ognuna delle stringhe specificate
endswith	elenco di stringhe	Restituisce tutti i record rilevanti che terminano con una delle stringhe specificate
Eq	elenco di valori	Restituisce tutti i record rilevanti contenenti uno dei valori specificati
Gt	valore singolo	Restituisce tutti i record il cui valore è maggiore del valore specificato
Gte	valore singolo	Restituisce tutti i record il cui valore è maggiore o uguale al valore specificato
gte_ndays	numero	Restituisce tutti i record con data successiva a N giorni fa
isnotset	booleano	Se impostato su "true", restituisce tutti i record rilevanti che non hanno un valore nel campo specificato
isset	booleano	Se impostato su "true", restituisce tutti i record rilevanti con un valore nel campo specificato
lt	valore singolo	Restituisce tutti i record il cui valore è minore del valore specificato
lte	valore singolo	Restituisce tutti i record il cui valore è minore o uguale al valore specificato
lte_ndays	numero	Restituisce tutti i record con data precedente a N giorni fa
ncontains	elenco di stringhe	Restituisce tutti i record rilevanti che non contengono una delle stringhe specificate
ndescendantof	elenco di valori	Restituisce tutti i record rilevanti che non corrispondono a valori o discendenti di essi
neq	elenco di valori	Restituisce tutti i record rilevanti che non contengono tutti i valori specificati
gamma	elenco di oggetti contenenti i campi "start" e "end"	Restituisce tutti i record all'interno di uno degli intervalli specificati
startswith	elenco di stringhe	Restituisce tutti i record rilevanti a partire da una delle stringhe specificate
startswithsingle	stringa	Restituisce tutti i record rilevanti a partire dalla stringa specificata
Testo	stringa	Esegue una ricerca full-text di tutti i record

Passaggi successivi

Autenticazione API

Se si verificano problemi, siamo qui per aiutarti. Per ottenere assistenza o supporto per il problema del prodotto, aprire un ticket di supporto.

Condividi tramite