Cisco MediaSense API の使用
Cisco MediaSense API の使用

Cisco MediaSense API の使用

MediaSense API 規則

MediaSense API は camelCase 表記法を使用します。 API URI では大文字と小文字が区別されます。 API ごとに識別される厳密な URI を使用します。 パラメータでは大文字と小文字が区別されません。

HTTPS の使用

MediaSense API は HTTPS のみをサポートします。 安全でない HTTP はほとんどの MediaSense API で受け入れられません。 getAPIVersion のみ、例外的に HTTP または HTTPS を受け入れることができます。

MediaSense は HTTP バージョン 1.1 を使用し、連続する要求を処理し、クライアント接続を維持します。 特にイベント配信の場合にパフォーマンスを向上させるには、必ず同様の動作が実行されるように、サードパーティ製のアプリケーションを構築してください。

POST 要求または GET 要求の使用

MediaSense API は、POST 要求と GET 要求に次の表記法を使用します。

HTTP 要求タイプ 説明 Action
POST サーバでアクションを実行し、MediaSense サーバの状態を変更する要求(開始または停止要求)。 または、パラメータの構造がクエリー パラメータで指定するには複雑すぎる、すべてのクエリーまたは読み取り要求。 たとえば、getSessions API は、それが安全な方法でも POST を使用します(サーバの状態を変更しません)。 パラメータは POST データ ブロックで渡されます。 データ ブロックは JSON 構文を使用します。
{
"requestParameters":{
   "param1":"value1",
   "param2":"value2"
    }
}
GET MediaSense システムに情報を問い合わせるか、情報を読み取るだけの要求(情報取得だけが目的であり、サーバの状態を変更しない、安全な方法)。 パラメータはクエリー パラメータとして URL で渡されます。 クエリー パラメータを指定するとき、疑問符「?」を最初のパラメータに付け、アンパサンド「&」を各後続パラメータに付けます。
http://cisco.com/abc
/xyz?param1=value1
&param2=value2

API バージョン

MediaSense API は次のバージョン表記法に従います。

  • MediaSense リリース 11.0(1) API のバージョンは 1.7 です。
  • API バージョン番号は 1.0 から始まり、製品バージョンと結び付いていません。
  • API バージョン番号は x.y.z ではなく x.y(例:1.0)です。

getAPIVersion API を使用して、システムで実行されている API の現在のバージョンを取得します。 この API は、MediaSense 展開で動作する API のバージョン番号を返します。 この API を使用するためにサインインする必要はありません。

応答の JSON 形式

MediaSense では JSON がサポートされます。 API 応答とイベントは JSON 形式です。 MediaSense API を使用するサードパーティ アプリケーションで使用される形式に関係なく、これらの規則に従ってください。

  • 各 API リクエストの HTTP ヘッダーでコンテンツ タイプをアプリケーションまたは json として指定します。
  • ヘッダーが欠落している場合、データはデフォルトの JSON 形式で返されます。

(注)  


JSON 形式は、キーと値のペアです。 キーと値のペアの順序は、各応答内で同じではない場合があります。

シスコでは、通常、1 つの API バージョンから次のバージョンまで、JSON 応答スキーマに新しいプロパティを追加しますが、既存のプロパティのオブジェクト階層の意味または相対的な位置は変更されません。 MediaSense の新しいバージョンでクライアント コードを正しく機能させるには、認識されない JSON プロパティをすべて無視する必要があります。 これは、API 応答とイベントの両方に適用されます。


MediaSense API の重要な要素

ここでは、MediaSense API 内の重要な要素とパターンを識別します。

MediaSense API のサンプル URI。

https://<host>:<port>/ora/<sampleService>/<sample>/<sampleMethod>

このサンプル URI の要素を次の表に示します。

要素 説明
https:// MediaSense API が使用するセキュアなプロトコル。
  • サーバ間の通信は常に HTTPS を使用する必要があります。
  • クライアント/サーバ間の通信では認証に HTTPS を使用する必要があります。
  • HTTPS は、ほとんどすべての MediaSense API に必要です。 1 つの例外が getAPIVersion API で、HTTP または HTTPS のいずれかを必要とします。
<host>:<port> <host> をホスト名に、<port> をポート番号に置き換えます。 これら 2 つの要素は、各 API のコンテキスト ルートの一部です。
ora MediaSense API の製品名仕様です。 この要素はすべての MediaSense API を通して一定です。
sampleService または sample

特定の MediaSense API によって指定されたサービスの名前。 利用可能なサービスはユーザ認証、イベント サブスクリプション、セッション照会、セッション管理などです。

この要素では、sampleService はインターフェイスで、sample がその実装です。

sampleMethod API の名前。 各 API 名は動詞で始まり、実行されるアクションを示します。

次の URI は、MediaSense subscribeRecording API の例です。

https://<host>:<port>/ora/eventService/event/subscribeToEvents

API 応答スキーマ

すべての MediaSense API 応答にこれらの重要な要素があります。

JSON スキーマ:

{
"responseCode": <replace with your integer> //Numeric code for the response
"responseMessage": <replace with your string> //A textual description of the result
"responseBody": {<JSON object>} //The response itself (optional)
}

(注)  


responseMessage パラメータは変更される場合があり、プログラム上の比較の目的で使用するものではありません。 その目的には、responseCode パラメータを使用してください。


非同期イベントのスキーマ

すべての MediaSense API 応答にこれらの重要な要素があります。

JSON の例:

{
    "eventType": <string value>, //type of the event, such as SESSION_EVENT
    "eventAction": <string value>, //possible actions for a given event such as SESSION_STARTED
    "forwardedEvent": <true or false>, //indicates that the event is not locally generated
    "eventBody": <JSON object> //the event itself
}

(注)  


これらの要素の詳細については、共有パラメータを参照してください。


API 応答コード

2xxx 成功応答コード

操作が正常に受信され、理解され、受け入れられました。

応答コード 説明
2000 成功:リクエストは正常に完了しました。
2001 成功:このクライアント要求に一致する結果は見つかりませんでした。
2002 成功:セッションのレコーディングが正常に一時停止しましたが、データベースは更新されませんでした。
2003 成功:セッションのレコーディングが正常に再開されましたが、データベースは更新されませんでした。
2004 成功:セッションのレコーディングは正常に削除されましたが、データベースは更新されませんでした。
2005 成功:指定されたサブスクリプション Uri を持つサブスクリプションはすでに存在します。
2006 成功:現在のサブスクリプションは更新され、要求された subscriptionFilters から解除されました。 サブスクリプションはまだアクティブです。
3xxx リダイレクト応答コード

要求を完了するには、クライアントは追加アクションを実行する必要があります。

応答コード 説明
3001 失敗:要求を処理できません。 リダイレクトを指定し、再試行してください。
4xxx クライアント エラー応答コード

要求に不正な構文が含まれているか、要求を実行できません。

応答コード 説明
4000 失敗:要求は無効です。
4001 失敗:安全でない HTTP は許可されません。 要求に HTTPS を使用します。
4005 失敗:データベースには値が見つかりません。 詳細:<parameter name>: <parameter value>
4019 失敗:認証されていない MediaSense ユーザ。
4020 失敗:ログイン認証情報(ユーザ名またはパスワード)は無効です。
4021 失敗:無効なセッションです。 セッションが期限切れになっている可能性があります。 再度ログインするか、または有効な JSESSIONID を入力してください。
4022 失敗:指定したユーザは Finesse スーパーバイザではありません。
4023 失敗:Cisco Finesse サーバへの接続に失敗しました。 Cisco Finesse の設定を確認し、再試行してください。
4030 失敗:この deviceRef を使用してコールを確立できません。 deviceRef を確認し、再試行してください。
4031 失敗:deviceRef が使用できないか、使用中です。 デバイスを確認し、後で再試行してください。
4032 失敗:この deviceRef を使用してコールを接続解除できません。 コールが存在していることを確認し、再試行してください。
4033 失敗:サポートされていない mediaStreams の組み合わせです。 このパラメータの許容ストリームを確認し、再試行してください。
4041 失敗:fieldName パラメータは無効です。
4042 失敗:fieldOperator パラメータは無効です。
4043 失敗:fieldValue パラメータ数が無効です。
4045 失敗:connector パラメータが無効です。
4046 失敗:order パラメータが無効です。
4047 失敗:fieldName パラメータが欠落しています。
4048 失敗:fieldCondition パラメータが欠落しています。
4049 失敗:fieldOperator パラメータが欠落しています。
4050 失敗:fieldValue パラメータが欠落しています。
4051 失敗:fieldConnector パラメータが欠落しています。
4052 失敗:paramConnector パラメータが欠落しています。
4053 失敗:fieldName パラメータが欠落しています。 fieldName でソートできません。
4054 失敗:order パラメータが欠落しています。
4055 失敗:requestParameter が欠落しています。
4056 失敗:無効な JSON 構文です。 構文を確認し、再試行してください。
4057 失敗:1 つ以上の fieldValue パラメータはタイプが不正です。
4058 失敗:tagName パラメータが欠落しています。
4059 失敗:認証プロバイダーが無効です。 有効な認証プロバイダーは、AXL、FINESSE です。
4060 失敗:クライアント要求に値が欠落しています。
4061 失敗:メッセージにパラメータが欠落しています。 詳細:<parameter name>
4062 失敗:パラメータの構文が無効です。 詳細:<parameter name>
4063 失敗:offset パラメータが無効です。
4064 失敗:limit パラメータが無効です。
4066 失敗:日付範囲が無効です。 日付範囲の上限は 1 年です。 要求を再送信します。
4070 失敗:セッション ID が無効であるか、アクティブなセッションがありません。
4071 失敗:セッション ID が無効であるか、非アクティブなセッションがありません。
4072 失敗:セッション ID が無効であるか、セッションがありません。
4073 失敗:conversionFormat が無効です。 サポートされている形式を確認し、再試行してください。
4080 失敗:指定された subscriptionUri を持つサブスクリプションはすでに存在します。
4081 失敗:指定された subscriptionUri を持つサブスクリプションは存在しません。
4082 失敗:ACTIVE または ERROR 状態のセッションを変換することはできません。
4090 失敗:jobId が無効であるか、特定のジョブがこの時点で実行されていません。
5xxx サーバ エラー応答コード

サーバは有効と思われる要求を実行できませんでした。

応答コード 説明
5000 失敗:不明なサーバ エラーが発生しました。 後でもう一度試してください。
5001 失敗:データベース エラーが発生しました。 後でもう一度試してください。
5002 失敗:セッションを一時停止できません。 後でもう一度試してください。
5003 失敗:セッションを再開できません。 後でもう一度試してください。
5004 失敗:セッションを削除できません。 後でもう一度試してください。
5006 失敗:セッションを変換できません。 後でもう一度試してください。 詳細:<Reason For Failure>
5020 失敗:Unified Communications Manager の AXL サービスがタイムアウトしました。 後でもう一度試してください。
5021 失敗:Unified Communications Manager の AXL サービスはアクティブになっていません。 サービスをアクティブにし、再試行してください。
5022 失敗:AXL 認証は無効です。 Unified Communications Manager の設定を確認し、再試行してください。
5023 失敗:不明な AXL ホスト。 Unified Communications Manager の設定を確認し、再試行してください。
5024 失敗:不明な AXL サービス エラー。 後でもう一度試してください。
5025 失敗:AXL サービスへの接続が失敗しました。 後でもう一度試してください。
5030 失敗:このシステムに関連する DeviceRef を使用してコールを確立できません。 Unified Communications Manager または Unified Border Element システムへの接続を確認し、再試行してください。
5031 失敗:コールをレコーディングできません。 MediaSense Media Service が動作していることを確認し、再試行してください。
5032 失敗:コールをレコーディングできません。 MediaSense Media Service のディスク容量が不足しています。
5040 失敗:要求を処理できません。 要求されたオペレーションのジョブの状態が無効です。 ジョブの状態を確認し、再試行してください。 詳細:<Job State>
5041 失敗:リクエストがタイムアウトになりました。 要求を再送信します。
5042 失敗:このシステムは、同時要求の最大数を超えました。 後でもう一度試してください。
5053 失敗:要求を処理できません。 アーカイブされたセッションの検索の上限を超えました。 検索を絞り込んでください。

応答メッセージ

応答メッセージでは、以下のタイプの値を使用できます。

  • 肯定応答の場合:「Success」または「Partial success」。
  • 否定応答の場合:「Failure: <text indicating reason for failure>」。

Response Body

API 応答には、要件に基づいてオプションの本文を含めることもできます(responseBody)。 responseBody 内には、前述の 2 つのキー以外にも情報が含まれます。

JSON スキーマ:

"responseBody": {//one or more optional elements within the 
 responseBody depending on the request specifications.
		        ..
                        ..
		      }

(注)  


場合によっては、すべてのパラメータが API の応答本文に存在しない可能性があります。 このような場合は、適切なパラメータのみが関連 API の応答本文に示されます。 たとえば、getSessions API の応答本文では、アクティブ セッションに duration パラメータの詳細は含まれません。


エンコード

すべての URL は URL エンコードである必要があります(パーセントエンコード)。

テキスト文字列の特殊文字

すべてのテキスト文字列に対して(パスワードを含む)、ユーザは http:/​/​www.json.org/​ の仕様に従います。また前にバックスラッシュを付けることで、特殊文字をエスケープする必要があります。

ジョブの状態

ジョブの状態 説明
RUNNING

ジョブの実行は正常に開始され、引き続き実行されています。

COMPLETED

ジョブが正常に完了しました。

(注)      「正常に完了しました」とは、すべてのオペレーションが成功したという意味ではなく、単にこのジョブのすべてのオペレーションが正常に試行されたことを示します。
CANCELED

ジョブは cancelJob API を使用して取り消され、現在は実行されていません。

ERROR

システム エラーが原因でジョブは実行を停止しました。

paramConnector および fieldConnector の優先順位ルール

getSessions のクエリー シンタックスには柔軟性があります(ただし、すべての考え得るクエリーを表現できるわけではありません)。 クエリーは、期間を AND および OR 演算子とリンクさせて形成します。各期間はフィールド名、関連する演算子、およびフィールド値で構成されます(BETWEEN の場合は 2 つのフィールド値)。 カッコを導入するには次に説明する優先順位ルールに従います。この優先順位ルールにより、期間の評価が順序付けられます。

  • 同じフィールドに複数の条件がある場合に、論理優先順位が最も高くなります。

  • AND は OR よりも優先されます。

次に例を示します。

クエリー「deviceRef=1000 or deviceRef=2000 or tagName=foo and state=active」の場合、OR とリンクされているにもかかわらず、最初の 2 つの期間の優先順位が最も高くなります。これは、同じフィールド名を参照するためです。

次に、tagName=foo and state=active が評価されます。これは、AND の優先順位が OR より高いためです。

最後に、前の 2 つの評価結果が計算されます。これは、フィールド名との組み合わせでない OR の優先順位が低いためです。

上記のクエリーをカッコで表す場合は、次のようになります。

((deviceRef=1000 or deviceRef=2000) or (tagName=foo and state=active))

上記の例は、分かりやすくするために、読み取り可能な英語に似た形式で記述しています。 ただし、実際の API 要求では、JSON 形式で表されます。 詳細な例については、getSessionsを参照してください。

エンコード

すべての URL は URL エンコードである必要があります(パーセントエンコード)。

テキスト文字列の特殊文字

すべてのテキスト文字列に対して(パスワードを含む)、ユーザは http:/​/​www.json.org/​ の仕様に従います。また前にバックスラッシュを付けることで、特殊文字をエスケープする必要があります。

要求と応答パラメータの定義

MediaSense API で使用される要求および応答パラメータのリストについては、共有パラメータを参照してください。

2 台の MediaSense Server 間のフェールオーバー

MediaSense クラスタが複数のサーバを含んでいる場合、それらのサーバの内の 2 台だけが API を処理する API サービスを提供します。 MediaSense はノード間のクライアント要求の内部リダイレクションをサポートしないため、フェールオーバーはサポートされません。 これらの REST 要求を処理する MediaSense API サービスが何らかの理由で休止中である場合、サードパーティのクライアントを示す応答コードを送信し、このサービスを提供する他の MediaSense サーバに要求をリダイレクトします。 クライアントはこの応答コードを解釈し、それに応じて要求をリダイレクトします。

MediaSense API サービスがダウンしているか、サーバ自体がダウンしている場合、クライアントは HTTP タイムアウトを処理し、他の MediaSense サーバに要求を適宜リダイレクトする必要があります。

セキュリティに関する注意事項

すべての MediaSense API は HTTPS に基づいており、自己署名証明書を使用します。 API を使用するたびにセキュリティ例外が表示されることがあります。

セキュア サーバは証明書を使用して、Web ブラウザが識別できるようにします。 独自の証明書(自己署名証明書と呼ばれる)を生成したり、認証局(CA)から証明書を取得できます。 詳細については、http:/​/​en.wikipedia.org/​wiki/​Certificate_​authority または Web ブラウザのマニュアルを参照してください。


(注)  


ポスターまたは他の類似するアプリケーションを使用して API 要求を発行する場合、まず Web ブラウザで次の URI を開いて、証明書を取得する必要があります。

https://<Cisco MediaSense IP address>>:8440


認証のための API Inter-Dependencies

MediaSense API はすべてのセッションを維持するために JSESSIONID を使用しています。そのため、(認証を必要とする)他の API を使用できるようにするには、事前にユーザを認証するために JSESSIONID が必要です。

JSESSIONID を取得するために MediaSense SignIn API を使用します。 SignIn API からの応答は次のようになります。

Header Name: Set-Cookie
Header Value: JSESSIONID=SomeRandomAlphaNumericString

認証が必要な MediaSense API を使用するたびに、SignIn API から返された JSESSIONID の値にヘッダーを設定する必要があります。

cookie の 設定に関する詳細については、 http:/​/​en.wikipedia.org/​wiki/​HTTP_​cookie を参照してください。

JSESSIONID は、ユーザがログアウトしたときか、または非アクティブになってから 30 分後(いずれか早いほう)に期限切れになります。

ポスター

すべての MediaSense API は、URI によるアクセスが可能で、要求応答パラダイムに従います。 ポスターは、Web サービスおよび Web リソースと連携する Firefox のアドオンです。これにより、Web サービスとやり取りし、結果を調べます。

ポスターを Firefox に追加する方法:

  • MediaSense API ユーザを設定します(有効なユーザ名とパスワードを使用)。

  • Firefox からポスター アドオンをダウンロードします。 https:/​/​addons.mozilla.org/​en-US/​firefox/​addon/​2691/​ から無料でダウンロードできます。

  • Firefox にポスターを追加したら、Ctrl + Alt + P を押して起動します。

ポスターの API をテストする方法:

  • Web ブラウザで次の URI を開き、受け入れることで、Web ブラウザに MediaSense セキュリティ証明書を受け入れます。

    https://<Cisco MediaSense IP address>>:8440 これは 1 回で行う必要があります。
  • この開発者ガイドからテキスト エディタに API 要求の URI をコピー アンド ペーストします。 たとえば、サインインの URI を入力するには、signIn API から URI をコピーします。

  • 貼り付けたコードの大文字と小文字の区別や形式を調べ、キャリッジ リターンをすべて削除します。

  • MediaSense サーバの IP アドレスとポートを使用して URI を更新します。

  • 要求の必須パラメータを追加します。

  • コンテンツ タイプ ヘッダーに適切な値を設定します。

  • 適切なアクションをクリックします(GET または POST)。

図 1. ポスターを使用した Cisco MediaSense API 要求

図 2. ポスターを使用した Cisco MediaSense API 応答ステータス