Caché での Web サービスおよび Web クライアントの作成
カスタム・ヘッダ要素の追加と使用
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

この章では、カスタムの SOAP ヘッダ要素の追加方法および使用方法を説明します。

この章は、以下のセクションで構成されます。
フォルト発生時のヘッダ要素の追加の詳細は、このドキュメントの SOAP フォルトの処理 の章を参照してください。
WS-Addressing ヘッダ要素については、後の章で説明します。WS-Security ヘッダ要素については、"Caché Web サービスの保護" を参照してください。
Caché の SOAP ヘッダ要素入門
SOAP メッセージには、ヘッダ (<Header> 要素) を含めることができます。ヘッダは、一連のヘッダ要素で構成されます。以下はその例です。
<SOAP-ENV:Envelope>
   <SOAP-ENV:Header>
      <MyHeaderElement>
         <Subelement1>abc</Subelement1>
         <Subelement2>def</Subelement2>
      </MyHeaderElement>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
...
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
非公式には、各ヘッダ要素は多くの場合 “ヘッダ” と呼ばれます。ただし、これは厳密には正しくありません。なぜなら、メッセージ自体に含まれるヘッダの数は最大でも 1 つであり、このヘッダには常に <Header> と適切なネームスペース接頭語が使用されるためです。ヘッダには、WS-Security ヘッダ要素、WS-Addressing ヘッダ要素、および独自のカスタム・ヘッダ要素を格納することができます。
ヘッダ要素には、SOAP メッセージを受信する Web サービスまたは Web クライアントで使用可能な追加情報が含まれます。ここに示す例では、この情報は XML 要素内に含まれています。上記の例には含まれていませんが、ヘッダ要素には XML 属性を含めることもできます。SOAP 規格では、受信者が SOAP メッセージをどのように処理するかを示す 3 つの標準属性 (mustUnderstandactor、および encodingStyle) が指定されています。
Caché で SOAP ヘッダを表す方法
Caché では、各ヘッダ要素を %SOAP.Header のインスタンス、またはそのサブクラスのいずれかとして表します。%SOAP.Header は XML 対応クラスであり、そのプロパティは標準的なヘッダ要素属性 (mustUnderstandactor、および encodingStyle) に対応します。
Caché には、WS-Addressing および WS-Security で使用するための %SOAP.Header の専門サブクラスが用意されています。カスタム・ヘッダ要素を表すには、%SOAP.Header の独自のサブクラスを作成します。
Caché Web サービスまたはクライアントが SOAP メッセージを受け取ると、そのメッセージをインポートして処理します。この手順では、カスタム・ヘッダ要素の指定されたヘッダがメッセージに含まれる場合、Caché は、そのヘッダ要素をサポート対象のヘッダ要素のリスト (次のサブセクションを参照) と比較します。
次に、サービスまたはクライアントは、以下のように該当する各ヘッダ要素クラスのインスタンスを作成し、それらを配列に挿入して、その配列を自身の HeadersIn プロパティに配置します。
Caché の Web サービスまたは Web クライアントは、それらのヘッダ要素を使用するために HeadersIn プロパティにアクセスすることができます。SOAP メッセージに <Header> 要素が含まれていなかった場合、HeadersIn プロパティの Count() は 0 です。
同様に、Caché の Web サービスまたは Web クライアントが SOAP メッセージを送信する前に、HeadersOut プロパティを更新して、発信メッセージに組み込むカスタム要素が格納されるようにする必要があります。HeadersOut Count() が 0 の場合、発信 SOAP メッセージに <Header> 要素は組み込まれません。
カスタム・ヘッダ要素の場合は、HeadersIn プロパティと HeadersOut プロパティを常に使用します。
その他 (カスタム以外) のヘッダ要素の場合は、以下のように詳細が異なります。
サポート対象のヘッダ要素
Caché の Web サービスおよび Web クライアントでは、WS-Addressing ヘッダおよび WS-Security ヘッダは自動的にサポートされますが、その他のヘッダは自動的にサポートされるわけではありません。
Caché の Web サービスまたは Web クライアントでサポートされるヘッダ要素を指定するには、クラスに XData ブロックを追加して、クラス・パラメータ USECLASSNAMESPACES を指定します。この XData ブロックは、サポート対象の要素をリストします。このクラス・パラメータにより、適用可能なタイプが WSDL に含まれるようになります。サポート対象のヘッダ要素の指定 を参照してください。
ヘッダ要素と WSDL
Web サービスの WSDL は、その Web サービスでサポートされていて、その Web サービスと通信する Web クライアントで許可されているヘッダ要素を通知します。
Caché Web サービスの場合、生成された WSDL には、SOAP ヘッダ要素に関する情報が含まれていないことがあります。
W3C 仕様では、生成された WSDL を Web サービスが提供することを要求していない点に注意してください。
必須のヘッダ要素
特定のヘッダ要素が mustUnderstand=1 と指定する場合、その要素は必須と見なされ、受信者はその要素をサポートする必要があります。受信者は、必須ヘッダ要素をすべて認識しない限り、メッセージを処理することはできません。
SOAP 規格に従って、Caché では、必須でありながらサポート対象ではないヘッダ要素を含む SOAP メッセージが拒否されます。具体的には、Caché の Web サービスまたは Web クライアントは、mustUnderstand=1 と指定されたヘッダ要素を含むメッセージを受信したときに、そのヘッダ要素がサポート対象でない場合には、SOAP フォルトを発行してそのメッセージを無視します。
カスタム・ヘッダ要素の定義
SOAP ウィザードを使用して、特定の WSDL に基づいて Caché の Web サービスまたは Web クライアントを作成すると、必要に応じて任意のヘッダ要素を表すためのクラスが生成されます。
一方、Web サービスまたは Web クライアントを手動で作成する場合には、任意のカスタム・ヘッダ要素を表すためのクラスを手動で定義する必要があります。そのためには、以下の操作を実行します。
  1. カスタム・ヘッダ要素ごとに、%SOAP.Header のサブクラスを作成します。
  2. ヘッダ要素のネームスペースを示す NAMESPACE パラメータを指定します。
  3. ヘッダ要素の名前を示す XMLNAME パラメータを指定します。
  4. このサブクラスで、必要なヘッダ情報を含めるようにプロパティを定義します。既定では、プロパティは、<Header> 要素内の要素に投影されます。
  5. オプションで、このヘッダ要素の形式を制御する XMLFORMAT パラメータを指定します。既定では、ヘッダ要素は常にリテラル形式です (SOAP エンコードではありません)。
以下はその例です。
Class Scenario1.MyHeaderElement Extends %SOAP.Header
{

Parameter NAMESPACE = "http://www.myheaders.org";

Parameter XMLNAME = "MyHeader";

Property Subelement1 As %String;

Property Subelement2 As %String;

}
このヘッダ要素は、SOAP メッセージ内で以下のように表示されます。
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope [parts omitted]>
  <SOAP-ENV:Header>
    <MyHeader xmlns="http://www.myheaders.org"
                     xmlns:hdr="http://www.myheaders.org">
      <Subelement1>abc</Subelement1>
      <Subelement2>def</Subelement2>
    </MyHeader>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
   [omitted]
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
任意のオブジェクト・クラスの XML プロジェクションをカスタマイズする方法の詳細は、"オブジェクトの XML への投影" のドキュメントを参照してください。
SOAP ウィザードの詳細は、SOAP ウィザードの使用法 を参照してください。
SOAP メッセージへのカスタム・ヘッダ要素の追加
Web サービスまたは Web クライアントからカスタム・ヘッダ要素を SOAP メッセージに追加するには、SOAP メッセージを送信する前に次の操作を実行します。
  1. ヘッダ・オブジェクトのインスタンスを作成します。
  2. 必要に応じてヘッダ・オブジェクトのプロパティを設定します。オプションで、actor プロパティと mustUnderstand プロパティも設定します。
  3. 発信ヘッダ配列の HeadersOut プロパティに新しいヘッダを追加します。このプロパティは、通常の配列インタフェース (SetAt() メソッド、Count() メソッド、GetAt() メソッドなど) を使用した配列です。
注意:
ユーティリティ・メソッドでこれらの手順を実行する場合、そのメソッドがインスタンス・メソッドであり、抽象クラスなどではなく、インスタンス化可能なクラスのメンバである必要があります。
また、Web サービスまたは Web クライアントのクラス内に、ヘッダ要素を追加するユーティリティ・メソッドがあるとします。
Method AddMyHeaderElement(mustUnderstand=0)
{
    Set h=##class(MyHeaderElement).%New()
    Set h.Subelement1 = "abc"
    Set h.Subelement2 = "def"
    If mustUnderstand {Set h.mustUnderstand=1}
    Do ..HeadersOut.SetAt(h,"MyHeaderElement")
}
そして、このユーティリティ・メソッドを使用する各 Web メソッドからそのユーティリティ・メソッドを呼び出すことができるとします。以下はその例です。
/// Divide arg1 by arg2 and return the result
Method Divide(arg1 As %Numeric, arg2 As %Numeric) As %Numeric [ WebMethod ]
{
    //main method code here
    //...

    do ..AddMyHeaderElement()

    Quit ans
}
この Web メソッドを呼び出すと、SOAP 応答にヘッダが追加されます。
サポート対象のヘッダ要素の指定
Caché の Web サービスおよび Web クライアントでは、WS-Addressing ヘッダ要素および WS-Security ヘッダ要素は自動的にサポートされますが、その他のヘッダ要素は自動的にサポートされるわけではありません。
Caché の Web サービスまたは Web クライアントでサポートされるヘッダ要素を指定するには、以下の手順を実行します。
XData ブロックでのサポート対象のヘッダ要素の指定
SOAP ウィザードを使用して特定の WSDL に基づいて Caché の Web サービスまたは Web クライアントを作成すると、その SOAP メッセージでサポート対象の任意のヘッダ要素を表すための XData ブロックがそのクラスに生成されます。SOAP ウィザードの詳細は、SOAP ウィザードの使用法 を参照してください。
一方、Web サービスまたはクライアントを手動で作成する場合には、この XData ブロックも手動で指定する必要があります。
以下の簡単な例で説明します。
XData NewXData1
{
<parameters xmlns="http://www.intersystems.com/configuration">
   <request>
      <header name="ServiceHeader" class="NewHeaders.MyCustomHeader"/> 
   </request>
   <response>
      <header name="ExpectedClientHeader" class="NewHeaders.MyCustomHeader"/> 
   </response>
</parameters>
}
詳細
この XData ブロックの要件は、以下のとおりです。
カスタム・ヘッダの継承
この Web サービスのサブクラスを作成する場合は、そのサブクラスが、メソッド固有ではないヘッダ情報を継承します。ヘッダ情報は、<parameters> の直接の子要素である <request> または <response> 要素に含まれています。これは、SOAPMETHODINHERITANCE が 0 の場合も同じです。
別の例を以下に示します。
XData service
{
<parameters xmlns="http://www.intersystems.com/configuration">
  <response>
    <header name="Header2" class="User.Header4" alias="Header4"/>
    <header name="Header3" class="User.Header3"/>
  </response>
  <method name="echoBase64">
    <request>
      <header name="Header2" class="User.Header4" alias="Header4"/>
      <Action>http://soapinterop.org/Round2Base.Service.echoBase64Request</Action>
    </request>
    <response>
      <header name="Header2" class="User.Header2" alias="Header2"/>
      <header name="IposTransportHeader" class="ipos.IposTransportHeader"/>
      <Action>http://soapinterop.org/Round2Base.Service.echoBase64Result</Action>
    </response>
  </method>
  <method name="echoString">
    <request>
      <Action>http://soapinterop.org/Round2Base.Service.echoStringRequest</Action>
    </request>
    <response>
      <Action>http://soapinterop.org/Round2Base.Service.echoStringAnswer</Action>
    </response>
  </method>
</parameters>
}
SOAPHEADERS パラメータでのサポート対象のヘッダ要素の指定
サポート対象のヘッダ要素を指定する従来の方法では、Web サービスまたは Web クライアントのクラスに SOAPHEADERS パラメータを含めます。
このパラメータは、ヘッダ仕様のコンマで区切られたリストと同じである必要があります。各ヘッダ仕様の形式は、以下のとおりです。
headerName:headerPackage.headerClass
headerName はサポート対象のヘッダの要素名で、headerPackage.headerClass は、そのヘッダを表すクラスのパッケージとクラスの完全な名前です。以下はその例です。
Parameter SOAPHEADERS = "MyHeaderElement:Scenario1Client.MyHeaderElement" 
このリストでは、その Web サービスまたは Web クライアントに対する SOAP 要求でサポートされるすべてのヘッダが特定され、それぞれのマッピング先のクラスが表されます。
この従来の手法を使用する場合は、以下の点に注意してください。
カスタム・ヘッダの継承
この Web サービスのサブクラスを作成する場合は、そのサブクラスが SOAPHEADERS パラメータを継承します。これは、SOAPMETHODINHERITANCE が 0 の場合も同じです。
ヘッダ要素の使用法
要求メッセージの受信後に特定の SOAP ヘッダ要素を使用するには、サービスまたはクライアントの HeadersIn プロパティを使用します。
サポート対象のヘッダ要素ごとに、Web サービスまたは Web クライアントは、適切なヘッダ・クラスのインスタンスを作成して、そのヘッダを着信ヘッダ配列である HeadersIn プロパティに追加します。このプロパティは、通常の配列インタフェース (SetAt() メソッド、Count() メソッド、 GetAt() メソッドなど) を使用した配列です。Web サービスまたは Web クライアントは、これらのヘッダを必要に応じて処理できるようになります。
注意:
ヘッダ要素のネームスペースは、リストのヘッダ要素のマッチングには使用されません。ただし、SOAP メッセージのヘッダ要素のネームスペースは、ヘッダ要素サブクラスの NAMESPACE パラメータで指定されたものと同じである必要があります。異なっていると、メッセージのインポート時にエラーが発生します。