開発者用 SIP 透過性および正規化ガイド Cisco Unified Communications Manager Release 9.1(1)
偏向のない言語
この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
翻訳について
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
- Updated:
- 2017年5月29日
章のタイトル： SIP メッセージ API
SIP メッセージ API
Lua スクリプト作成環境には、メッセージの処理を可能にする一連の API が用意されています。これらの API について、次のカテゴリで説明します。
•
「透過性」
要求行または応答行での操作
getRequestLine
この API が応答で起動されると、実行時エラーがトリガーされます。
例：メソッド、要求 URI、プロトコル バージョンのローカル変数の値を設定します。
getRequestUriParameter
この関数では、要求 URI パラメータの文字列名が指定された場合、指定された URI パラメータの値を返されます。
• URI パラメータが「tag=value」の形式の場合、等記号の右側にある値が返されます。
• URI パラメータが値のないタグの場合、値は空文字列（例：""）で返されます。
• URI パラメータが最初のヘッダー値にない場合、nil が返されます。
• このメソッドが応答メッセージに対して起動されると、nil が返されます。
例：ローカル変数を、要求 URI のユーザ パラメータの値に設定します。
setRequestUri
このメソッドでは、要求行の要求 URI が設定されます。この API が応答で起動されると、実行時エラーがトリガーされます。
getResponseLine
このメソッドでは、プロトコル バージョン（文字列）、ステータス コード（整数）、および理由フレーズ（文字列）の 3 つの値が返されます。この API が要求に対して起動されると、実行時エラーがトリガーされます。
例：ローカル変数を、プロトコル バージョン、ステータス コード、および理由フレーズの値に設定します。
setResponseCode
このメソッドでは、ステータス コードおよび理由フレーズが設定されます。どちらの値にも nil を使用できます。値に nil が指定されている場合、メッセージに格納されている既存の値が使用されます。この API が要求に対して起動されると、実行時エラーがトリガーされます。
ヘッダーの操作
allowHeader
Cisco Unified CM が認識していないヘッダーに対するデフォルト動作では、このようなヘッダーを無視します。場合によっては、このようなヘッダーを正規化時に使用したり、ヘッダーを透過的に受け渡したりすることが望ましいこともあります。 allowHeaders テーブルでヘッダー名を指定することにより、スクリプトを使用して、Cisco Unified CM でのヘッダーの認識が可能になり、スクリプトで正規化のためにローカルで使用したり、透過的に受け渡したりすることは問題なく行えます。
allowHeaders は History-Info を指定します。指定しない場合は、スクリプトの処理前に、着信 History-Info ヘッダーがドロップされます。したがって、 convertHIToDiversion で有用な結果は得られません。このスクリプトでは、 x-pbx-id と呼ばれる仮想ヘッダーも許可されます。これは、allowHeaders がヘッダー名のテーブルであることを示しています。
getHeader
このメソッドでは、ヘッダーの文字列名が指定された場合、ヘッダーの値が返されます。同じ名前の複数ヘッダーについては、値が連結され、カンマで区切られます。
getHeaderValues
この関数では、ヘッダーの文字列名が指定された場合、値がインデックス化されたテーブルとして、ヘッダーのカンマ区切りの値が返されます。Lua のインデックス化は 1 から始まります。n 個のヘッダー値がある場合、最初の値はインデックス 1 であり、最後の値はインデックス n です。Lua の ipairs 関数では、テーブル全体で繰り返し使用できます
例：History-Info ヘッダーの値を含むローカル テーブルを作成します。
getHeaderValueParameter
このメソッドでは、ヘッダーの名前およびヘッダー パラメータが指定された場合、指定されたヘッダー パラメータの値が返されます。同じ名前の複数のヘッダーでは、最初のヘッダー値のみが評価されます。
• ヘッダー パラメータが「tag=value」の形式の場合、等記号の右側にある値が返されます。
• ヘッダー パラメータが値のないタグの場合、値は空文字列（例：""）で返されます。
• ヘッダー パラメータが最初のヘッダー値にない場合、nil が返されます。
例：ローカル変数を、tag という名前のヘッダー パラメータの値に設定します。
getHeaderUriParameter
このメソッドでは、ヘッダーの文字列名が指定された場合、指定された URI パラメータの値が返されます。同じ名前の複数のヘッダーでは、最初のヘッダー値のみが評価されます。
• URI パラメータが「tag=value」の形式の場合、等記号の右側にある値が返されます。
• URI パラメータが値のないタグの場合、値は空文字列（例：""）で返されます。
• URI パラメータが最初のヘッダー値にない場合、nil が返されます。
例：ローカル変数を、user という名前の uri パラメータの値に設定します。
addHeader
このメソッドでは、ヘッダーの文字列名および値が指定された場合、ヘッダー値のリストの 末尾 に値が付加されます。
addHeaderValueParameter
このメソッドでは、ヘッダー名、パラメータ名、およびオプション パラメータ値が指定された場合、SIP メッセージで指定されたヘッダーが検索され、指定されたヘッダー パラメータおよびオプション パラメータ値がヘッダーに追加されます。SIP メッセージで、元のヘッダーが変更されたヘッダー値に置き換えられます。指定されたヘッダーに対して複数のヘッダー値がある場合、最初のヘッダー値のみが変更されます。指定されたヘッダーのインスタンスが SIP メッセージにない場合、アクションは実行されません。
例：発信 Contact ヘッダーに color=blue ヘッダー パラメータを追加します。
addHeaderUriParameter
このメソッドでは、ヘッダー名、パラメータ名、およびオプション パラメータ値が指定された場合、SIP メッセージで指定されたヘッダーが検索され、指定されたヘッダー URI パラメータおよびオプション URI パラメータ値が、含まれている URI に追加されます。SIP メッセージで、元のヘッダーが変更されたヘッダー値に置き換えられます。指定されたヘッダーに対して複数のヘッダー値がある場合、最初のヘッダー値のみが変更されます。SIP メッセージに指定されたヘッダーのインスタンスがない場合、または、指定されたヘッダーの最初のインスタンス内に有効な URI が見つからない場合、アクションは実行されません。
例：P-Asserted-Identity URI に、user=phone パラメータを追加します。
modifyHeader
このメソッドでは、ヘッダーの文字列名および値が指定された場合、既存のヘッダー値が指定された値で上書きされます。これは、removeHeader が起動された後で addHeader が起動される動作に実際似ています。
例：発信 INVITE メッセージの P-Asserted-Identity ヘッダーから、表示名を削除します。
applyNumberMask
このメソッドでは、ヘッダー名および番号マスクが指定された場合、SIP メッセージで指定されたヘッダーが検索され、指定された番号マスクが、ヘッダー内に含まれている URI に適用されます。URI がヘッダー値から正常に解析された場合、解析された URI のユーザ部分に番号マスクが適用されます。SIP メッセージで、元のヘッダーが変更されたヘッダー値に置き換えられます。指定されたヘッダーに複数のインスタンスがある場合、ヘッダーの最初のインスタンスのみが変更されます。
次のいずれかの条件を満たす場合、アクションは実行されません。
1. 指定されたヘッダーのインスタンスが、SIP メッセージにない場合
番号マスクの適用
マスク パラメータによって、ヘッダー URI のユーザ部に適用される変換が定義されます。マスク パラメータでは、大文字の X でワイルド カード文字が指定されます。たとえば、マスク「+1888XXXXXXX」が指定されている場合、マスクの挿入文字として「X」が使用されます。このマスクが例のユーザ部「4441234」に適用される場合、結果の文字列は「+18884441234」になります。
マスクされるユーザ部に見つかった文字数が、マスクのワイルド カード文字数よりも少ない場合、一番左のワイルド カード文字から「X」が置かれます。前述のマスクを例のユーザ部「1234」に適用すると、結果の文字列は「+1888XXX1234」になります。マスクされるユーザ部に見つかった文字数が、マスクのワイルド カード文字数よりも多い場合、ユーザ部の一番左の文字から切り捨てられます。たとえば、マスク「+1888XXXX」がユーザ部「4441234」に適用される場合、結果の文字列は「+18881234」になります。
例：着信 INVITE メッセージの P-Asserted-Identity ヘッダーの番号に番号マスクを適用します。
convertDiversionToHI
Cisco Unified CM では、リダイレクト情報を処理するための Diversion ヘッダーの送信がサポートされます。たとえば、Cisco Unified CM によってコールが転送される場合について考えます。このような例では、リダイレクト番号の送信のために Cisco Unified CM で使用される Diversion ヘッダーが、SIP メッセージに含まれる場合があります。ただし、多くの SIP サーバでは、この目的で、Diversion ヘッダーの代わりに History-Info ヘッダーが使用されます。この API を使用して、Diversion ヘッダーが History-Info ヘッダーに変換されます。
（注） 一部の実装では、この API の代わりまたはこの API に加えて、raw ヘッダー API（例：getHeader、addHeader、modifyHeader、removeHeader）の使用が必要です。
例：発信 INVITE メッセージで、Diversion ヘッダーを History-Info ヘッダーに変換します。次に、Diversion ヘッダーを削除します
convertHIToDiversion
Cisco Unified CM では、リダイレクト情報を処理するための Diversion ヘッダーの受信がサポートされます。たとえば、Cisco Unified CM に到達する前にコールが転送される場合について考えます。このような場合、リダイレクト番号の確立のために Cisco Unified CM で使用される Diversion ヘッダーが、SIP メッセージに含まれることがあります。ただし、多くの SIP サーバでは、この目的で、Diversion ヘッダーの代わりに History-Info ヘッダーが使用されます。
（注） 一部の実装では、この API の代わりまたはこの API に加えて、raw ヘッダー API（例：getHeader、addHeader、modifyHeader、removeHeader）の使用が必要な場合があります。
（注） Diversion ヘッダーは、History-Info ヘッダーに「cause=」タグが存在する場合にだけ追加されます。以下の例では、Diversion ヘッダーが 1 つしかないが、History-Info ヘッダーが 2 つある場合、そのうちの 1 つには「cause=」タグがあることに注意してください。
allowHeaders では、「History-Info」を指定する必要があります。指定しない場合、スクリプトの処理前に、着信 History-Info ヘッダーがドロップされます。したがって、convertHIToDiversion へのコールで有用な結果は得られません。
removeHeader
このメソッドでは、ヘッダーの文字列名が指定された場合、メッセージからヘッダーが削除されます。
例：発信 INVITE メッセージから、Cisco-Guid ヘッダーを削除します。
removeHeaderValue
このメソッドでは、ヘッダーの文字列名およびヘッダー値が指定された場合、メッセージからヘッダー値が削除されます。値がヘッダー値だけだった場合、ヘッダーそのものが削除されます。
例：発信 INVITE メッセージのサポート ヘッダーから、X-cisco-srtp-fallback を削除します。
SDP の操作
• getSdp
• setSdp
getSdp
このメソッドでは、Lua 文字列として SDP が返されます。メッセージに SDP が含まれない場合、nil が返されます。
例：SDP が含まれるローカル変数を確立します（SDP がない場合は nil）。
変数 sdp が次の文字列に設定されます。この文字列には、組み込みの復帰改行文字および改行文字（つまり「\r\n」）が含まれていることに注意してください。
setSdp
このメソッドでは、SIP メッセージで指定された文字列を SDP コンテンツ本文として保存します。SIP メッセージの Content-Length ヘッダーは、文字列の長さに自動的に更新されます。
前述のスクリプト実行後の最後の SIP メッセージは、次のようになります。
INVITE sip:901@rawlings.cisco.com:5080 SIP/2.0
Via: SIP/2.0/TCP 172.18.197.88:5080;branch=z9hG4bK4bae847b2
From: <sip:579@172.18.197.88>;tag=9f12addc-04fc-4f0f-825b-3cd7d6dd8813-25125665
To: <sip:901@rawlings.cisco.com>
Date: Thu, 28 Jan 2010 01:09:39 GMT
Call-ID: cd80d100-b601e3d3-15-58c512ac@172.18.197.88
.
.
Max-Forwards: 69
Content-Type: application/sdp
Content-Length: 214
v=0
o=CiscoSystemsCCM-SIP 2000 1 IN IP4 172.18.197.88
s=SIP Call
c=IN IP4 172.18.197.88
t=0 0
m=audio 24580 RTP/AVP 0 101
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
removeUnreliableSdp
このメソッドでは、18X メッセージから SDP が削除されます。SCDP を削除する前に、メッセージでは、PRACK が必要ではないことが確認されます。
（注） Content-Length ヘッダーへの調整は、この API によって SDP が実際に削除されるときに、自動的に行われます。メッセージに他のコンテンツ本文がない場合、Content-Type ヘッダーは自動的に削除されます。
コンテンツ本文の操作
getContentBody
この関数では、content-type の文字列名が指定された場合、content-body、content-disposition、content-encoding、および content-language が返されます。content-disposition、content-encoding、および content-language はオプションで、メッセージで指定されていない場合があります。メッセージで特定のヘッダーが指定されていない場合、その値には nil が返されます。
メッセージに content-body がない場合、返されるすべての項目に nil 値が含まれます。
例：発信 INFO メッセージのコンテンツ情報が含まれるローカル変数を確立します。
Local variable b is set to the string:
p=Digit-Collection
y=Digits
s=success
u=12345678
i=87654321
d=4
addContentBody
この API では、content-type および content-body が指定された場合、メッセージにコンテンツ本文が追加され、content-length ヘッダーに必要な変更が行われます。スクリプトでは、オプションで、ディスポジション、エンコード、および言語も指定できます。
例：発信 UPDATE メッセージに、プレーン テキストのコンテンツ本文を追加します。
.
.
removeContentBody
この API では、content-type が指定された場合、関連付けられているコンテンツ本文がメッセージから削除され、content-length ヘッダーに必要な変更が行われます。
例：発信 UPDATE メッセージから text/plain コンテンツ本文を削除します。
メッセージのブロック
• block
block
このメソッドでは、着信または発信の信頼できない 18X メッセージをブロックできます。着信のブロックでは、メッセージを受信しなかったものとして CUCM が動作します。発信メッセージのブロックでは、CUCM によってネットワークにメッセージが送信されません。
（注） PRACK が有効で、メッセージが実際は信頼できる 18X の場合、CUCM では block() への呼び出しは事実上無視します。メッセージはブロックされず、エラー SDI トレースが生成されます。
透過性
getPassThrough
このメソッドでは、SIP パススルー オブジェクトが返されます。これは、着信メッセージに対して起動できます。パススルー オブジェクトに追加される情報は、他のコール レッグで生成された発信メッセージに自動的に結合されます。この情報の自動結合は、（必要に応じて）発信の正規化の前に発生します。
パススルー オブジェクトの使用および例については、 SIP パススルー APIを参照してください。
Per-Dialog コンテキストの管理
getContext
このメソッドでは、コールごとのコンテキストが返されます。コンテキストは Lua テーブルです。このスクリプト作成者は、ダイアログの継続中に使用される、多様なメッセージ ハンドラでのコンテキストからデータを保存および取得することができます。スクリプト作成者は、ダイアログの最後でコンテキストの解放を考慮する必要はありません。コンテキストは、ダイアログの終了時に、Cisco Unified CM によって自動的に解放されます。
このスクリプトでは、コンテキストを使用して、INVITE で受信した History-Info ヘッダーが保存されます。その INVITE への応答が送信されると、保存されたヘッダーが取得され、発信応答に追加されます。「clear」パラメータを使用して、後続の reINVITE 応答にこれらのヘッダーが追加されることを防止します。
context["History-Info"] = nil
.
SIP/2.0 200 OK
.
Content-Type: application/sdp
ユーティリティ
• getUri
isInitialInviteRequest
このメソッドでは、メッセージが要求であり、メソッドが INVITE であり、To ヘッダーにタグ パラメータがない場合に、真が返されます。これ以外の場合は、偽が返されます。
発信 INVITE が初期 INVITE かどうかに基づいて、ローカル変数を設定します。この例では、INVITE は初期 INVITE です。したがって、この場合の INVITE については、値は真になります。
発信 INVITE が初期 INVITE かどうかに基づいて、ローカル変数を設定します。この例では、INVITE は初期 INVITE ではありません。したがって、この場合の INVITE については、値は偽になります。
isReInviteRequest
このメソッドでは、メッセージが要求であり、メソッドが INVITE であり、To ヘッダーにタグ パラメータが 1 つある場合に、真が返されます。これ以外の場合は、偽が返されます。
発信 INVITE が reINVITE かどうかに基づいて、ローカル変数を設定します。この例では、INVITE は reINVITE です。したがって、この場合の INVITE については、値は真になります。
発信 INVITE が reINVITE かどうかに基づいて、ローカル変数を設定します。この例では、INVITE は reINVITE ではありません。したがって、この場合の INVITE については、値は偽になります。
getUri
このメソッドでは、ヘッダー名が指定された場合、SIP メッセージで指定されたヘッダーが検索され、そのヘッダーからの URI の取得が試行されます。指定されたヘッダーに複数のインスタンスがある場合、ヘッダーの最初のインスタンスの URI が返されます。SIP メッセージに指定されたヘッダーのインスタンスがない場合、または、指定されたヘッダーの最初のインスタンス内に有効な URI が見つからない場合、Lua nil が返されます。
例：ローカル変数を、P-Asserted-Identity ヘッダーの URI に設定します。
フィードバック