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?

カスタム・ヘッダ要素の追加と使用

この章では、カスタムの 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.HeaderOpens in a new tab のインスタンス、またはそのサブクラスのいずれかとして表します。%SOAP.HeaderOpens in a new tab は XML 対応クラスであり、そのプロパティは標準的なヘッダ要素属性 (mustUnderstandactor、および encodingStyle) に対応します。

Caché には、WS-Addressing および WS-Security で使用するための %SOAP.HeaderOpens in a new tab の専門サブクラスが用意されています。カスタム・ヘッダ要素を表すには、%SOAP.HeaderOpens in a new tab の独自のサブクラスを作成します。

Caché Web サービスまたはクライアントが SOAP メッセージを受け取ると、そのメッセージをインポートして処理します。この手順では、カスタム・ヘッダ要素の指定されたヘッダがメッセージに含まれる場合、Caché は、そのヘッダ要素をサポート対象のヘッダ要素のリスト (次のサブセクションを参照) と比較します。

次に、サービスまたはクライアントは、以下のように該当する各ヘッダ要素クラスのインスタンスを作成し、それらを配列に挿入して、その配列を自身の HeadersIn プロパティに配置します。

generated description: headers in

Caché の Web サービスまたは Web クライアントは、それらのヘッダ要素を使用するために HeadersIn プロパティにアクセスすることができます。SOAP メッセージに <Header> 要素が含まれていなかった場合、HeadersIn プロパティの Count() は 0 です。

同様に、Caché の Web サービスまたは Web クライアントが SOAP メッセージを送信する前に、HeadersOut プロパティを更新して、発信メッセージに組み込むカスタム要素が格納されるようにする必要があります。HeadersOut Count() が 0 の場合、発信 SOAP メッセージに <Header> 要素は組み込まれません。

generated description: headers out

カスタム・ヘッダ要素の場合は、HeadersIn プロパティと HeadersOut プロパティを常に使用します。

その他 (カスタム以外) のヘッダ要素の場合は、以下のように詳細が異なります。

  • WS-Addressing には、HeadersIn プロパティと HeadersOut プロパティではなく、AddressingIn プロパティと AddressingOut プロパティを使用します。このドキュメントで後述の “WS-Addressing ヘッダ要素の追加と使用” の章を参照してください。

  • WS-Security ヘッダ要素には、WS-Policy 機能を使用してください ("Caché Web サービスの保護" を参照)。

    または、SecurityIn プロパティと SecurityOut プロパティを直接使用します (同じドキュメントを参照)。一般に、こちらのほうが作業が多くなります。

    (WS-Security ヘッダ要素は HeadersIn プロパティと HeadersOut プロパティにも格納されていますが、これらのプロパティを通じて、それらの要素にアクセスしたり、それらの要素を設定したりすることはお勧めできません)。

  • Caché SOAP セッションのサポートでは、HeadersIn プロパティと HeadersOut プロパティが使用されます。このドキュメントで後述の “SOAP セッション管理” の章を参照してください。

サポート対象のヘッダ要素

Caché の Web サービスおよび Web クライアントでは、WS-Addressing ヘッダおよび WS-Security ヘッダは自動的にサポートされますが、その他のヘッダは自動的にサポートされるわけではありません。

Caché の Web サービスまたは Web クライアントでサポートされるヘッダ要素を指定するには、クラスに XData ブロックを追加して、クラス・パラメータ USECLASSNAMESPACES を指定します。この XData ブロックは、サポート対象の要素をリストします。このクラス・パラメータにより、適用可能なタイプが WSDL に含まれるようになります。“サポート対象のヘッダ要素の指定” を参照してください。

ヘッダ要素と WSDL

Web サービスの WSDL は、その Web サービスでサポートされていて、その Web サービスと通信する Web クライアントで許可されているヘッダ要素を通知します。

Caché Web サービスの場合、生成された WSDL には、SOAP ヘッダ要素に関する情報が含まれていないことがあります。

  • HeadersOut プロパティを設定して、手動で SOAP ヘッダを追加する場合は、この章の “サポート対象のヘッダ要素の指定” で後述するように、それらのヘッダを XData ブロック内で宣言してください。また、Web サービス・クラスのクラス・パラメータ USECLASSNAMESPACES を 1 に指定してください。

    これらの手順を実行すると、すべての該当情報が WSDL に含まれるようになります。それ以外の場合は、これが行われなくなるため、WSDL をファイルに保存して、そのファイルを必要に応じて手動で編集することが必要になります。

  • SecurityOut プロパティ ("Caché Web サービスの保護" を参照) を設定して、WS-Security ヘッダを追加した場合、WSDL には必要な情報の一部が含まれなくなります。(これは、コンパイル時に WSDL が生成され、その後の実行時にヘッダが追加されるためです。)この場合は、WSDL をファイルに保存して、そのファイルを必要に応じて手動で編集してください。

    多くの理由から、WS-Policy を使用することで、WS-Security 要素の追加が単純で簡単になります (同じドキュメントを参照)。WS-Policy を使用すると、生成された WSDL には必要な情報がすべて含まれます。

  • その他の場合は、生成された WSDL にすべての情報が含まれます。

W3C 仕様では、生成された WSDL を Web サービスが提供することを要求していない点に注意してください。

必須のヘッダ要素

特定のヘッダ要素が mustUnderstand=1 と指定する場合、その要素は必須と見なされ、受信者はその要素をサポートする必要があります。受信者は、必須ヘッダ要素をすべて認識しない限り、メッセージを処理することはできません。

SOAP 規格に従って、Caché では、必須でありながらサポート対象ではないヘッダ要素を含む SOAP メッセージが拒否されます。具体的には、Caché の Web サービスまたは Web クライアントは、mustUnderstand=1 と指定されたヘッダ要素を含むメッセージを受信したときに、そのヘッダ要素がサポート対象でない場合には、SOAP フォルトを発行してそのメッセージを無視します。

カスタム・ヘッダ要素の定義

SOAP ウィザードを使用して特定の WSDL に基づいて Caché の Web サービスまたは Web クライアントを作成すると、必要に応じて任意のヘッダ要素を表すためのクラスが生成されます。

一方、Web サービスまたは Web クライアントを手動で作成する場合には、任意のカスタム・ヘッダ要素を表すためのクラスを手動で定義する必要があります。そのためには、以下の操作を実行します。

  1. カスタム・ヘッダ要素ごとに、%SOAP.HeaderOpens in a new tab のサブクラスを作成します。

  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() メソッドなど) を使用した配列です。

Note:

ユーティリティ・メソッドでこれらの手順を実行する場合、そのメソッドがインスタンス・メソッドであり、抽象クラスなどではなく、インスタンス化可能なクラスのメンバである必要があります。

また、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 クライアントでサポートされるヘッダ要素を指定するには、以下の手順を実行します。

  • それらのヘッダ要素を表すクラスを定義します。その手順は、“カスタム・ヘッダ要素の定義” を参照してください。

  • ヘッダ要素クラスを、Web サービスまたは Web クライアントのヘッダ要素に関連付けます。

    これは、以下の 2 つの方法のいずれかで行うことができます。

    • Web サービスまたは Web クライアントのクラスに XData ブロックを追加します。この XData ブロックで、特定のヘッダ要素とそれらに対応するヘッダ要素クラス間の関連付けを指定します。

      さらに、そのサービスまたはクライアントのクラスでクラス・パラメータ USECLASSNAMESPACES を 1 (推奨値) に設定する場合、生成された WSDL で、このヘッダ情報が使用されます。

    • Web サービスまたは Web クライアントのクラスで、SOAPHEADERS パラメータを指定します。このパラメータで、特定のヘッダ要素とそれらに対応するヘッダ要素クラス間の関連付けを指定します。

      Note:

      この手法は柔軟性があまりなく、生成された WSDL には影響しないため、現在は非推奨となっています。

    以降のセクションで詳細を説明します。

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 ブロックの要件は、以下のとおりです。

  • XData ブロックには、どのような名前でも指定できます。その名前 (この例では NewXData1) は使用されません。

    SOAP ウィザードでは、このブロックの作成時に parameters という名前が使用されます。

  • 最上位の要素は、<parameters> であることが必要です。

  • <parameters> 要素とそのすべての子要素 (とさらにそれらの子) は、"http://www.intersystems.com/configuration" ネームスペース内に存在している必要があります。

  • <parameters> 要素には、以下の子要素を含めることができます。

    • <request> — すべての要求メッセージに関連付けられるヘッダ要素を決定します。すべての要求メッセージに共通するヘッダ要素の場合に使用します。

      この要素には、該当するヘッダ要素ごとに子要素 <header> が必要です。

    • <response> — すべての応答メッセージに関連付けられるヘッダ要素を決定します。すべての応答メッセージに共通するヘッダ要素の場合に使用します。

      この要素には、該当するヘッダ要素ごとに子要素 <header> が必要です。

    • <methodname>methodname という名前の Web メソッドに関連付けられるヘッダ要素を決定します。

      この要素には、以下の子要素を含めることができます。

      • <header> — この Web メソッドの要求メッセージと応答メッセージに関連付けられるヘッダ要素を決定します。両方の場合に共通するヘッダ要素の場合に使用します。

      • <request> — この Web メソッドの要求メッセージに関連付けられるヘッダ要素を決定します。

        この要素には、該当するヘッダ要素ごとに子要素 <header> が必要です。

      • <response> — この Web メソッドの応答メッセージに関連付けられるヘッダ要素を決定します。

        この要素には、該当するヘッダ要素ごとに子要素 <header> が必要です。

  • この XData ブロックでは、各 <header> 要素は、ヘッダ要素を表すために使用される Caché クラスにヘッダ要素を関連付けます。この要素には以下の属性が含まれます。

    属性 目的
    name ヘッダ要素の名前。
    class そのヘッダ要素を表す Caché クラス。
    alias (オプション) Web サービスまたは Web クライアントの HeadersIn 配列内のそのヘッダ要素のキー。既定値は、name 属性に指定された値です。

    XData ブロック内での <header> 要素の位置によって、適用先のメッセージが示されます。

カスタム・ヘッダの継承

この 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 サービスの場合、この手法は、生成された WSDL に影響しません。

  • 特定の Web メソッドに異なるヘッダ要素を指定することはできません。

  • SOAP ウィザードでは、生成された Web サービスおよび Web クライアントのクラスに SOAPHEADERS パラメータが生成されなくなりました。

  • この手法は非推奨となっています。

カスタム・ヘッダの継承

この Web サービスのサブクラスを作成する場合は、そのサブクラスが SOAPHEADERS パラメータを継承します。これは、SOAPMETHODINHERITANCE が 0 の場合も同じです。

ヘッダ要素の使用法

要求メッセージの受信後に特定の SOAP ヘッダ要素を使用するには、サービスまたはクライアントの HeadersIn プロパティを使用します。

サポート対象のヘッダ要素ごとに、Web サービスまたは Web クライアントは、適切なヘッダ・クラスのインスタンスを作成して、そのヘッダを着信ヘッダ配列である HeadersIn プロパティに追加します。このプロパティは、通常の配列インタフェース (SetAt() メソッド、Count() メソッド、 GetAt() メソッドなど) を使用した配列です。Web サービスまたは Web クライアントは、これらのヘッダを必要に応じて処理できるようになります。

Note:

ヘッダ要素のネームスペースは、リストのヘッダ要素のマッチングには使用されません。ただし、SOAP メッセージのヘッダ要素のネームスペースは、ヘッダ要素サブクラスの NAMESPACE パラメータで指定されたものと同じである必要があります。異なっていると、メッセージのインポート時にエラーが発生します。

FeedbackOpens in a new tab