Sommario

Introduzione

Prerequisiti

Requisiti

Componenti usati

Premesse

Test iniziale

Struttura dei dati

Verificare i risultati utilizzando sia la GUI che l'API

Test iniziale con CURL

Recupera tutti i messaggi

Verifica conteggio totale

ID filtro per dominio

Filtra MID e crea payload

Esecuzione della release (POST)

Verifica dei risultati

Controllo dei log di posta

Controllo diretto nella GUI

Controllo tramite API

Postino

ARRICCIATURA

Rilascio in blocco messaggi (500 messaggi)

Adeguamento dei parametri API per le operazioni di massa

Ridimensionamento del flusso di lavoro

Informazioni correlate

Introduzione

In questo documento viene descritto come automatizzare la gestione e il rilascio dei messaggi su uno SMA Cisco tramite l'API REST per elaborare grandi volumi di messaggi.

Prerequisiti

Requisiti

Cisco raccomanda la conoscenza dei seguenti argomenti:

- Conoscenze dei prodotti Cisco SMA

- Familiarità con API REST, Postman, Curl e JQ per l'elaborazione JSON

- Credenziali valide per l'accesso API SMA

- Riga di comando

- Accesso di rete all'SMA

- Strumenti installati: curl (per le richieste), JQ (per la manipolazione JSON) e un client come Postman per il test iniziale

- Ruolo utente appropriato nell'SMA per eseguire le azioni di rilascio del messaggio

Componenti usati

Il documento può essere consultato per tutte le versioni software o hardware.

Le informazioni discusse in questo documento fanno riferimento a dispositivi usati in uno specifico ambiente di emulazione. Su tutti i dispositivi menzionati nel documento la configurazione è stata ripristinata ai valori predefiniti. Se la rete è operativa, valutare attentamente eventuali conseguenze derivanti dall'uso dei comandi.

Premesse

L'automazione del rilascio dei messaggi è essenziale per gli ambienti con un elevato volume di e-mail. Utilizzando l'API, gli amministratori possono filtrare messaggi specifici (ad esempio, per mittente) e rilasciarli a livello di programmazione, riducendo il tempo operativo e il rischio di errore umano rispetto alla gestione manuale nell'interfaccia utente.

Test iniziale

Per gestire la quarantena, eseguire una query iniziale per verificare la connettività e confermare la struttura dei dati.

https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages?quarantineType=pvo&quarantines=TEST_QUARANTINE&limit=25&offset=0&orderBy=received&orderDir=desc&startDate=2026-03-15T00:00:00.000Z&endDate=2026-03-16T00:00:00.000Z

Struttura dei dati

- Endpoint API: L'URL di base per l'API SMA (ad esempio, https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages).

- Nome quarantena: L'identificatore di quarantena specifico di PVO (ad esempio, TEST_QUARANTINE) da cui si intende recuperare i messaggi.

- Intervallo di date: StartDate e endDate utilizzati per definire l'intervallo di tempo specifico per la ricerca.

- Limite: Numero massimo di record da restituire in una singola risposta API. In questo modo è possibile gestire le dimensioni del payload e impedire timeout durante code di grandi dimensioni.

- Scostamento: Indice iniziale del set di risultati. È usato per l'impaginazione; se ad esempio si imposta un valore di offset pari a 25, i primi 25 messaggi verranno ignorati e sarà possibile recuperare il batch di risultati successivo.

Verificare i risultati utilizzando sia la GUI che l'API

Quando si recuperano le informazioni, è possibile visualizzare la stessa quantità di messaggi nella chiamata API e nella GUI.

richiesta GET postman

Messaggi TEST_QUARANTINE

Test iniziale con CURL

Generare il token di autenticazione Base64 per l'intestazione dell'autorizzazione:

echo -n 'username:password' | base64

Recupera tutti i messaggi

Eseguire la richiesta curl per estrarre i messaggi in un file locale:

curl -X GET "https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages?quarantineType=pvo&quarantines=TEST_QUARANTINE&limit=25&offset=0&orderBy=received&orderDir=desc&startDate=2026-03-15T00:00:00.000Z&endDate=2026-03-16T00:00:00.000Z" \

-H "Authorization: Basic token-generated-in-base64" \

-H "Accept: application/json" \

-o response.json

Verifica conteggio totale

Verifica il numero totale di messaggi ricevuti:

$ grep "totalCount" response.json | awk '{ print $2, $3}'

{"totalCount": 24},

ID filtro per dominio

Utilizzare JQ per filtrare i MID dei messaggi che si desidera rilasciare (ad esempio, filtrando per dominio).

$ jq '[.data[] | select(.attributes.sender | endswith("@labcisco.com")) | .mid]' response.json > mids-labcisco-domain.json

$ cat mids-labcisco-domain.json

[

440,

439,

438,

437,

436,

435,

434,

433,

425,

414

]

Il numero di MID, può corrispondere se si esegue una ricerca nella GUI TEST_QUARANTINE dell'interfaccia SMA.

ricerca quarantena

risultati quarantena

Filtra MID e crea payload

Filtrare i MID e generare il file di payload.

$ jq '{action:"release", quarantineType:"pvo", quarantineName:"TEST_QUARANTINE", mids:[.data[] | select(.attributes.sender | endswith("@labcisco.com")) | .mid]}' response.json > payload.json

$ cat payload.json

{

"action": "release",

"quarantineType": "pvo",

"quarantineName": "TEST_QUARANTINE",

"mids": [

440,

439,

438,

437,

436,

435,

434,

433,

425,

414

]

}

Esecuzione della release (POST)

Inviare la richiesta di rilascio all'SMA:

$ curl -X POST "https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages" \

-H "Authorization: Basic token-generated-in-base64" \

-H "Content-Type: application/json" \

-d @payload.json

{"data": {"action": "release", "totalCount": 10}}

Verifica dei risultati

Controllo dei log di posta

Quando si controlla mail_logs per i messaggi rilasciati, è possibile filtrare per grep "release" mail_logs e gli stessi MID filtrati in precedenza, gli stessi che sono stati rilasciati.

Sun Mar 15 11:48:21 2026 Info: MID 436 released from quarantine "TEST_QUARANTINE" (manual) t=1393

Sun Mar 15 11:48:21 2026 Info: MID 425 released from quarantine "TEST_QUARANTINE" (manual) t=1411

Sun Mar 15 11:48:21 2026 Info: MID 414 released from quarantine "TEST_QUARANTINE" (manual) t=2787

Sun Mar 15 11:48:21 2026 Info: MID 433 released from quarantine "TEST_QUARANTINE" (manual) t=1397

Sun Mar 15 11:48:21 2026 Info: MID 440 released from quarantine "TEST_QUARANTINE" (manual) t=1387

Sun Mar 15 11:48:21 2026 Info: MID 439 released from quarantine "TEST_QUARANTINE" (manual) t=1388

Sun Mar 15 11:48:21 2026 Info: MID 434 released from quarantine "TEST_QUARANTINE" (manual) t=1396

Sun Mar 15 11:48:21 2026 Info: MID 437 released from quarantine "TEST_QUARANTINE" (manual) t=1391

Sun Mar 15 11:48:21 2026 Info: MID 435 released from quarantine "TEST_QUARANTINE" (manual) t=1395

Sun Mar 15 11:48:21 2026 Info: MID 438 released from quarantine "TEST_QUARANTINE" (manual) t=1390

Controllo diretto nella GUI

Se si esegue la stessa ricerca per il dominio in cui sono stati rilasciati i messaggi, si noterà che la ricerca non ha alcun risultato, poiché tutti i messaggi sono stati rilasciati.

quarantena dei nuovi risultati

Controllo tramite API

Postino

Eseguire nuovamente il comando GET da Retrieve All Messages per verificare che totalCount sia diminuito o che i MID specifici non siano più presenti.

query GET postman

ARRICCIATURA

$ curl -X GET "https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages?quarantineType=pvo&quarantines=TEST_QUARANTINE&limit=25&offset=0&orderBy=received&orderDir=desc&startDate=2026-03-12T00:00:00.000Z&endDate=2026-03-14T00:00:00.000Z" \

-H "Authorization: Basic token-generated-in-base64" \

-H "Accept: application/json" \

-o response.json

$ jq '[.data[] | select(.attributes.sender | endswith("@labcisco.com")) | .mid]' response.json > mids-labcisco-domain.json

$ cat mids-labcisco-domain.json

[]

Rilascio in blocco messaggi (500 messaggi)

Per gestire in modo efficace le operazioni di massa, è necessario conoscere le modalità di gestione dei dataset di grandi dimensioni tramite l'impaginazione. Quando è necessario elaborare un numero elevato di messaggi, è necessario calcolare i parametri di limite e offset per garantire il recupero dell'insieme completo di dati senza superare i vincoli di risposta API.

Adeguamento dei parametri API per le operazioni di massa

Quando si recupera un grande volume di messaggi, utilizzare questa logica per configurare la richiesta:

- Limite: Definisce il numero di record restituiti per richiesta. Sebbene sia possibile impostare questo valore su un valore elevato (ad esempio, 500 o 1000) per acquisire più dati contemporaneamente, è importante tenere presente le prestazioni del sistema e i potenziali timeout.

- Scostamento: In questo modo viene definito il punto iniziale dell'insieme di risultati. Se il numero totale di messaggi supera il limite, è necessario eseguire più richieste, incrementando lo scostamento del valore limite in ogni chiamata successiva (ad esempio, offset=0, offset=500, offset=1000).

Ridimensionamento del flusso di lavoro

Il processo utilizzato nell'esempio di 10 messaggi precedente funge da base per tutte le operazioni di massa. Per scalare il flusso di lavoro, è sufficiente scorrere la coda incrementando sistematicamente il parametro di offset. Se si utilizzano questi valori, modificando il limite per definire le dimensioni del batch e l'offset per spostarsi nelle pagine, è possibile recuperare ed elaborare l'intera coda di quarantena, indipendentemente dal numero totale di messaggi.

Informazioni correlate

- Guida introduttiva ad AsyncOS API 16.0 per Cisco Secure Email e Web Manager - GD (General Deployment)

- Supporto tecnico Cisco e download