AMIは、外部プログラムからシステムを管理するためのAsteriskの強力で使いやすいプログラミングインターフェイス（API）です。 AMIに加えて、AGIがよく使用されます。これは、特定の呼び出し内でアスタリスクチャネルを制御する外部アプリケーションを起動するためのインターフェイスです。 AMIのおかげで、外部プログラムはTCPプロトコルを介してアスタリスクに接続し、コマンドの実行を開始し、実行結果を読み取り、イベントのリアルタイム通知も受信できます。 これらのメカニズムは、たとえば次の場合に使用できます。

• システムの状態を調べる必要があります
• アクティブなサブスクライバーの数
• CLIコマンドをリモートで実行する
• CDRストレージを改善する
• ...など

AMIは、ビジネスプロセスやシステム、CRMソフトウェア（Customer Relationship Management）との統合によく使用されます。 自動ダイヤラーやClick-to-Callシステムなど、さまざまなアプリケーションにも使用できます。



多くの場合、アスタリスクはCLIコンソールから管理されますが、AMIを使用する場合、アスタリスクを実行しているサーバーに直接アクセスする必要はありません。 AMIは、開発者が他のソフトウェア製品と統合するための非常に強力で柔軟なツールになることができる最も単純なツールです。 これにより、開発者はアスタリスクによって生成された情報をリアルタイムで使用できます。



また、バージョン1.6以降のアスタリスクでは、マネージャーバージョン1.1インターフェースが使用されています。 基本的に、変更は、同じタイプのコマンドの多くの統一と、さまざまなモジュールによって発行される応答の標準化に関係していました。 CoreSettingsコマンドを使用して、インターフェイスのバージョンを確認できます。 AMIインターフェイスが以前のバージョンとの完全な互換性を失う場合、将来バージョンが変更される可能性があります。

AMIの仕組み

Asteriskサーバーとクライアントプログラムの間で単純な行単位のプロトコルが使用され、通信が確立されます。各メッセージ行は2行で構成されます。

• keyは、現在の行に含まれる情報の性質を説明するキーワードです。 キーワードは一意ではなく、同じ前提内で複数回使用できます
• value-パラメーター値
• キーワードはコロンで区切られます

さらに、「パッケージ」という用語を使用します。これは、CRLFで区切られ、追加のCRLFシーケンスで完了する一連の「キー：値」構成要素を表します。



アスタリスクとクライアント間の相互作用のプロトコルは、次の特性によって説明できます。

• コマンドをAsteriskサーバーに送信する前に、Asteriskサーバーとのクライアント接続セッションを実行する必要があります。
• パケットは、認証手順を通過した後、いつでも任意の順序で送信できます。
• パケットの最初の行には、次のキーのいずれかを含める必要があります。「アクション」（クライアントから送信される場合の唯一のオプション）、および「イベント」および「レスポンス」キー（アスタリスクからクライアントに送信する必要があります）;
• パッケージ内の行の順序は重要ではありません。クライアント側でパッケージを形成できる任意のプログラミング言語を使用できます。
• CRLFは、アスタリスクへのコマンドの転送の完了を示すために、パッケージ内の各行と2つのCRLFシーケンス（別名\ r \ n）を分離するために使用されます

AMIは、ネットワークポートで確立された接続を受け入れます（デフォルトはTCPポート5038）。 クライアントプログラムは、このポートを介してAMIに接続して認証します。その後、アスタリスクは要求に応答し、指定されたサブシステムのステータスの変化に関する通知を送信します。

パッケージの種類



クライアントからAsteriskサーバーに送信されて返送されるパケットは、次の重要な特性によって決定されます。

• アクション、AMIに接続されたクライアントによって送信されたパケット。 サーバーがこのようなパケットを処理した後、何らかのアクションが実行されます。 クライアントによって実行されるアクションには、比較的柔軟な制限があります。 1つのパッケージ-1つのアクション。 Actionパッケージには、実行する操作の名前と、必要なすべてのパラメーターが含まれている必要があります。
• 応答。アクションの完了時にアスタリスククライアントに送信される応答を定義します。
• イベント、アスタリスクまたは拡張モジュールのコア内部で生成されるイベントに関連するデータ。

通常、クライアントはアクションパケットをアスタリスクに送信します（コマンドとも呼ばれます）。 次に、アスタリスクは要求を実行し、Responseパッケージで受信した結果（多くの場合、結果は失敗の場合は簡単な説明を伴うアクションの成功です）を返します。 結果が受信される順序（応答パケット）に関する保証はありません。したがって、クライアント要求では、通常ActionIDパラメーターは各Actionパケットに含まれ、対応する応答パケットはActionIDフィールドに同じ値を含みます。 したがって、クライアントは、応答パケットが次のアクションを実行するのを待たずに、任意の順序でアクションパケットと応答パケットを非常に簡単に処理できます。



次のCLIコマンド（タブ補完はオートコンプリートで機能します）は、ご使用のバージョンのAsteriskで使用可能なAMIコマンドの完全なリストを取得するのに役立ちます。

*CLI> manager show commands







応答パッケージ。 上記のように、送信されたコマンドに対する回答として機能します。 コマンドに対する1つの応答が送信され、いくつかの値を伝達できます。

• 「成功」-アクションは成功し、すべての情報がこのパッケージに含まれます
• 「エラー」-エラーが発生しました。「メッセージ」ヘッダーの詳細な説明
• 「フォロー」-実行の結果は後続のイベントパケットで送信されます

イベントパケット（イベント）は2つのコンテキストで適用されます。 一方では、クライアントにアスタリスクサブシステムの状態の変化（チャネル状態のその他の変化）を通知し、他方では、アクションに応答してアスタリスクが返すデータセットを転送します。

• クライアントがアクションパケットを送信すると、アスタリスクは（多くの均一なレコードを返す必要がある場合に）「Response：Follows」レコードのみを含むResponseパケットを送信できます。 次に、アスタリスクはデータセットを含む一定数のイベントを送信し、最後に、すべてのデータが送信されたことを報告するイベントを送信します。 これによって生成されるすべてのイベントパケットには、要求を開始した元のアクションパケットのActionIDが含まれます。 これにより、Responseパッケージのように簡単に処理できます。 アクションによって生成されるイベントの例は、アクティブチャンネルごとにステータスイベントをトリガーするアクションステータスです。 すべてのStatusイベントが送信された後、StatusCompleteイベントが送出されます。
• イベントは、アスタリスクのさまざまな構造部分（SIP / IAX2 / ...チャネル、CDR、ダイヤルプラン、コアのさまざまな部分）によって作成されます。 イベントに割り当てられる主なタスクは、外部接続システムがアスタリスクから情報を受信し、これらすべてのイベントを収集し、それらを分析して、得られた結果に応じてアクションを実行できるようにすることです。

イベントはCLIに文書化されていないため、詳細な情報はvoip-info.orgの文書（manager_1_1.txtファイル）にあります。 何らかのイベントが記述されていないという印象をまだ受けているが、そうあるべきである場合-対応するモジュールのソースコードで、関数名-manager_eventですべての種類のイベントを見つけることができます



実用的な例に移る前に、アスタリスクのバージョン1.6から、AMIインターフェースがバージョン番号1.1を取得したことは注目に値します。 これは、コマンド形式が単一形式に縮小され、互換性が部分的に失われたためです。 この記事では、バージョン1.6の作業に焦点を当て、相違点が存在する場合は、括弧内に説明を記載します。

安全性



AMIインターフェースを介して提供されるシステムを管理する可能性はほぼ無限です。 暗号化されていないパスワードと特定のIPアドレスからAMIへのアクセスを制限する機能に加えて、Managerインターフェースには他のセキュリティ機能もあります（別名）ので、パブリックIPアドレスでは使用しないことを強くお勧めします。



パブリックネットワークからの使用が必要な場合は、iptablesを使用するか、任意のタイプのVPNトンネルを介してアクセスを制限する必要があります。 AMIインターフェースへのアクセスは、ビルトインHTTP（S）サーバーを介して取得することもできます。アクセスはhttp.confファイルで設定されます。 HTTPサーバーを介してAMIインターフェースを操作するように、デフォルトではAMIインターフェースが禁止されていることに注意してください。



信頼されていないネットワークでも、AMIへのエンドユーザーアクセス（TAPIを介したクリック2呼び出し機能など）を提供する場合は、AstManProxyを使用してManager APIへのすべての接続を処理することをお勧めします。 彼についてもう一度。

AMI設定

AMIインターフェースを使用するには、構成を担当する/etc/asterisk/manager.confファイルを編集する必要があります。



[general]

enabled=yes ; AMI (- no)

port=5038 ; TCP 5038

bindaddr=192.168.0.1 ; (0.0.0.0 - )

timestampevents = yes ;

displayconnects = yes ; AMI

allowmultiplelogin = yes ;



; ,

[admin] ; ,

secret=passwd1234 ; AMI

deny=0.0.0.0/0.0.0.0 ; ip-

permit=192.168.0.2/255.255.255.0 ; ip

read=system, call, log, verbose, command, agent, user ;

write=system, call,log, verbose, command, agent, user ;







[general]セクションは、一般的な接続設定を定義します。 AMIオプションを有効にします=はい。 注：設定を有効にするには、AMIオーバーロードを実行する必要があります。



*CLI>module reload manager







または

*CLI>manager reload







拒否および許可オプションを使用して、アスタリスクに接続できるIPアドレスを指定できます。 システムにユーザーを追加して（角かっこで始まるセクションをコピーすることにより）、アクセス権を割り当てることができます。

• 読み取り-読み取り許可。
• 書き込み-書き込み許可。

上記の例では、adminユーザーにAsteriskサービスを停止するまでの広範な権限が付与されています（コマンドオプションがこれを担当しています）。 それ以降のバージョン（1.6.1以降）では、AMIでアスタリスクの停止につながる可能性のあるコマンドを使用することは禁止されています。

参照資料

• AMI 1.1の変更に関するドキュメント
• 構成ファイル（トランク）
• AJAMの説明
• AstManProxy