Automatizar la liberación de mensajes en cuarentenas PVO mediante la API SMA

Introducción

Este documento describe cómo automatizar la administración y liberación de mensajes en un SMA de Cisco a través de la API REST para procesar grandes volúmenes de mensajes.

Prerequisites

Requirements

Cisco recomienda que tenga conocimiento sobre estos temas:

• Conocimiento del producto SMA de Cisco
• Familiaridad con los conceptos básicos de la API REST, Postman, curl y JQ para el procesamiento JSON
• Credenciales válidas para el acceso a la API SMA
• Línea de comandos
• Acceso de red al SMA
• Herramientas instaladas: curl (para solicitudes), JQ (para manipulación de JSON) y un cliente como Postman para pruebas iniciales
• Función de usuario adecuada en el SMA para realizar acciones de liberación de mensajes

Componentes Utilizados

Este documento no tiene restricciones específicas en cuanto a versiones de software y de hardware.

La información que contiene este documento se creó a partir de los dispositivos en un ambiente de laboratorio específico. Todos los dispositivos que se utilizan en este documento se pusieron en funcionamiento con una configuración verificada (predeterminada). Si tiene una red en vivo, asegúrese de entender el posible impacto de cualquier comando.

Antecedentes

La automatización de la liberación de mensajes es esencial para entornos con un gran volumen de correo electrónico. Mediante el uso de la API, los administradores pueden filtrar mensajes específicos (por ejemplo, por remitente) y liberarlos mediante programación, lo que reduce el tiempo de funcionamiento y el riesgo de errores humanos en comparación con la gestión manual en la GUI.

Prueba inicial

Para administrar la cuarentena, comience por realizar una consulta inicial para verificar la conectividad y confirmar la estructura de datos.

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

Estructura de datos

• Terminal de API: La URL base para la API SMA (por ejemplo, https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages).
• Nombre de cuarentena: El identificador de cuarentena de PVO específico (por ejemplo, TEST_QUARANTINE) del que pretende recuperar mensajes.
• Intervalo de fechas: StartDate y endDate utilizados para definir el período de tiempo específico para la búsqueda.
• Límite: El número máximo de registros que se devolverán en una única respuesta de API. Esto ayuda a administrar el tamaño de la carga útil y evita tiempos de espera cuando se trata de colas grandes.
• Desplazamiento: El índice inicial del conjunto de resultados. Esto se utiliza para paginación; por ejemplo, si establece un desplazamiento de 25, se saltarán los primeros 25 mensajes, lo que le permitirá recuperar el siguiente lote de resultados.

Verifique los resultados utilizando tanto la GUI como la API

Al recuperar la información, puede ver la misma cantidad de mensajes en la llamada API y en la GUI.

solicitud GET de cartero

Mensajes de TEST_QUARANTINE

Prueba inicial con CURL

Genere su token de autenticación Base64 para el encabezado de autorización:

echo -n 'username:password' | base64

Recuperar todos los mensajes

Ejecute la solicitud curl para extraer los mensajes en un archivo local:

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

Verificar recuento total

Compruebe el número total de mensajes recibidos:

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

Filtrar MID por dominio

Utilice JQ para filtrar los MID de los mensajes que desea liberar (por ejemplo, filtrando por 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
]

El número de MID puede coincidir si realiza una búsqueda en TEST_QUARANTINE en la GUI de SMA.

búsqueda en cuarentena

resultados de cuarentena

Filtrar MID y crear carga útil

Filtre los MID y genere el archivo de carga.

$ 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
  ]
}

Ejecutar la versión (POST)

Envíe la solicitud de liberación al 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}}

Verifique los resultados

Comprobando mail_logs

Cuando verifique mail_logs para mensajes liberados, puede filtrar por grep "release" mail_logs y los mismos MIDs que filtra arriba, los mismos que fueron liberados.

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

Comprobación directa en la GUI

Si realiza la misma búsqueda para el dominio que liberó los mensajes, verá que la búsqueda no tiene resultados, ya que todos los mensajes fueron liberados.

poner en cuarentena nuevos resultados

Comprobando mediante API

POSTMAN

Vuelva a ejecutar el comando GET desde Recuperar todos los mensajes para confirmar que el totalCount ha disminuido o que los MID específicos ya no están presentes.

consulta GET de postman

RIZAR

$ 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
[]

Liberación masiva de mensajes (500 mensajes)

Para controlar eficazmente las operaciones masivas, debe entender cómo administrar grandes conjuntos de datos mediante paginación. Cuando necesite procesar un gran número de mensajes, debe calcular los parámetros de límite y desplazamiento para asegurarse de recuperar el conjunto completo de datos sin superar las restricciones de respuesta de la API.

Ajuste de los parámetros de API para operaciones masivas

Al recuperar un gran volumen de mensajes, utilice esta lógica para configurar su solicitud:

• Límite: Define el número de registros devueltos por solicitud. Aunque puede establecer este valor en un número alto (por ejemplo, 500 o 1000) para capturar más datos a la vez, tenga en cuenta el rendimiento del sistema y los posibles tiempos de espera.
• Desplazamiento: Esto define el punto inicial del conjunto de resultados. Si el número total de mensajes supera el límite, debe realizar varias solicitudes, aumentando el desplazamiento por el valor límite en cada llamada posterior (por ejemplo, desplazamiento=0, desplazamiento=500, desplazamiento=1000).

Ampliación del flujo de trabajo

El proceso utilizado en el ejemplo anterior de 10 mensajes sirve de base para todas las operaciones masivas. Para escalar el flujo de trabajo, simplemente realice una iteración por la cola incrementando sistemáticamente el parámetro de desplazamiento. Al "reproducir" con estos valores (ajustar el límite para definir el tamaño del lote y el desplazamiento para navegar por las páginas) puede recuperar y procesar eficazmente toda la cola de cuarentena, independientemente del recuento total de mensajes.

Información Relacionada

• AsyncOS API 16.0 for Cisco Secure Email and Web Manager-Guía de inicio - GD (implementación general)
• Soporte técnico y descargas de Cisco