Automatize a liberação de mensagens nas quarentenas PVO usando a API do SMA

Introdução

Este documento descreve como automatizar o gerenciamento e a liberação de mensagens em um Cisco SMA através da API REST para processar grandes volumes de mensagens.

Pré-requisitos

Requisitos

A Cisco recomenda que você tenha conhecimento destes tópicos:

• Conhecimento do produto Cisco SMA
• Familiaridade com os conceitos básicos da API REST, Postman, Curl e JQ para processamento JSON
• Credenciais válidas para acesso à API do SMA
• Linha de comando
• Acesso à rede para o SMA
• Ferramentas instaladas: curl (para solicitações), JQ (para manipulação JSON) e um cliente como Postman para testes iniciais
• Função de usuário apropriada no SMA para executar ações de liberação de mensagem

Componentes Utilizados

Este documento não se restringe a versões de software e hardware específicas.

As informações neste documento foram criadas a partir de dispositivos em um ambiente de laboratório específico. Todos os dispositivos utilizados neste documento foram iniciados com uma configuração (padrão) inicial. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Informações de Apoio

Automatizar a liberação de mensagens é essencial para ambientes com alto volume de e-mail. Usando a API, os administradores podem filtrar mensagens específicas (por exemplo, por remetente) e liberá-las programaticamente, reduzindo o tempo operacional e o risco de erro humano em comparação ao gerenciamento manual na GUI.

Teste inicial

Para gerenciar a quarentena, comece executando uma consulta inicial para verificar a conectividade e confirmar a estrutura de dados.

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

Estrutura de dados

• Ponto de Extremidade de API: A URL base para a API do SMA (por exemplo, https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages).
• Nome da quarentena: O identificador de quarentena de PVO específico (por exemplo, TEST_QUARANTINE) do qual você pretende recuperar mensagens.
• Intervalo de datas: A data de início e a data de término usadas para definir o período de tempo específico para a pesquisa.
• Limite: O número máximo de registros a serem retornados em uma única resposta de API. Isso ajuda a gerenciar o tamanho do payload e evita timeouts ao lidar com filas grandes.
• Deslocamento: O índice inicial do conjunto de resultados. Isso é usado para paginação; por exemplo, definir um deslocamento de 25 ignora as primeiras 25 mensagens, permitindo que você recupere o próximo lote de resultados.

Verificar os resultados usando a GUI e a API

Ao recuperar as informações, você pode ver a mesma quantidade de mensagens na chamada à API e na GUI.

solicitação GET do carteiro

Mensagens de TEST_QUARANTINE

Teste inicial com CURL

Gere seu token de autenticação Base64 para o cabeçalho de autorização:

echo -n 'username:password' | base64

Recuperar todas as mensagens

Execute a solicitação de curva para extrair as mensagens em um arquivo 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 Contagem Total

Verifique o número total de mensagens recebidas:

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

Filtrar MIDs por domínio

Use JQ para filtrar os MIDs das mensagens que você deseja liberar (por exemplo, filtrando por domínio).

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

O número de MIDs pode ser correspondente se você fizer uma pesquisa no TEST_QUARANTINE na GUI do SMA.

pesquisa de quarentena

resultados de quarentena

Filtrar MIDs e Criar Carga

Filtre os MIDs e gere o arquivo de 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
  ]
}

Execute a versão (POST)

Envie a solicitação de liberação ao 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 os resultados

Verificando mail_logs

Ao verificar mail_logs para mensagens liberadas, você pode filtrar por grep "release" mail_logs e os mesmos MIDs que você filtrar acima, os mesmos que foram 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

Verificando diretamente na GUI

Se você fizer a mesma pesquisa para o domínio em que liberou as mensagens, verá que a pesquisa não tem resultados, já que todas as mensagens foram liberadas.

colocar novos resultados em quarentena

Verificando usando API

POSTMAN

Execute novamente o comando GET em Recuperar todas as mensagens para confirmar que o totalCount diminuiu ou que os MIDs específicos não estão mais presentes.

consulta GET do carteiro

CURL

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

Liberação de Mensagem em Massa (500 Mensagens)

Para lidar com operações em massa de forma eficaz, você deve entender como gerenciar grandes conjuntos de dados usando a paginação. Quando você precisa processar um grande número de mensagens, deve calcular os parâmetros de limite e deslocamento para garantir que você recupere o conjunto completo de dados sem exceder as restrições de resposta da API.

Ajustando Parâmetros de API para Operações em Massa

Ao recuperar um grande volume de mensagens, use esta lógica para configurar sua solicitação:

• Limite: Define o número de registros retornados por solicitação. Embora você possa definir isso como um número alto (por exemplo, 500 ou 1000) para capturar mais dados de uma só vez, tenha em mente o desempenho do sistema e os possíveis timeouts.
• Deslocamento: Isso define o ponto inicial do seu conjunto de resultados. Se o número total de mensagens exceder o limite, você deverá executar várias solicitações, aumentando o deslocamento pelo valor de limite em cada chamada subsequente (por exemplo, deslocamento=0, deslocamento=500, deslocamento=1000).

Dimensionando seu fluxo de trabalho

O processo usado no exemplo anterior de 10 mensagens serve como base para todas as operações em massa. Para dimensionar o fluxo de trabalho, simplesmente faça a iteração através da fila, incrementando sistematicamente o parâmetro de deslocamento. Ao "reproduzir" com esses valores, ajustando o limite para definir o tamanho do lote e o deslocamento para navegar pelas páginas, você pode efetivamente recuperar e processar toda a fila de quarentena, independentemente da contagem total de mensagens.

Informações Relacionadas

• Guia de introdução do AsyncOS API 16.0 para Cisco Secure Email and Web Manager - GD (General Deployment)
• Suporte técnico e downloads da Cisco