SMA APIを使用したPVO検疫でのメッセージリリースの自動化

はじめに

このドキュメントでは、大量のメッセージを処理するためにREST APIを介してCisco SMAのメッセージ管理とリリースを自動化する方法について説明します。

前提条件

要　件

次の項目に関する知識があることが推奨されます。

• Cisco SMA製品の知識
• REST APIの基本、Postman、curl、およびJSON処理のJQに精通していること
• SMA APIアクセスの有効なクレデンシャル
• コマンドライン
• SMAへのネットワークアクセス
• インストールされるツール：curl（リクエスト用）、JQ（JSON操作用）、初期テスト用のPostmanなどのクライアント
• メッセージリリースアクションを実行するSMAの適切なユーザロール

使用するコンポーネント

このドキュメントの内容は、特定のソフトウェアやハードウェアのバージョンに限定されるものではありません。

このドキュメントの情報は、特定のラボ環境にあるデバイスに基づいて作成されたものです。このドキュメントで使用するすべてのデバイスは、クリアな（デフォルト）設定で作業を開始しています。本稼働中のネットワークでは、各コマンドによって起こる可能性がある影響を十分確認してください。

バックグラウンド情報

大量のEメールが存在する環境では、メッセージリリースの自動化が不可欠です。APIを使用することにより、管理者は特定のメッセージ（送信者によるなど）をフィルタ処理し、それらをプログラムによって解放できます。これにより、GUIでの手動管理と比較して、運用時間が短縮され、人的エラーのリスクが軽減されます。

初期テスト

隔離を管理するには、最初にクエリを実行して接続を確認し、データ構造を確認します。

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

データ構造

• APIエンドポイント：SMA APIのベースURL(例：https://dhxyz-sma2.iphmx.com/sma/api/v2.0/quarantine/messages)。
• 隔離名：メッセージの取得元となる特定のPVO隔離識別子（TEST_QUARANTINEなど）。
• 日付範囲：検索の特定の期間を定義するために使用される開始日と終了日。
• Limit:1つのAPI応答で返されるレコードの最大数。これは、ペイロードサイズの管理に役立ち、大きなキューを処理する際のタイムアウトを防止します。
• オフセット：結果セットの開始インデックス。これはページ区切りに使用されます。たとえば、オフセットを25に設定すると、最初の25個のメッセージがスキップされ、次の結果バッチを取得できます。

GUIとAPIの両方を使用した結果の確認

情報を取得すると、APIコールとGUIで同じ量のメッセージを確認できます。

postman GET要求

TEST_QUARANTINEメッセージ

CURLを使用した初期テスト

認証ヘッダー用のBase64認証トークンを生成します。

echo -n 'username:password' | base64

すべてのメッセージの取得

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

合計数の確認

受信したメッセージの合計数を確認します。

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

ドメインごとのMIDのフィルタ

JQを使用して、解放するメッセージのMIDをフィルタリングします（ドメインによるフィルタリングなど）。

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

SMA GUIでTEST_QUARANTINEを検索する場合は、MIDの数が一致する可能性があります。

検疫検索

検疫結果

MIDのフィルタリングとペイロードの作成

MIDをフィルタリングし、ペイロードファイルを生成します。

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

リリースの実行(POST)

リリース要求を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}}

結果の確認

mail_logsのチェック

リリースされたメッセージのmail_logsを確認する場合、grep “release” mail_logsと、上記でフィルタリングした同じMID（リリースされたものと同じ）でフィルタリングできます。

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

GUIでの直接チェック

メッセージをリリースしたドメインに対して同じ検索を実行すると、すべてのメッセージがリリースされているため、検索の結果が表示されません。

新しい結果の検疫

APIを使用したチェック

Postman

Retrieve All MessagesからGETコマンドを再実行して、totalCountが減少したか、または特定のMIDが存在しないことを確認します。

postman GETクエリ

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

バルクメッセージリリース（500メッセージ）

バルク操作を効果的に処理するには、ページ区切りを使用して大きなデータセットを管理する方法を理解する必要があります。大量のメッセージを処理する必要がある場合は、制限パラメータとオフセット・パラメータを計算して、API応答制約を超えずにデータの完全なセットを取得できるようにする必要があります。

バルク操作のAPIパラメータの調整

大量のメッセージを取得する場合は、次のロジックを使用して要求を構成します。

• Limit（制限）：リクエストごとに返されるレコードの数を定義します。この値を大きい値（500や1000など）に設定すると、一度に多くのデータをキャプチャできますが、システムのパフォーマンスとタイムアウトの可能性に注意してください。
• オフセット：結果セットの開始点を定義します。メッセージの合計数が制限を超える場合は、複数の要求を実行し、後続のコールごとに制限値だけオフセットを増分する必要があります（たとえば、offset=0、offset=500、offset=1000）。

ワークフローの拡大

前の10メッセージの例で使用したプロセスは、すべてのバルク操作の基盤として機能します。ワークフローをスケーリングするには、offsetパラメータを体系的に増分してキューを反復します。バッチサイズを定義する制限と、ページ間を移動するオフセットを調整するこれらの値を「再生」することで、メッセージ合計数に関係なく、検疫キュー全体を効果的に取得して処理できます。

関連情報

• AsyncOS API 16.0 for Cisco Secure Email and Web Managerスタートアップガイド – GD（一般導入）
• シスコのテクニカルサポートとダウンロード