API REST delle app Defender per il cloud

Articolo
01/23/2024

Questo articolo descrive come interagire con le app Defender per il cloud tramite HTTPS.

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

Caricare i file di log per Cloud Discovery
Generare script di blocco
Elencare attività e avvisi
Chiudere o risolvere gli avvisi

Struttura DELL'URL DELL'API

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

Per ottenere l'URL dell'API delle app di Defender per il cloud per il tenant, seguire questa procedura:

Nel portale di Microsoft Defender selezionare Impostazioni. Scegliere quindi App cloud. In Sistema selezionare Informazioni su.
Nella schermata Defender per il cloud Apps about (App di Defender per il cloud) è possibile visualizzare l'URL dell'API.

Dopo aver ottenuto l'URL dell'API, aggiungere il suffisso per ottenere l'URL /api 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 per il cloud Le app richiedono un token API nell'intestazione di tutte le richieste API al server, ad esempio:

Authorization: Token <your_token_key>

Dove <your_token_key> è il token DELL'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:

Conto risorse	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 Resource 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
boolean	Valore booleano che rappresenta true/false
integer	Intero con segno a 32 bit
timestamp	Millisecondi dall'epoca

Timestamp

Le menzioni dei timestamp nell'API delle app Defender per il cloud 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 PowerShell get-date per convertire le date in timestamp.

Limiti

È possibile scegliere di limitare le richieste fornendo 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 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 dispone di un numero elevato di risultati, è utile ottimizzare le richieste usando filtri. Questa sezione descrive la struttura degli operatori e che possono essere usati con filtri.

Struttura

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

La maggior parte dei filtri supporta più valori per offrire query avanzate. Quando si combinano filtri e operatori si usa 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.

La tabella seguente descrive gli operatori supportati:

Operatore	Tipo di risposta	Descrizione
contains	Elenco di stringhe	Restituisce tutti i record pertinenti contenenti una delle stringhe specificate
deq	elenco di valori	Restituisce tutti i record che contengono un valore diverso da uno dei valori forniti
descendantof	elenco di valori	Restituisce tutti i record pertinenti corrispondenti a valori o discendenti di essi
doesnotstartwith	Elenco di stringhe	Restituisce tutti i record pertinenti che non iniziano con ognuna delle stringhe specificate
finisce con	Elenco di stringhe	Restituisce tutti i record pertinenti che terminano con una delle stringhe specificate
eq	elenco di valori	Restituisce tutti i record pertinenti contenenti uno dei valori forniti
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	number	Restituisce tutti i record con data successiva a N giorni fa
isnotset	boolean	Se impostato su "true", restituisce tutti i record pertinenti che non hanno un valore nel campo specificato
isset	boolean	Se impostato su "true", restituisce tutti i record pertinenti 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	number	Restituisce tutti i record con data precedente a N giorni fa
ncontains	Elenco di stringhe	Restituisce tutti i record pertinenti che non contengono una delle stringhe specificate
ndescendantof	elenco di valori	Restituisce tutti i record pertinenti che non corrispondono a valori o discendenti di essi
neq	elenco di valori	Restituisce tutti i record pertinenti che non contengono tutti i valori forniti
range	elenco di oggetti contenenti campi "start" e "end"	Restituisce tutti i record all'interno di uno degli intervalli specificati
startswith	Elenco di stringhe	Restituisce tutti i record pertinenti a partire da una delle stringhe specificate
startswithsingle	string	Restituisce tutti i record pertinenti a partire dalla stringa specificata
Testo	string	Esegue una ricerca full-text di tutti i record

Passaggi successivi

Autenticazione API

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

Condividi tramite