Skip to main content

添付での 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 パッケージを作成する際に以下の規則が使用されます。

この既定は、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
}

}
FeedbackOpens in a new tab