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 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:

Resource	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
string	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.

Filtra

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