PythonおよびAsyncOS REST APIを使用したESAディクショナリの設定

はじめに

このドキュメントでは、AsyncOS API(REST API)を使用してPythonスクリプトを使用し、新しいディクショナリをCisco Eメールセキュリティアプライアンス(ESA)に追加する方法について説明します。

前提条件

次の前提条件を確認してください。

• Pythonプログラミング言語
• Python requestsモジュール
• JSON
• Cisco Email Security Appliance (ESA)

要件

スクリプトを実行するには、次のソフトウェアとアクセス権を使用します。

• AsyncOS 14.x以降を実行するCisco Eメールセキュリティアプライアンス(ESA)
• Python 3
• Python requestsモジュール
• AsyncOS API(REST API)を使用する権限を持つESA管理者クレデンシャル
• ポート6443（推奨）でのHTTPSによるESA管理インターフェイスへのアクセス

使用するコンポーネント

この実習では、次のコンポーネントを使用しました。

1) Cisco ESA - 15.0.0-104

2)崇高なテキストエディタ

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

転送と認証

• トランスポート：AsyncOS APIのポート6443でHTTPSを使用します（使用可能な場合）。HTTP/6080は、非実稼働環境またはラボ環境でのみ使用してください。
• 認証：この例では、HTTP Basic認証を使用します。ヘッダー「Authorization: Basic <base64(username:password)>」を指定します。実際のクレデンシャルをスクリプトに貼り付けないでください。

バックグラウンド情報

このドキュメントの内容：

目標：PythonスクリプトとAsyncOS API(REST API)を使用して、ESAにディクショナリを追加します。

期待される結果：APIは正常な応答を返し、新しいディクショナリがESA設定に表示されます。

設定

スクリプトを実行する前に、ESA管理インターフェイスでAsyncOS API(REST API)サービスを有効にします。

1. グラフィカルユーザインターフェイス(GUI)で、AsyncOS API HTTPおよびAsyncOS API HTTPS設定が含まれているネットワークページまたはインターフェイスページに移動します。
2. AsyncOS API HTTPSを有効にして、ポート6443を確認します。
3. （オプション）AsyncOS API HTTPを有効にして、ラボで使用するポート6080を確認します。
4. [Save] をクリックします。

図1：管理インターフェイスでAsyncOS API HTTPS（ポート6443）が有効になっていることを確認します。

AsyncOS API要求をトラブルシューティングするためのAPIロギングの設定

1. グラフィカルユーザインターフェイス(GUI)で、System Administration > Log Subscriptionsに移動します。
2. Add Log Subscriptionをクリックします。
3. Log Typeドロップダウンリストから、API Logsを選択します。
4. ログ名やファイル名などの残りの必須フィールドに入力し、Submitをクリックします。

Log TypeドロップダウンリストからAPI Logsを選択し、残りの必須詳細を入力します。

スクリプト

PythonのrequestsモジュールからHTTPのPOSTメソッドを使用して、ディクショナリを作成します。

POST要求には次のパラメータを使用します。

項目	場所	Required	注意事項
device_type（デバイスのタイプ）	URLクエリ文字列	Yes	esaを設定します。
無視する	JSONペイロード	Yes	0 =大文字と小文字を区別する、1 =大文字と小文字を区別しない。
全ての語	JSONペイロード	Yes	0 =部分文字列の一致、1 =単語単位の一致。
符号化	JSONペイロード	Yes	別のエンコーディングが必要でない場合は、utf-8を使用します。
言葉	JSONペイロード	Yes	エントリの配列。リテラル用語には["term"]を使用します。スマートIDには、ESAでサポートされている["*credit", 2, "prefix"]などのタプル形式を使用します。
モード	URLクエリ文字列	いいえ	クラスタ化された/グループの展開にのみ必要です（たとえば、mode=cluster）。

import base64
import requests

# ESA management IP address or FQDN
host = ""

# Dictionary name to create
dictionary_name = ""

# AsyncOS API endpoint (HTTPS recommended)
url = f"https://{host}:6443/esa/api/v2.0/config/dictionaries/{dictionary_name}?device_type=esa"

payload = {
    "data": {
        "ignorecase": 0,
        "wholewords": 1,
        "words": [
            ["*credit", 2, "prefix"],
            ["*aba"],
            ["Example Term"]
        ],
        "encoding": "utf-8"
    }
}

# Basic authentication header
username = ""
password = ""
creds = base64.b64encode(f"{username}:{password}".encode()).decode()

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Basic {creds}"
}

response = requests.post(url, headers=headers, json=payload, timeout=30, verify=False)
print(f"Status code: {response.status_code}")
try:
    print(response.json())
except ValueError:
    print(response.text)

if response.status_code != 201:
    raise SystemExit("Dictionary creation failed.")

スクリプトでは、ディクショナリ名(<DICT_NAME>)が要求URLパスに含まれています。

必要なパラメータ（ignorecase、wholewords、words、およびencoding）をJSONペイロードに含めます。URLクエリ文字列にdevice_typeを追加します。

modeパラメータは、ESAがクラスタまたはグループ内にある場合にのみ必要です。その場合は、device_typeと同じ方法で、URLクエリ文字列にmode=clusterを追加します。

*creditと*abaがペイロードに追加され、クレジットカード番号とABAルーティング番号のスマート識別子を有効にします（スクリーンショットを参照）。

Example Termという用語が、照合する辞書項目としてペイロードに追加されます。

確認

POST要求が成功すると、APIログに次のようなエントリが記録されます。

API log example
Thu October 5 12:58:19 2023 Info: 198.51.100.10 - - 05/Oct/2023 12:58:19 +0000 POST /esa/api/v2.0/config/dictionaries/ExampleDictionary?device_type=esa HTTP/1.1 201 -

予測される応答:

{"data": {"message": "Added Successfully"}}

ディクショナリがすでに存在し、POST要求が再実行される場合、APIログには次のようなエントリが含まれます。

API log example
Thu October 5 13:00:31 2023 Info: 198.51.100.10 - - 05/Oct/2023 13:00:31 +0000 POST /esa/api/v2.0/config/dictionaries/ExampleDictionary?device_type=esa HTTP/1.1 409 -

予測される応答:

{"error": {"message": "Dictionary already exists.", "code": "409", "explanation": "409 = Request conflict."}}

関連情報

追加の背景情報については、次の外部リソースを使用してください（このドキュメントの手順は完全独立型です）。

REST API + Pythonを使用した辞書の追加 

このドキュメントには、必要な認証方式と最小限の手順が記載されています。ヘッダーAuthorization: Basic <base64(username:password)>の付いたHTTP Basic認証を使用し、ポート6443でHTTPSを優先します。

REST APIとCisco ESA 

さらに、この手順で使用されるPythonコードはPostmanから抽出できます。必要に応じて、このビデオチュートリアルを確認してください。

Postman - Pythonスクリプトの生成方法 

更新履歴

改定	発行日	コメント
1.0	26-Aug-2026	初版