Pythonを使ってMCUのAPIを実行する

Yusuke Yoshinaga · ‎2014-12-16

はじめに

このドキュメントではCisco TelePresence MCUのAPIをプログラミング言語Pythonを用いて実行する例を紹介します。
XML-RPCで提供されるMCUのAPIを実行する方法はいくつかありますが、Pythonは広く一般的に使用されているプログラミング言語であり、色々なプラットフォーム上に実行環境を容易に用意することが可能ですので、MCUのAPIをテストするために適しています。

APIを使用することにより、外部システムからMCUの操作(情報取得・設定変更・会議の作成など)を行うことが可能です。

実行環境

本ドキュメントに掲載する例は以下の環境で実行したものです。

MCU5320 - 4.5(1.55)
Python 2.7.5をMac Book Pro OSX 10.9.5で実行

WindowsでPythonを実行する場合にはPython公式サイトで配布されているMSI形式のインストーラを使用できます。

https://www.python.org/downloads/windows/

Linuxの場合にはディストリビューションによって異なりますが、Pythonのパッケージはプリインストールされているかパッケージレポジトリで提供されています。

http://docs.python.jp/2/using/unix.html

APIの実行

はじめに

前述のとおり、本ドキュメントではMCU5320ソフトウェアバージョン4.5(1.55)でのAPI実行例を記載します。

MCUソフトウェアバージョン4.5ではAPIバージョン2.11を使用しますので、API Guide 2.11を参照します。

PythonでAPI「device.query」を実行するコードの例(mcu_api.py)を示します(左端の行番号は説明用)。

1. # coding: utf-8
2. import xmlrpclib
3. auth = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI"}
4. MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
5. print MCU.device.query(auth)

2行目でXML-RPCクライアントモジュール「xmlrpclib」をインポートしています。

xmlrpclibの詳細について下記Python公式ドキュメントに記載されています。

xmlrpclib - XML-RPCクライアントアクセス

http://docs.python.jp/2/library/xmlrpclib.html

3行目はMCUのユーザ認証情報です。「認証」で後述します。

4行目のServerProxyはXML-RPCサーバつまりMCUとの通信を管理するためのオブジェクトです。「HTTP/HTTPS」で後述しますが、192.168.97.40がMCUのIPアドレスです。

5行目でAPI「device.query」を実行し、結果を表示しています。

Pythonのソースファイル「mcu_api.py」を実行すると、以下のようになります。

コマンド「python <ファイル名>」でプログラムを実行します。

「device.query」で得られる結果に含まれる情報は、API Guide 91ページ「device.query」の「Returned data」に記載されています。

MCUのWebUIでLogs > Event logからAPIの実行ログを確認できます。

正常に実行されたログはSeverity「Trace」で記録されます。

「Trace」のログはデフォルト設定では記録されませんので、確認が必要な場合にはLogs > Event capture filterで「API」の設定を「Errors, warnings, information and trace」とし、「Update settings」をクリックしてください。

注) 同設定はMCUに処理負荷をかけますので、ログの確認を完了次第、デフォルト設定「Errors, warnings and information」に戻してください。

WiresharkでAPIのリクエストとレスポンスを確認することも可能です。

下図の例では、IPアドレス192.168.13.5(クライアントPC)から192.168.97.40(MCU)にAPI「device.query」を送信し、レスポンスを受信しています。

<リクエスト>

赤枠の箇所にプログラム中で指定した値が設定されています。

<レスポンス>

<methodResponse>以下にMCUからのレスポンスデータが含まれています。

HTTP/HTTPS

API Guide 6ページ「Transport protocol」に記載のとおり、APIはHTTP/HTTPSを使って送受信します。

アプリケーションからの送信先はhttp(s)://<MCUのIPアドレス>/RPC2です。

API「device.query」を実行するコードの例

# coding: utf-8
import xmlrpclib

auth = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI"}
MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
print MCU.device.query(auth)

赤文字の箇所がAPIの送信先を設定している部分です。

MCUのHTTP/HTTPS設定はWebUIのNetwork Servicesで行います。

HTTPSはチェックボックスで有効/無効を設定可能です。

HTTP/HTTPSとも、ポート番号を変更可能です。

本ドキュメントでは、APIの宛先をHTTP/ポート80番として記述します。MCUのIPアドレスは192.168.97.40を使用しています。

文字エンコード

API Guide 9ページ「Encoding」に記載のとおり、APIの文字コードはASCIIテキストまたはUTF-8としてください。

認証

MCUのAPIインタフェースはステートレスに動作しますので、APIを発行する毎に認証が必要となります。つまり、アプリケーションからMCUに送信するAPIにはパラメータ「authenticationUser」と「authenticationPassword」を毎回設定する必要があります。

API Guide 9ページ「Authentication」をご参照ください。

API「device.query」を実行するコードの例

# coding: utf-8
import xmlrpclib

auth = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI"}
MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
print MCU.device.query(auth)

赤文字の箇所が認証情報を設定している部分です。

MCUのユーザ情報はWebUIのUsersから設定します。

本ドキュメントでは、MCUの「admin」ユーザにパスワード「PythonAPI」を設定したものとして記述します。

MCUから情報取得

MCUから情報を取得するAPIを使う例を示します。

cdrlog.query - MCUに記録されているCDRログの情報を取得

# coding: utf-8
import xmlrpclib

auth = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI"}
MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
print MCU.cdrlog.query(auth)

結果

{'numEvents': 1, 'firstIndex': 0, 'percentageCapacity': 0, 'deletableIndex': 0}

MCUには CDRログに1つの記録が保存されており、最初のインデックスが「0」であることがわかります。

cdrlog.enumrate - CDRログのデータを取得

# coding: utf-8
import xmlrpclib

param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "filter":["scheduledConferenceStarted"], 
         "index":0,
         "numEvents":1}
print MCU.cdrlog.enumerate(param)

API Guide 38ページ「cdrlog.enumerate」の「Input parameters」にリクエストパラメータについて書かれています。

fitler、index、numEventsをそれぞれ指定しています。filterはTypeが「array」なので中括弧で囲むことに注意してください。indexとnumEventsはTypeが「integer」なので中括弧やクォーテーションは不要です。

実行した結果が以下です。

{'eventsRemaining': False, 'nextIndex': 1, 'events': [{'conference': {'name': 'ADHOC', 'uniqueId': 57001}, 'index': 0, 'end': {'scheduledTime': 'permanent'}, 'time': <DateTime '20141216T16:06:35' at 1019a6368>, 'owner': {'name': 'admin'}, 'type': 'scheduledConferenceStarted', 'conferenceDetails': {'numericId': '', 'hasPin': 'no', 'billingCode': ''}}], 'startIndex': 0, 'currentTime': <DateTime '20141216T18:36:21' at 1019a63b0>}

会議名「ADHOC」に関するCDRログであることがわかります。その他、会議に関する情報が確認できます。

conference.status - 会議の状態を取得

# coding: utf-8
import xmlrpclib

MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "conferenceName":"ADHOC"}
print MCU.conference.status(param)

cdr.enumrateで取得した会議名「ADHOC」をパラメータ「conferenceName」に指定してconference.statusを実行します。

結果

{'h239Enabled': True, 'pin': '', 'contentImportant': False, 'contentMode': 'hybrid', 'private': False, 'startLocked': False, 'conferenceName': 'ADHOC', 'customLayout': 8, 'guestNumericId': '', 'contentTxCodec': 'automatic', 'contentTransmitResolutions': 'allowAll', 'automaticLectureModeEnabled': False, 'layoutControlEnabled': True, 'joinAGC': False, 'h239Important': False, 'activeStartTime': <DateTime '20141126T10:46:00' at 10ee0a320>, 'lastChairmanLeavesDisconnect': True, 'uniqueId': 1, 'registerWithGatekeeper': True, 'conferenceType': 'scheduled', 'description': '', 'contentPassthroughLimit': 'none', 'guestPin': '', 'chairControl': 'floorControlOnly', 'newParticipantsCustomLayout': False, 'joinAudioMuted': False, 'contentTxMinimumBitRate': 0, 'encryptionRequired': False, 'startTime': <DateTime '20141126T10:46:00' at 10ee0a368>, 'activeConferenceId': '57001', 'numericId': '', 'joinVideoMuted': False, 'floorStatus': 'inactive', 'locked': False, 'conferenceActive': True, 'preconfiguredParticipantsDefer': False, 'automaticLectureMode': 'disabled', 'layoutControlEx': 'feccWithDtmfFallback', 'cameraControl': 'feccWithDtmfFallback', 'inCallMenuControlChair': 'local', 'contentContribution': True, 'inCallMenuControlGuest': 'local', 'customLayoutEnabled': False, 'registerWithSIPRegistrar': False, 'suppressDtmfEx': 'fecc'}

会議の作成、参加者追加/削除、終了

MCUに会議を作成し、端末を会議に参加させ、会議を終了するまでの一連の操作をAPIで行う例を示します。

構成は以下のとおりです。

SX20 ---(SIP)--- MCU5320 ---(H.323)--- C20

SX20: 192.168.0.100

C20: 192.168.0.101

MCU: 192.168.97.40

MCUと端末の間にはGatekeeper/Proxy Serverは存在しない

使用するAPIは以下のとおりです。

conference.create
participant.add
participant.disconnect
conference.end
conference.destroy

MCUには会議が存在しない状態です。WebUIのConferencesで確認できます。

conference.create - 会議を新規作成

# coding: utf-8
import xmlrpclib

MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "conferenceName":"Created by API"}
print MCU.conference.create(param)

上記例では必須パラメータ(会議名："Created by API")のみを指定していますが、テンプレートやレイアウト、開始時間などを指定することが可能です。API Guideの41ページ「Optional or conditional inputs」をご参照ください。

実行結果

{'status': 'operation successful'}

MCUのWebUIで会議「Created by API」が作成されたことを確認できます。

participant.add - 会議に参加者を追加

# coding: utf-8
import xmlrpclib

MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "conferenceName":"Created by API", 
         "participantName":"SX20", 
         "participantProtocol":"sip",
         "address":"192.168.13.100"}
print MCU.participant.add(param)

必須パラメータは会議名、参加者名です。

ここではSX20を会議に参加させるためにオプションパラメータのプロトコルとIPアドレスを指定しています。

H.323で接続するC20も同じ要領で会議に参加させます。

# coding: utf-8
import xmlrpclib

param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "conferenceName":"Created by API",
         "participantName":"C20", 
         "participantProtocol":"h323",
         "address":"192.168.13.101"}
print MCU.participant.add(param)

MCUのWebUIから、会議「Created by API」の参加者が2となっていることがわかります。

会議名をクリックすると、会議の詳細を確認することができます。

participant.disconnect - 会議から参加者を切断

# coding: utf-8
import xmlrpclib

param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "conferenceName":"Created by API",
         "participantName":"SX20"}
print MCU.participant.disconnect(param)

SX20が会議から切断されました。

C20も同様です。

# coding: utf-8
import xmlrpclib

param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "conferenceName":"Created by API",
         "participantName":"C20"}
print MCU.participant.disconnect(param)

会議の参加者が0になりました。

conference.end - 会議を終了

# coding: utf-8
import xmlrpclib

MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "conferenceName":"Created by API"}
print MCU.conference.end(param)

「Created by API」が終了済会議(completed conference)に移りました。

conference.destroy - 会議情報の削除

# coding: utf-8
import xmlrpclib

MCU = xmlrpclib.ServerProxy("http://192.168.97.40/RPC2")
param = {"authenticationUser":"admin", "authenticationPassword":"PythonAPI", 
         "conferenceName":"Created by API"}
print MCU.conference.destroy(param)

MCUから会議情報が削除されました。

おわりに

本ドキュメントで例示したとおり、基本的な操作はシンプルなプログラムで簡単に実行することが可能です。

APIの各オプションパラメータを指定することで、より複雑な操作も可能です。PythonでGUIを作成することもできますので、GUIでMCUを操作するアプリケーションを開発したり、制御構造を用いることでMCUの検証を自動化することも可能です。

本ドキュメントの例を参考にMCUのAPIをご活用いただければと思います。

APIについてのご質問などはJapan CDN(Cisco Developer Network)のディスカッションスペース、CSC(Cisco Support Community)のご意見箱やテレプレゼンスのディスカッションにお問い合わせいただければと思います。

Japan CDN - ディスカッションスペース

https://communities.cisco.com/community/global/japanese/cdn/other

CSC - ご意見箱

https://supportforums.cisco.com/ja/document/12303581

CSC - テレプレゼンス/ディスカッション

https://supportforums.cisco.com/t5/-/bd-p/5231-discussions-telepresence