添付での MTOM の使用法
SOAP 要求と応答のメッセージに添付を追加できます。この実行方法としては、MTOM (Message Transmission Optimization Mechanism) に対する InterSystems IRIS® データ・プラットフォーム・サポートの使用が推奨されます。
ポリシー内で MTOM の使用について指定することもできます。"Web サービスの保護" を参照してください。
また、パッケージ化の後で gzip を使用してメッセージを圧縮するように InterSystems IRIS® データ・プラットフォーム Web サービスと Web クライアントを構成することもできます。"InterSystems IRIS での Web サービスの調整" と "InterSystems IRIS での Web クライアントの調整" を参照してください。
添付および SOAP メッセージのパッケージ化
一般に添付は、バイナリ・データの伝送に使用されます。InterSystems IRIS の SOAP サポートでは、SOAP メッセージをパッケージ化する方法が 3 種類用意されています。詳細を説明する前に、このパッケージ化方法を確認しておきます。
-
すべてのパーツをインラインにしてメッセージをパッケージ化します (添付なし)。バイナリ・データのすべてに Base 64 のエンコードを使用します。
Web サービスが MTOM 要求を受信する場合 (サービスが MTOM 応答で返信する) を除き、これは InterSystems IRIS Web サービスおよび Web クライアントの既定の動作です。
-
MTOM (Message Transmission Optimization Mechanism) 仕様に従ってメッセージをパッケージ化します。この場合、すべてをインライン化するメッセージと比較して若干コンパクトになります。現在、SOAP メッセージについてはこちらの方法が推奨されます。
この方法を採用した場合、状況に応じて SOAP メッセージが自動的にパッケージ化されます。つまり、MIME パーツが必要に応じて作成され、ユーザの操作を必要とせずにメッセージに追加されます。
また、InterSystems IRIS で MTOM パッケージを作成する際の既定として、添付を使用してバイナリ・ストリームが出力され、バイナリ文字列 (%BinaryOpens in a new tab または %xsd.base64BinaryOpens in a new tab) がインラインで出力されます。この動作は制御が可能です。
MTOM の仕様へのリンクは、"SOAP 標準" を参照してください。
-
SOAP With Attachments 仕様に従ってメッセージをパッケージ化します。この場合、すべてをインライン化するメッセージと比較して若干コンパクトになります。
この方法を採用した場合は、MIME パーツを作成し、そのパーツにデータを入力し、必要に応じて MIME ヘッダを指定して、パーツを SOAP メッセージに添付するという手動作業が必要になります。一般に、この方法では MTOM を採用した場合より多くの作業が必要です。"SOAP With Attachments の使用法" を参照してください。
すべてのパーツをインライン化した SOAP メッセージ (既定)
SOAP メッセージをパッケージ化する既定の方法は、すべての要素をインライン・パーツとして組み込む方法です (つまり、添付はありません)。バイナリ・データもすべて Base 64 でエンコードされたデータとしてインラインに組み込まれます。以下に例を示します (読みやすくするため改行およびスペースが追加されています)。
HTTP/1.1 200 OK
Date: Wed, 19 Nov 2008 21:57:50 GMT
Server: Apache
SET-COOKIE: CSPSESSIONID-SP-8080-UP-csp-gsoap-=003000010000248
guobl000000K7opwlDlY$XbvrGR1eYZsA--; path=/csp/mysamples/;
CACHE-CONTROL: no-cache
EXPIRES: Thu, 29 Oct 1998 17:04:19 GMT
PRAGMA: no-cache
TRANSFER-ENCODING: chunked
Connection: close
Content-Type: text/xml; charset=UTF-8
1d7b
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/'
xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance'
xmlns:s='https://www.w3.org/2001/XMLSchema'>
<SOAP-ENV:Body>
<DownloadResponse xmlns="https://www.filetransfer.org">
<DownloadResult><Filename>sample.pdf</Filename>
<IsBinary>true</IsBinary>
<BinaryContents>
[very long binary content not shown here]
</BinaryContents></attachment></Upload>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
このパッケージでは MIME が使用されず、また、メッセージ範囲もないことがわかります。
MTOM パッケージ化を使用した SOAP メッセージ
SOAP メッセージをパッケージ化する 2 つ目の方法は、MTOM (Message Transmission Optimization Mechanism) の仕様に従って MIME パーツを使用する方法です。バイナリ・データは、独立した MIME パートに配置され、Base 64 エンコードは使用されません。SOAP メッセージには、必要に応じて独立したパーツへの参照が組み込まれます。以下に例を示します (読みやすくするため改行およびスペースが追加されています)。
HTTP/1.1 200 OK
Date: Wed, 19 Nov 2008 21:54:57 GMT
Server: Apache
SET-COOKIE: CSPSESSIONID-SP-8080-UP-csp-gsoap-=003000010
000247guhlx000000NW1KN5UtWg$CWY38$bbTOQ--; path=/csp/mysamples/;
CACHE-CONTROL: no-cache
EXPIRES: Thu, 29 Oct 1998 17:04:19 GMT
MIME-VERSION: 1.0
PRAGMA: no-cache
TRANSFER-ENCODING: chunked
Connection: close
Content-Type: multipart/related; type="application/xop+xml";
boundary=--boundary388.5294117647058824932.470588235294118--;
start="<0.B1150656.EC8A.4B5A.8835.A932E318190B>"; start-info="text/xml"
1ddb
----boundary388.5294117647058824932.470588235294118--
Content-Type: application/xop+xml; type="text/xml"; charset="UTF-8"
Content-Transfer-Encoding: 8bit
Content-Id: <0.B1150656.EC8A.4B5A.8835.A932E318190B>
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/'
xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance'
xmlns:s='https://www.w3.org/2001/XMLSchema'>
<SOAP-ENV:Body>
<DownloadResponse xmlns="https://www.filetransfer.org">
<DownloadResult>
<Filename>sample.pdf</Filename>
<IsBinary>true</IsBinary>
<BinaryContents>
<xop:Include href="cid:1.B1150656.EC8A.4B5A.8835.A932E318190B"
xmlns:xop="https://www.w3.org/2004/08/xop/include"/>
</BinaryContents></DownloadResult></DownloadResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
----boundary388.5294117647058824932.470588235294118--
Content-Id: <1.B1150656.EC8A.4B5A.8835.A932E318190B>
Content-Transfer-Encoding: binary
CONTENT-TYPE: application/octet-stream
[very long binary content not shown here]
既定のパッケージと比べて次のような違いがあります。
-
メッセージには MIME パーツがあり、したがって境界が含まれます。
-
MIME パーツには Content-ID 属性があります。
-
SOAP 本文では、BinaryContents 要素はそのコンテンツ ID への参照で構成されています。
SOAP With Attachments
SOAP メッセージをパッケージ化する 3 つ目の方法は、SOAP With Attachments 仕様を使用する方法です。この場合も MIME パーツが使用されますが、メッセージのパッケージ化方法は MTOM と少し異なります。以下に例を示します (読みやすくするため改行およびスペースが追加されています)。
HTTP/1.1 200 OK
Date: Mon, 09 Nov 2009 17:47:36 GMT
Server: Apache
SET-COOKIE: CSPSESSIONID-SP-8080-UP-csp-gsoap-=
000000010000213eMwn70000004swjTo4cGuInLMU1n7jaPg--; path=/csp/mysamples/;
CACHE-CONTROL: no-cache
EXPIRES: Thu, 29 Oct 1998 17:04:19 GMT
MIME-VERSION: 1.0
PRAGMA: no-cache
TRANSFER-ENCODING: chunked
Connection: close
Content-Type: multipart/related; type="text/xml";
boundary=--boundary2629.3529411764705883531.411764705882353--
1ca2
----boundary2629.3529411764705883531.411764705882353--
Content-Type: text/xml; charset="UTF-8"
Content-Transfer-Encoding: 8bit
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/'
xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance'
xmlns:s='https://www.w3.org/2001/XMLSchema'>
<SOAP-ENV:Body><DownloadBinaryResponse xmlns="https://www.filetransfer.org">
<DownloadBinaryResult>MQ==</DownloadBinaryResult></DownloadBinaryResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
----boundary2629.3529411764705883531.411764705882353--
Content-Transfer-Encoding: binary
Content-Type: application/octet-stream
%PDF-1.4
%âãÏÓ
86 0 obj
<</Length 87 0 R
/Filter /FlateDecode
>>
stream
[stream not shown]
MTOM と同じように境界文字列があり、添付は MIME パートです。一方、MTOM と異なる点として、その MIME パートにはコンテンツ ID がなく、SOAP の本文にもその MIME パートの参照が存在しません。
InterSystems IRIS Web サービスおよび Web クライアントの既定の動作
既定では、InterSystems IRIS Web サービスは次のように動作します。
-
MTOM パッケージで要求を受け取ると、Web サービスはその応答を MTOM パッケージとして送信します。
また、Web サービス・インスタンスの IsMTOM プロパティは、1 に設定されます。
-
MTOM パッケージ以外の要求を受け取ると、Web サービスはその応答を MTOM パッケージ以外で送信します。
既定では、InterSystems IRIS Web クライアントは次のように動作します。
-
要求を MTOM パッケージとして送信しません。
-
応答が MTOM パッケージであるかどうかに関わらず、応答を処理します。
応答が MTOM パッケージである場合、Web クライアント・インスタンスの IsMTOM プロパティは、1 に設定されます。応答が MTOM パッケージでない場合は、IsMTOM プロパティは変更されません。
応答を MTOM パッケージとして強制する
InterSystems IRIS Web サービスに対して、すべての応答を MTOM パッケージとして送信するように強制できます。これを実行するには、次のいずれかの操作を行います。
-
InterSystems IRIS Web サービス・クラスで MTOMREQUIRED パラメータを 1 に設定します。
-
InterSystems IRIS Web サービス・インスタンスで MTOMRequired プロパティを 1 に設定します。これは、Web メソッド内または OnPreWebMethod() コールバック内で実行できます。このコールバックの概要は、"Web サービスのコールバックのカスタマイズ" を参照してください。
-
MTOM パッケージを送信するように、Web サービスのポリシー文を添付します。そのためには、Web サービス・クラスを参照する構成クラスを作成およびコンパイルし、このポリシー内で MTOM の使用を有効にします。"Web サービスの保護" を参照してください。
このようなポリシー文を添付すると、MTOMREQUIRED の値は無視され、MTOMRequired は 1 に設定されます。
WSDL への影響
MTOMREQUIRED および MTOMRequired は、Web サービスの WSDL には何も影響しません。
MTOM を参照するポリシー文は、WSDL に影響します。ポリシー文を追加する場合、Web クライアントの再生成が必要です。InterSystems IRIS Web クライアントでは、クライアント・クラスを再生成する代わりに、MTOM ポリシー文をクライアントに添付するだけですみます。
要求を MTOM パッケージとして強制する
InterSystems IRIS Web クライアントに対して、すべての要求を MTOM パッケージとして送信するように強制できます。これを実行するには、以下のいずれかの操作を行います。
-
InterSystems IRIS Web クライアント・クラスで MTOMREQUIRED パラメータを 1 に設定します。
-
InterSystems IRIS Web クライアント・インスタンスで MTOMRequired プロパティを 1 に設定します。
-
MTOM パッケージを送信するように、Web クライアントにポリシー文を添付します。そのためには、Web サービス・クライアントを参照する構成クラスを作成およびコンパイルし、このポリシー内で MTOM の使用を有効にします。"Web サービスの保護" を参照してください。
このようなポリシー文を添付すると、MTOMREQUIRED の値は無視され、MTOMRequired は 1 に設定されます。
WSDL への影響
MTOMREQUIRED および MTOMRequired は、この Web クライアントによって使用される Web サービスの WSDL に何らかの変更があるとは想定していません。
MTOM を参照するポリシー文は、WSDL に影響します。つまり、Web サービスが要求した場合のみ、MTOM ポリシー文をクライアントに追加することになります。
MTOM パッケージ化の制御
既定では、InterSystems IRIS が MTOM パッケージを作成する際に以下の規則が使用されます。
-
バイナリ文字列 (%BinaryOpens in a new tab または %xsd.base64BinaryOpens in a new tab) はインラインで出力されます。
-
バイナリ・ストリームは添付を使用して出力されます。
この既定は、MTOM プロパティ・パラメータを使用して変更できます。
-
1 は、このプロパティが添付として出力されることを意味します。
-
0 は、このプロパティがインラインとして出力されることを意味します。
Web サービスまたは Web クライアントが MTOM を使用しない場合、MTOM プロパティ・パラメータは何にも影響しません。
また、このプロパティ・パラメータは Web サービスの WSDL には影響しません。
例
この例では、バイナリ・ファイルを受信して呼び出し元に返送する InterSystems IRIS Web サービスを示します。
対応する Web クライアントは、ハードコードされたファイル名を持つファイルを送信し、Web サービスから同じファイルを受信します。そして、そのファイルを新しい名前で保存して、それが正常に送信されたことを実証します。
Web サービス
Web サービスは、次のとおりです。
/// Receive an attachment and send it back
Class MTOM.RoundTripWS Extends %SOAP.WebService
{
/// Name of the web service.
Parameter SERVICENAME = "RoundTrip";
/// SOAP namespace for the web service
Parameter NAMESPACE = "https://www.roundtrip.org";
/// Receive an attachment and send it back
Method ReceiveFile(attachment As %GlobalBinaryStream) As %GlobalBinaryStream [ WebMethod ]
{
Set ..MTOMRequired=1
Quit attachment
}
}
Web クライアント
生成される Web クライアント (MTOMClient.RoundTripSoap) には、メソッド ReceiveFile() が組み込まれます。これによって同じ名前の Web メソッドが起動されます。このメソッドは、最初は次のようになっています。
Method ReceiveFile(attachment As %xsd.base64Binary) As %xsd.base64Binary
[ Final, SoapBindingStyle = document, SoapBodyUse = literal, WebMethod ]
{
Quit ..WebMethod("ReceiveFile").Invoke($this,"https://www.roundtrip.org/MTOM.RoundTripWS.ReceiveFile",
.attachment)
}
送信するファイルが文字列長の制限を超える可能性があるため、メソッド・シグニチャを次のように調整します。
Method ReceiveFile(attachment As %GlobalBinaryStream) As %GlobalBinaryStream
[ Final, SoapBindingStyle = document, SoapBodyUse = literal, WebMethod ]
{
Quit ..WebMethod("ReceiveFile").Invoke($this,"https://www.roundtrip.org/MTOM.RoundTripWS.ReceiveFile",
.attachment)
}
既定では、Web クライアントで MTOM は不要です。つまり、MTOMREQUIRED パラメータは定義されていません。
このプロキシ・クライアントを使用するには、次のクラスを作成します。
Include %systemInclude
Class MTOMClient.UseClient
{
/// For this example, hardcode what we are sending
ClassMethod SendFile() As %GlobalBinaryStream
{
Set client=##class(MTOMClient.RoundTripSoap).%New()
Set client.MTOMRequired=1
//reset location to port 8080 to enable tracing
Set client.Location="https://devsys:8080/csp/mysamples/MTOM.RoundTripWS.cls"
//create file
Set filename="c:\sample.pdf"
Set file=##class(%Library.FileBinaryStream).%New()
Set file.Filename=filename
//create %GlobalBinaryStream
Set attachment=##class(%GlobalBinaryStream).%New()
Do attachment.CopyFrom(file)
//call the web service
Set answer=client.ReceiveFile(attachment)
//save the received file to prove we made the round trip successfully
Set newfilename="c:\roundtrip"_$h_"sample.pdf"
Set newfile=##class(%Library.FileBinaryStream).%New()
Set newfile.Filename=newfilename
Do newfile.CopyFromAndSave(answer)
Quit answer
}
}