Cisco MediaSense 開発者ガイド リリース 11.0(1)
録音制御 API
録音制御 API

録音制御 API

はじめに

MediaSense が提供する録音制御 API により、サードパーティ製クライアントがセッションの録音を制御できるようになります。

サードパーティ製クライアントは、現在進行中(アクティブ)のセッションの録音を一時停止したり、再開したりできます。次の条件がこれらの API に適用されます。

  • アクティブなセッションの録音でのみこの API を使用できます。
  • 一時停止中の録音だけを再開できます。

MediaSense は、別の種類の制御も提供します。これにより、サードパーティ製クライアントは MediaSense から電話機へのコールをトリガーし、コールが応答されたらすぐに録音を開始できます。 これは Direct Outbound Recording と呼ばれます。 対応する API はこの方法で開始された録音を停止できます。 これらの API を使用して、ブログやビデオ メッセージを録音できます。


(注)  


Direct Outbound Recording は、Unified Communications Manager 電話機でのみサポートされます。

録音を開始するには、デバイス参照で startRecording API によって開始されたコールに応答する必要があります。 電話を切るか、そのデバイス参照で stopRecording API を呼び出すことにより、録音を停止できます。

通話中のコーデック変更は、ダイレクト受信コールまたはダイレクト発信コールではサポートされていません。


pauseRecording

この API を使用して、セッションの録音を一時停止します。

URI

https://<host>:<port>/ora/controlService/control/pauseRecording

HTTP メソッド

POST

パラメータ

sessionId:セッションのシステム生成識別子。 共有パラメータを参照してください。

関連イベント

tagEvent:タグがセッションに追加またはセッションから削除された場合にイベントが送信されます。 詳細については、tagEventを参照してください。

現在進行中の録音を一時停止する方法:

HTTPS POST:

https://10.194.118.1:8440/ora/controlService/control/
pauseRecording

ヘッダー:

Content-Type: application/json
JSESSIONID: <the jsessionId received from a signIn request>

ボディ:

{
   requestParameters: {
                        "sessionId": "Session-1234.abc.
                         5678"
                      }
}

応答:

 {
    "responseCode": 2000,
    "responseMessage": "Successful"
}

resumeRecording

この API を使用して、セッションの録音を再開します。

URI

https://<host>:<port>/ora/controlService/control/resumeRecording

HTTP メソッド

POST

パラメータ

sessionId:セッションのシステム生成識別子。 共有パラメータを参照してください。

関連イベント

tagEvent:タグがセッションに追加またはセッションから削除された場合にイベントが送信されます。 詳細については、tagEventを参照してください。

HTTPS POST:

 https://10.194.118.1:8440/ora/controlService/control/
resumeRecording

ヘッダー:

Content-Type: application/json
JSESSIONID: <the jsessionId received from a signIn 
request>

ボディ:

{
   requestParameters: {
                        "sessionId": "Session-1234.abc.
                         5678"
                      }
}

応答:

{
    "responseCode": 2000,
    "responseMessage": "Successful"
}

startRecording

この API を使用して MediaSense で電話機にコールし、受信者のオーディオおよびビデオ入力を録音します。

URI

https://<host>:<port>/ora/controlService/control/startRecording

HTTP メソッド

POST

パラメータ(Parameters)

  • codec:出力文字列。 トラックのコーデック。 共有パラメータを参照してください。

  • deviceId:出力文字列。 デバイスの一意の識別子。 共有パラメータを参照してください。

  • deviceRef:出力文字列。 各デバイスの電話番号。 共有パラメータを参照してください。

  • downloadUrl:出力文字列。 raw 形式で録音をダウンロードするために使用される URL。 共有パラメータを参照してください。

  • httpUrl:出力文字列。 セッションの HTTPS リンクです。 共有パラメータを参照してください。

  • isConference:出力ブール。 参加者が会議ブリッジまたは個々のデバイスであるかどうかを示します。 共有パラメータを参照してください。

  • mediaType:出力文字列。 作成中のメディアのタイプです。 共有パラメータを参照してください。

  • mediaStreams:メディア タイプの必須入力アレイ。 作成中のメディア ストリーム。 各ストリームはメディア タイプです。 したがって、mediaStreams はメディア タイプのアレイです。 録音には、少なくとも 1 個のメディア ストリームが必要です。 アレイは順序付けされていません。 これは必須の入力です。

  • mp4Url:出力文字列。 セッションの mp4 リンク。 共有パラメータを参照してください。

  • offset:オプション入力整数。 pageParameters 内の必須の入力整数になります。 返される最初のレコード。 共有パラメータを参照してください。

  • participantDuration:出力整数。 セッション内で参加者がアクティブだった期間(ミリ秒単位)。 共有パラメータを参照してください。

  • participants:参加者オブジェクトの出力 JSON アレイ。 共有パラメータを参照してください。

  • participantStartDate:出力整数。 1970 年 1 月 1 日 GMT からこのトラックの録音が開始されるまでに経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • rtspUrl:出力文字列。 複数のトラックを含むことができるセッション全体への参照です。 共有パラメータを参照してください。

  • sessions:セッション オブジェクトの出力 JSON アレイ。 共有パラメータを参照してください。

  • sessionId:必須入力文字列。 システムで生成されるセッションの一意の識別子です。 共有パラメータを参照してください。

  • sessionStartDate:出力整数。 1970 年 1 月 1 日 GMT からセッションの録音が開始されるまでに経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • sessionState:出力文字列。 セッションのステート。 共有パラメータを参照してください。

  • tags:タグ オブジェクトの出力 JSON アレイ。 共有パラメータを参照してください。

  • tagCreateDate:出力整数。 1970 年 1 月 1 日 GMT からタグの作成までに経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • tagName:出力文字列。 録音を分類するために使用される大文字と小文字を区別しない名前。 共有パラメータを参照してください。

  • tagOffset:出力整数。 このタグのセッション開始から経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • tagType:出力文字列。 共有パラメータを参照してください。

  • trackDuration:出力整数。 トラックが継続した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • trackMediaType:出力整数。 共有パラメータを参照してください。

  • trackNumber:出力整数。 システムで生成されるトラックの一意の識別子。 共有パラメータを参照してください。

  • tracks:トラック オブジェクトの出力 JSON アレイ。 共有パラメータを参照してください。

  • trackStartDate:出力整数。 1970 年 1 月 1 日 GMT からトラックの録音が開始されるまでに経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • urls:出力 JSON オブジェクト。 httpUrl および rtspUrl パラメータの情報が含まれます。 共有パラメータを参照してください。

  • wavUrl:出力文字列。 セッションの wav リンク。 共有パラメータを参照してください。

  • xRefCi:出力文字列。 特定のメディア ストリームに対する Unified Communications Manager 識別子。 共有パラメータを参照してください。


(注)  


この API では、Cisco MediaSense 管理のコール制御サービス プロバイダーを設定し、発信先の電話機がその Unified Communications Manager にアクセスできることが必要です。


関連イベント

sessionEvent:このイベントは、録音セッションが開始されるか、既存の録音セッションが更新または終了されるたびに送信されます。 詳細については、sessionEventを参照してください。

例 1

deviceRef 1000 を使用したデバイスでオーディオおよびビデオ トラックを含むブログの録音を開始する方法:

HTTPS POST:

https://10.194.118.1:8440/ora/controlService/control/
startRecording 

ヘッダー:

Content-Type: application/json
JSESSIONID: <the jsessionId received from a signIn 
request>

ボディ:

{
    "requestParameters": {
        "deviceRef": "1000",
        "mediaStreams": [
            {
                "mediaType": "VIDEO"
            },
            {
                "mediaType": "AUDIO"
            }
        ]
    }
}

例 2

deviceRef 1111 を使用したデバイスでオーディオ トラックだけが含まれるブログの録音を開始する方法:

HTTPS POST:

https://10.194.118.1:8440/ora/controlService/control/
startRecording 

ヘッダー:

Content-Type: application/json
JSESSIONID: <the jsessionId received from a signIn 
request>

ボディ:

{
    "requestParameters": {
        "deviceRef": "1111",
        "mediaStreams": [
            {
                "mediaType": "AUDIO"
            }
        ]
    }
}

stopRecording

この API を使用して、発信コール(startRecording API により開始)の終了後すぐにデバイスの録音を停止します。

URI

https://<host>:<port>/ora/controlService/control/stopRecording

HTTP メソッド

POST

パラメータ(Parameters)

  • codec:トラックのコーデック。 共有パラメータを参照してください。

  • deviceId:デバイスの一意の識別子。 共有パラメータを参照してください。

  • deviceRef:各デバイスの電話番号。 共有パラメータを参照してください。

  • downloadUrl:RAW 形式で録音をダウンロードするために使用される URL。 共有パラメータを参照してください。

  • httpUrl:セッションの HTTPS リンク。 共有パラメータを参照してください。

  • isConference:参加者が会議ブリッジまたは個々のデバイスであるかどうかを示します。 共有パラメータを参照してください。

  • mp4Url:セッションの mp4 リンク。 共有パラメータを参照してください。

  • offset:返される最初のレコード。 共有パラメータを参照してください。

  • participantDuration:セッション内で参加者がアクティブだった期間(ミリ秒単位)。 共有パラメータを参照してください。

  • participants:参加者オブジェクトの JSON アレイ。 共有パラメータを参照してください。

  • participantStartDate:1970 年 1 月 1 日 GMT からこのトラックの録音が開始されるまでに経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • rtspUrl:複数のトラックを含むことができるセッション全体への参照。 共有パラメータを参照してください。

  • sessions:セッション オブジェクトの JSON アレイ。 共有パラメータを参照してください。

  • sessionDuration:セッションが継続した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • sessionId:システムで生成されるセッションの一意の識別子。 共有パラメータを参照してください。

  • sessionStartDate:1970 年 1 月 1 日 GMT からセッションの録音が開始されるまでに経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • sessionState:セッションの状態。 共有パラメータを参照してください。

  • tags:タグ オブジェクトの JSON アレイ。 共有パラメータを参照してください。

  • tagCreateDate:1970 年 1 月 1 日 GMT からタグの作成までに経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • tagName:録音を分類するために使用される大文字と小文字を区別しない名前。 共有パラメータを参照してください。

  • tagOffset:このタグのセッション開始から経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • tagType:出力文字列。 共有パラメータを参照してください。

  • trackDuration:トラックが継続した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • trackMediaType:出力整数。 共有パラメータを参照してください。

  • trackNumber:システムで生成されるトラックの一意の識別子。 共有パラメータを参照してください。

  • tracks:トラック オブジェクトの JSON アレイ。 共有パラメータを参照してください。

  • trackStartDate:1970 年 1 月 1 日 GMT からトラックの録音が開始されるまでに経過した時間(ミリ秒単位)。 共有パラメータを参照してください。

  • urls:httpUrl および rtspUrl パラメータの情報が含まれます。 共有パラメータを参照してください。

  • wavUrl:セッションの wav リンク。 共有パラメータを参照してください。

  • xRefCi:特定のメディア ストリームに対する Unified Communications Manager 識別子。 共有パラメータを参照してください。

関連イベント

sessionEvent:このイベントは、録音セッションが開始されるか、既存の録音セッションが更新または終了されるたびに送信されます。 詳細については、sessionEventを参照してください。

deviceRef 1000 を使用したデバイスで進行中のブログ録音を停止する方法:

HTTPS POST:

https://10.194.118.1:8440/ora/controlService/control/
stopRecording

ヘッダー:

Content-Type: application/json
JSESSIONID: <the jsessionId received from a signIn request>

ボディ:

{	"requestParameters":
			{
                            "deviceRef": "1000"
			 }
}

launchMediaPlayer

この API を使用して MediaSense メディア プレーヤーを起動し、特定の録音を再生します。 この API は、ブラウザのプロキシとして機能するサーバ ベースのアプリケーションと連携するように設計されています。 ただし、ブラウザで直接 API を呼び出すこともできます。 アプリケーションがブラウザ クライアントの代わりにこの要求を発行すると、実行のためにそのブラウザに JNLP ファイルを渡します。 それから、ブラウザは直接 MediaSense とやり取りして、プレーヤー アプリケーションをダウンロードし、再生するメディア ストリームを取得します。 API パラメータは JSON で、URL ではありません。

URI

https://<host>:<port>/ora/controlService/control/launchMediaPlayer

HTTP メソッド

GET

パラメータ

rtspUrl:このパラメータは、URL のクエリー セクションで指定する必要があります。

rtspUrl=<ユーザが指定した文字列>

rtspUrl は起動時にメディア プレイヤーで再生するセッションの rtsp URL です。 この URL は、クエリー API(getSessions など)を使用して取得します。 クライアントは、launchMediaPlayer 要求で使用する少し前に MediaSense からこの rtspUrl を取得します。 MediaSense により提供されるすべての URL と同様に、録音されたセッションの rtspUrl は予告なしに随時変更されることがあります。


(注)  


クライアント マシンに Java の特定のバージョンをインストールする必要があります。 Java 要件の詳細については、次の URL にある『MediaSense User Guide』の「Search and Play」の項を参照してください。http:/​/​www.cisco.com/​c/​en/​us/​support/​customer-collaboration/​mediasense/​tsd-products-support-maintain-and-operate.html


例 1

メディア プレイヤーの rtspUrl 「13092154564622」でセッションを再生する方法:

HTTPS GET:https://<server>:<port>/ora/controlService/control/launchMediaPlayer?rtspUrl=rtsp://<server>/archive/2413e6746c8441

ヘッダー:JSESSIONID(前の signIn 要求から受信した jsessionID)

応答:


(注)  


この応答は、説明のみを目的としています。 アプリケーションでこの応答を解析する必要はありません。 Java が正常にインストールされている場合、この応答により JWS を使用したメディア プレイヤー アプレットが自動的に起動されます。


...
Content-type: application/x-java-jnlp-file
...

<?xml version="1.0" encoding="UTF-8"?>
<jnlp codebase="https://<server>:<port>/mediasense/
 " spec="1.0+">
   <information>
      <title>MediaSensePlayer</title>
      <vendor>Cisco Systems</vendor>
      <homepage href="http://www.cisco.com" />
      <description>MediaSensePlayer</description>
      <description kind="short">MediaSensePlayer</description>
   </information>
   <update check="always" />
   <security>
      <all-permissions />
   </security>
   <resources>
      <j2se version="1.7.0_11" />
      <jar href="java/MediaSensePlayer.jar" main="true" />
      <jar href="java/jna-3.4.0.jar" />
   </resources>
   <application-desc main-class="com.cisco.cbabu.videoplayer.
    Main">
      <argument>rtsp://<server>/archive/2413e6746c8441?
       token=HQFmZ0yl2ynton0CvOKMifXwe6gBONLAOeMqaPzw2jTrrbhh
       SjbnjOr2siZJmIIqcg2gJDNsFpMrDheQyUGYveUhDQAwdT6ze6mQeek
       JPhipAhtI15Rrfaackd6r6jlj</argument>
   </application-desc>
</jnlp>

例 2

失敗した応答の例。 (GET 要求が必要な rtspUrl パラメータなしで送信された場合)。

HTTPS GET:https://<server>:<port>/ora/controlService/control/launchMediaPlayer

ヘッダー:JSESSIONID(前の signIn 要求から受信した jsessionID)

応答:

...
Content-type: application/json
...

{
    "responseMessage": "Failure: Missing parameter in message.",
    "responseCode": 4061,
    "detail": "rtspUrl"
}