Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

添付での MTOM の使用法

SOAP 要求と応答のメッセージに添付を追加できます。この実行方法としては、MTOM (Message Transmission Optimization Mechanism) に対する Caché サポートの使用が推奨されます。

この章では以下の詳細を示します。

ポリシー内で MTOM の使用について指定することもできます。Caché Web サービスの保護を参照してください。

また、パッケージ化の後 gzip を使用してメッセージを圧縮するように、Caché Web サービスおよび Web クライアントを構成することもできます。“Caché Web サービスの調整” および “Caché Web クライアントの調整” の章を参照してください。

添付および SOAP メッセージのパッケージ化

一般に添付は、バイナリ・データの伝送に使用されます。Caché の SOAP サポートでは、SOAP メッセージをパッケージ化する方法が 3 種類用意されています。詳細を説明する前に、このパッケージ化方法を確認しておきます。

  • すべてのパーツをインラインにしてメッセージをパッケージ化します (添付なし)。バイナリ・データのすべてに Base 64 のエンコードを使用します。

    Web サービスが MTOM 要求を受信する場合 (サービスが MTOM 応答で返信する) を除き、これは Caché Web サービスおよび Web クライアントの既定の動作です。

  • MTOM (Message Transmission Optimization Mechanism) 仕様に従ってメッセージをパッケージ化します。この場合、すべてをインライン化するメッセージと比較して若干コンパクトになります。現在、SOAP メッセージについてはこちらの方法が推奨されます。

    この方法を採用した場合、状況に応じて SOAP メッセージが自動的にパッケージ化されます。つまり、MIME パーツが必要に応じて作成され、ユーザの操作を必要とせずにメッセージに追加されます。

    また、Caché で MTOM パッケージを作成する際の既定として、添付を使用してバイナリ・ストリームが出力され、バイナリ文字列 (%BinaryOpens in a new tab または %xsd.base64BinaryOpens in a new tab) がインラインで出力されます。この動作は制御が可能です。

    MTOM の仕様へのリンクについては、このドキュメントの最初の章の “Caché でサポートされる規格” を参照してください。

  • 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/gsop/;
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='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
xmlns:s='http://www.w3.org/2001/XMLSchema'>
<SOAP-ENV:Body>
  <DownloadResponse xmlns="http://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/gsop/;
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='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
xmlns:s='http://www.w3.org/2001/XMLSchema'>
<SOAP-ENV:Body>
<DownloadResponse xmlns="http://www.filetransfer.org">
<DownloadResult>
   <Filename>sample.pdf</Filename>
   <IsBinary>true</IsBinary>
   <BinaryContents>
      <xop:Include href="cid:1.B1150656.EC8A.4B5A.8835.A932E318190B" 
              xmlns:xop="http://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/gsop/;
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='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
xmlns:s='http://www.w3.org/2001/XMLSchema'>
  <SOAP-ENV:Body><DownloadBinaryResponse xmlns="http://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 パートの参照が存在しません。

Caché Web サービスおよび Web クライアントの既定の動作

既定では、Caché Web サービスは次のように動作します。

  • MTOM パッケージで要求を受け取ると、Web サービスはその応答を MTOM パッケージとして送信します。

    また、Web サービス・インスタンスの IsMTOM プロパティは、1 に設定されます。

  • MTOM パッケージ以外の要求を受け取ると、Web サービスはその応答を MTOM パッケージ以外で送信します。

既定では、Caché Web クライアントは次のように動作します。

  • 要求を MTOM パッケージとして送信しません。

  • 応答が MTOM パッケージであるかどうかに関わらず、応答を処理します。

    応答が MTOM パッケージである場合、Web クライアント・インスタンスの IsMTOM プロパティは、1 に設定されます。応答が MTOM パッケージでない場合は、IsMTOM プロパティは変更されません。

応答を MTOM パッケージとして強制する

Caché Web サービスに対して、すべての応答を MTOM パッケージとして送信するように強制できます。これを実行するには、次のいずれかの操作を行います。

  • Caché Web サービス・クラスで MTOMREQUIRED パラメータを 1 に設定します。

  • Caché Web サービス・インスタンスで MTOMRequired プロパティを 1 に設定します。これは、Web メソッドまたは OnPreWebMethod() コールバック内で実行できます。このコールバックの概要は、このドキュメントで後述の “Web サービスのコールバックのカスタマイズ” を参照してください。

  • MTOM パッケージを送信するように、Web サービスのポリシー文を添付します。そのためには、Web サービス・クラスを参照する構成クラスを作成およびコンパイルし、このポリシー内で MTOM の使用を有効にします。"Caché Web サービスの保護" を参照してください。

    このようなポリシー文を添付すると、MTOMREQUIRED の値は無視され、MTOMRequired は 1 に設定されます。

WSDL への影響

MTOMREQUIRED および MTOMRequired は、Web サービスの WSDL には何も影響しません。

MTOM を参照するポリシー文は、WSDL に影響します。ポリシー文を追加する場合、Web クライアントの再生成が必要です。Caché Web クライアントでは、クライアント・クラスを再生成する代わりに、MTOM ポリシー文をクライアントに添付するだけで済みます。

要求を MTOM パッケージとして強制する

Caché Web クライアントに対して、すべての要求を MTOM パッケージとして送信するように強制できます。これを実行するには、以下のいずれかの操作を行います。

  • Caché Web クライアント・クラスで MTOMREQUIRED パラメータを 1 に設定します。

  • Caché Web クライアント・インスタンスで MTOMRequired プロパティを 1 に設定します。

  • MTOM パッケージを送信するように、Web クライアントにポリシー文を添付します。そのためには、Web サービス・クライアントを参照する構成クラスを作成およびコンパイルし、このポリシー内で MTOM の使用を有効にします。"Caché Web サービスの保護" を参照してください。

    このようなポリシー文を添付すると、MTOMREQUIRED の値は無視され、MTOMRequired は 1 に設定されます。

WSDL への影響

MTOMREQUIRED および MTOMRequired は、この Web クライアントによって使用される Web サービスの WSDL に何らかの変更があるとは想定していません。

MTOM を参照するポリシー文は、WSDL に影響します。つまり、Web サービスが要求した場合のみ、MTOM ポリシー文をクライアントに追加することになります。

MTOM パッケージ化の制御

既定では、Caché が MTOM パッケージを作成する際に以下の規則が使用されます。

この既定は、MTOM プロパティ・パラメータを使用して変更できます。

  • 1 は、このプロパティが添付として出力されることを意味します。

  • 0 は、このプロパティがインラインとして出力されることを意味します。

Web サービスまたは Web クライアントが MTOM を使用しない場合、MTOM プロパティ・パラメータは何にも影響しません。

また、このプロパティ・パラメータは Web サービスの WSDL には影響しません。

この例では、バイナリ・ファイルを取得して呼び出し元に返送する Caché 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 = "http://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,"http://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,"http://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="http://localhost:8080/csp/gsop/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