Caché での Web サービスおよび Web クライアントの作成
生成された WSDL の詳細
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

この付録では、参考として、Caché Web サービスのサンプル WSDL ドキュメントから一部をいくつか取り上げ、キーワードとパラメータがそれらの部分に及ぼす影響に関する情報を示します。以下のトピックについて説明します。

Web メソッドのシグニチャも WSDL に影響しますが、この付録ではその詳細には触れません。
WSDL は、Web サービスで使用するあらゆる XML 対応クラスの XML プロジェクションの影響も受けます。"オブジェクトの XML への投影" のドキュメントを参照してください。
注意:
Web サービスにコンパイル済みのポリシー構成クラスがある場合、<binding> セクションには、<wsp:Policy> 形式の要素も含まれます。このドキュメントでは、ポリシーがどのように WSDL に影響するかについては触れません。それは WS-SecurityPolicy などの仕様によって決まるからです。
ポリシー構成については、"Caché Web サービスの保護" を参照してください。
Caché は利便性を向上するために WSDL ドキュメントを生成しますが、これは W3C 仕様では要求されていません。これに関する重要な注意事項は、このドキュメントで前述した WSDL の表示 を参照してください。
WSDL ドキュメントの概要
Web サービスには、マシンが読み取ることができる形式で記述されているインタフェース定義である WSDL ドキュメント があります。WSDL ドキュメントは、Web サービス記述言語の規格に従って XML で記述されます。これにより、Web サービスとそのクライアントの対話方法に関するコントラクトが定義されます。
WSDL には、以下を定義する追加要素を記述したルート <definitions> 要素があります。
サービス、スキーマ、およびメッセージはすべて XML ネームスペースに関連付けられます。これらをすべて 1 つのネームスペースに置くことも、複数のネームスペースに置くこともできます。SOAP に対する Caché サポートでは、想定可能なすべての機能がサポートされるわけではありません。このドキュメントで前述の Caché でサポートされる規格 を参照してください。
サンプルの Web サービス
この付録では、次のサンプル Web サービスの WSDL を抜粋して示します。
Class WSDLSamples.BasicWS Extends %SOAP.WebService
{

Parameter SERVICENAME = "MyServiceName";

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

Parameter USECLASSNAMESPACES = 1;

///  adds two complex numbers
Method Add(a As ComplexNumber, b As ComplexNumber) As ComplexNumber [ WebMethod ]
{
    Set sum = ##class(ComplexNumber).%New()
    Set sum.Real = a.Real + b.Real
    Set sum.Imaginary = a.Imaginary + b.Imaginary

    Quit sum
}
}
この Web サービスは次のクラスに基づいています。
///  A complex number
Class WSDLSamples.ComplexNumber Extends (%RegisteredObject, %XML.Adaptor)
{

/// real part of the complex number
Property Real As %Float;

/// imaginary part of the complex number
Property Imaginary As %Float;

}
特に明記のない限り、この付録では、この Web サービスの WSDL を抜粋して取り上げています (この Web サービスのバリエーションを使用している場合もあります)。
ネームスペース宣言
WSDL の残りの部分を詳細に検証する前に、残りの部分によって使用されるネームスペース宣言を確認すると役に立ちます。<definitions> 要素には、WSDL で使用するネームスペースごとにネームスペース宣言が 1 つ記述されています。この付録の最初に示したサンプルの Web サービスの場合、ネームスペース宣言は次のようになります。
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
xmlns:s="http://www.w3.org/2001/XMLSchema" 
xmlns:s0="http://www.mynamespace.org" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
targetNamespace="http://www.mynamespace.org">
以下のパラメータはネームスペース宣言に影響します。
また、その他のネームスペース (http://schemas.xmlsoap.org/wsdl/soap/ など) が、必要に応じて自動的に追加されます。
ネームスペースの接頭語は自動的に選択され、カスタマイズはできません。
<service>
WSDL を検証する際、最後から開始して最初まで確認していくことは有用です。
WSDL 内の最後の要素は <service> 要素であり、これは Web サービスを定義するものです。この付録の最初に示したサンプルの Web サービスの場合、この要素は次のようになります。
<service name="MyServiceName">
    <port name="MyServiceNameSoap" binding="s0:MyServiceNameSoap">
        <soap:address location="http://localhost:57772/csp/gsop/WSDLSamples.BasicWS.cls"/>
    </port>
</service>
この要素は、次のように指定されます。
<binding>
WSDL では、<service> 要素の前に、<binding> 要素が含まれます。これらはそれぞれ、特定の <portType> 要素によって定義された処理とメッセージの、メッセージ形式とプロトコルの詳細を定義します。
一般に、WSDL には複数の <binding> 要素を含めることができますが、Caché Web サービスの WSDL で含めることができるのは 1 つだけです。
この付録の最初に示したサンプルの Web サービスの場合、この要素は次のようになります。
<binding name="MyServiceNameSoap" type="s0:MyServiceNameSoap">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" 
                  style="document"/>
    <operation name="Add">
        <soap:operation soapAction="http://www.mynamespace.org/WSDLSamples.BasicWS.Add" 
                        style="document"/>
        <input>
            <soap:body use="literal"/>
        </input>
        <output>
            <soap:body use="literal"/>
        </output>
    </operation>
</binding>
この要素は、次のように指定されます。
注意:
Web サービスにコンパイル済みのポリシー構成クラスがある場合、<binding> セクションには、<wsp:Policy> 形式の要素も含まれます。このドキュメントでは、ポリシーがどのように WSDL に影響するかについては触れません。それは WS-SecurityPolicy などの仕様によって決まるからです。
ポリシー構成については、"Caché Web サービスの保護" を参照してください。
<portType>
WSDL では、<binding> セクションの前に、<portType> 要素が含まれます。これらの要素はそれぞれ、<binding> 要素に対して単一のアドレスを指定することで個々のエンドポイントを定義します。<portType> 要素は、抽象操作の名前付きセットおよび関連する抽象メッセージです。
一般に、WSDL には複数の <portType> 要素を含めることができますが、Caché Web サービスの WSDL で含めることができるのは 1 つだけです。
この付録の最初に示したサンプルの Web サービスの場合、<portType> 要素は次のようになります。
<portType name="MyServiceNameSoap">
    <operation name="Add">
        <input message="s0:AddSoapIn"/>
        <output message="s0:AddSoapOut"/>
    </operation>
</portType>
この要素のすべての特性は、WSDL の他の部分でも自動的に一貫性が保たれます。独立した制御は必要ありません。
<message>
<portType> 要素の前の <message> 要素は、処理で使用されるメッセージを定義します。WSDL は通常、Web メソッドごとに 2 つの <message> 要素を含んでいます。この付録の最初に示したサンプルの Web サービスの場合、これらの要素は次のようになります。
<message name="AddSoapIn">
    <part name="parameters" element="s0:Add"/>
</message>
<message name="AddSoapOut">
    <part name="parameters" element="s0:AddResponse"/>
</message>
この要素は、次のように指定されます。
<types>
WSDL では、<message> 要素の前に、<types> 要素が含まれます。これは、メッセージが使用するスキーマを定義します。<types> 要素には、Web サービスおよびそのクライアントで使用する要素、タイプ、またはその両方を定義する <schema> 要素が 1 つ以上記述されています。この付録の最初に示したサンプルの Web サービスの場合、この要素は次のようになります。
<types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.mynamespace.org">
        <s:element name="Add">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="0" name="a" type="s0:ComplexNumber"/>
                    <s:element minOccurs="0" name="b" type="s0:ComplexNumber"/>
                </s:sequence>
            </s:complexType>
        </s:element>
        <s:complexType name="ComplexNumber">
            <s:sequence>
                <s:element minOccurs="0" name="Real" type="s:double"/>
                <s:element minOccurs="0" name="Imaginary" type="s:double"/>
            </s:sequence>
        </s:complexType>
        <s:element name="AddResponse">
            <s:complexType>
                <s:sequence>
                    <s:element name="AddResult" type="s0:ComplexNumber"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
</types>
以降のサブセクションでは、主なバリエーションについて説明します。
注意:
<types> セクションも、Web サービスで使用するあらゆる XML 対応クラスに定義した XML プロジェクションの影響を受けます。XML プロジェクションによって、ネームスペースの使用、NULL 処理、特殊文字の処理などの課題が決まります。"オブジェクトの XML への投影" のドキュメントを参照してください。
SoapBindingStyle キーワードおよび SoapBodyUse キーワードは、WSDL の他のパートに影響し、それらのパートは <types> セクションの構造を決定します。
name 属性
<schema> 要素は、メッセージ・スタイルに応じて、要素、タイプ、またはその両方で構成できます。要素またはタイプはそれぞれ、次のように指定する name 属性を持ちます。
例えば、サンプルの Web メソッドを次のように編集したとします。
Method Add(a As ComplexNumber, b As ComplexNumber) 
As ComplexNumber [ WebMethod, SoapMessageName = MyResponseMessage]
{
    Set sum = ##class(ComplexNumber).%New()
    Set sum.Real = a.Real + b.Real
    Set sum.Imaginary = a.Imaginary + b.Imaginary

    Quit sum
}
この場合、<types> セクションは次のようになります。
<types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.mynamespace.org">
        <s:element name="Add">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="0" name="a" type="s0:ComplexNumber"/>
                    <s:element minOccurs="0" name="b" type="s0:ComplexNumber"/>
                </s:sequence>
            </s:complexType>
        </s:element>
        <s:complexType name="ComplexNumber">
            <s:sequence>
                <s:element minOccurs="0" name="Real" type="s:double"/>
                <s:element minOccurs="0" name="Imaginary" type="s:double"/>
            </s:sequence>
        </s:complexType>
        <s:element name="MyResponseMessage">
            <s:complexType>
                <s:sequence>
                    <s:element name="AddResult" type="s0:ComplexNumber"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
</types>
詳細は、SOAP 応答のメッセージ名の制御 を参照してください。また、"オブジェクトの XML への投影" のドキュメントも参照してください。
<types> のネームスペース
Web サービスの次のパラメータは、<types> セクションでのネームスペースの使用に影響します。
各 XML 対応クラスの NAMESPACE パラメータも、WSDL の <types> 要素に影響します。
前出の Web サービスの次のバリエーションを取り上げます。
Class WSDLSamples.Namespaces Extends %SOAP.WebService
{

Parameter SERVICENAME = "MyServiceName";

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

Parameter RESPONSENAMESPACE = "http://www.myresponsenamespace.org";

Parameter TYPENAMESPACE = "http://www.mytypes.org";

Parameter RESPONSETYPENAMESPACE = "http://www.myresponsetypes.org";

Parameter USECLASSNAMESPACES = 1;

///  adds two complex numbers
Method Add(a As ComplexNumberNS, b As ComplexNumberNS) As ComplexNumberNS [ WebMethod ]
{
    Set sum = ##class(ComplexNumberNS).%New()
    Set sum.Real = a.Real + b.Real
    Set sum.Imaginary = a.Imaginary + b.Imaginary

    Quit sum
}

}
クラス WSDLSamples.ComplexNumberNS は次のようになります。
///  A complex number
Class WSDLSamples.ComplexNumberNS Extends (%RegisteredObject, %XML.Adaptor)
{

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

Property Real As %Float;

Property Imaginary As %Float;

}
この Web サービスの WSDL では、<types> パートは次のようになります。
<types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.mytypes.org">
        <s:import namespace="http://www.complexnumbers.org"/>
        <s:element name="Add">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="0" name="a" type="ns2:ComplexNumberNS"/>
                    <s:element minOccurs="0" name="b" type="ns2:ComplexNumberNS"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.complexnumbers.org">
        <s:complexType name="ComplexNumberNS">
            <s:sequence>
                <s:element minOccurs="0" name="Real" type="s:double"/>
                <s:element minOccurs="0" name="Imaginary" type="s:double"/>
            </s:sequence>
        </s:complexType>
    </s:schema>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.myresponsetypes.org">
        <s:import namespace="http://www.complexnumbers.org"/>
        <s:element name="AddResponse">
            <s:complexType>
                <s:sequence>
                    <s:element name="AddResult" type="ns2:ComplexNumberNS"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
</types>
使用可能なその他のバリエーション
以下に示すその他のパラメータも <types> 要素に影響します。
メソッド・シグニチャのバリエーションによる WSDL のバリエーション
ここでは、メソッド・シグニチャのバリエーションによって生じる WSDL のバリエーションをいくつか示します。
参照による返り値または出力パラメータとしての返り値
参照によって値を返す場合、または出力パラメータとして値を返す場合には、Web メソッドのシグニチャ内で ByRef キーワードまたは Output キーワードを必要に応じて使用します。この変更は、スキーマと SOAP 応答メッセージに影響を及ぼします。
例えば、2 つの異なる Web サービスのメソッドから、次のような Web メソッド・シグニチャがあるとします。
//from web service 1
Method HelloWorld() As %String [ WebMethod ]

//from web service 2
Method HelloWorld(ByRef myarg As %String) [ WebMethod ]
最初の Web サービスでは、<types> セクションは次のようになります。
<types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.helloworld.org">
        <s:element name="HelloWorld1">
            <s:complexType>
                <s:sequence/>
            </s:complexType>
        </s:element>
        <s:element name="HelloWorld1Response">
            <s:complexType>
                <s:sequence>
                    <s:element name="HelloWorld1Result" type="s:string"/>
                </s:sequence>
            </s:complexType>
        </s:element>
    </s:schema>
</types>
参照によって値を返す 2 つ目の Web サービスでは、<types> セクションに、応答メッセージに対応するタイプのバリエーションがあります。
<types>
...
        <s:element name="HelloWorld2Response">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="0" name="myarg" type="s:string"/>
...
これは、<HelloWorld2Response> メッセージに含まれる要素が <myarg> であることを示しています。この要素は、メッセージ・シグニチャの引数の名前に対応します。一方、この要素は通常 <methodnameResult> です。
Output キーワードの代わりに ByRef キーワードを使用しても、WSDL に同じ影響が及ぼされます。
これらのキーワードの詳細は、"Caché オブジェクトの使用法" の メソッド の章を参照してください。
Caché Web サービスの WSDL のその他のバリエーション
このセクションでは、Caché Web サービスに使用できる、WSDL のその他のバリエーションについて説明します。
Caché SOAP セッションの WSDL の相違点
Web サービスで SOAPSESSION パラメータに 1 を指定すると、WSDL に次のように影響します。
Caché バイナリ SOAP 形式の WSDL の相違点
SOAPBINARY パラメータに 1 を指定した Caché Web サービスでは、WSDL の機能が次のように拡張されます。
これらの WSDL の拡張機能は、XML スキーマ、WSDL、および WS-I Basic Profile の各仕様の下で有効であり、これらの仕様に準拠したすべての Web クライアント・ツールキットでは無視されることが想定されています。
注意:
Caché の Web サービスまたは Web クライアントが Caché のバイナリ SOAP 形式を使用する場合、その Web サービスまたは Web クライアントで WS-Security 機能または WS-Policy 機能を使用することはできません。"Caché Web サービスの保護" を参照してください。
単方向 Web メソッドの WSDL の相違点
メソッドの返りタイプを %SOAP.OneWay として定義している場合、WSDL は既定のものと以下の点が異なります。