| Oracle® XML DB開発者ガイド 11gリリース2 (11.2) B70200-03 |
|
 前 |
 次 |
この章の内容は次のとおりです。
Webサービスは、アプリケーションがインターネットを介して情報をやりとりし、ビジネス・ロジックを実装するサービスにアクセスするための標準的な方法です。Webサービスを使用すると、使用中のアプリケーションからネイティブなOracle XML DBにアクセスできます。あるサービスでは、SQL問合せやXQuery問合せを発行し、その結果をXMLデータとして取得できます。また、別のサービスでは、PL/SQLのあらゆるストアド・ファンクションおよびストアド・プロシージャにアクセスできます。
このサービスを使用する場合は、入力ドキュメントおよび出力ドキュメントのフォーマットをカスタマイズできます。その場合、WSDLはネイティブなデータベースWebサービス・エンジンにより自動的に生成されます。
Oracle XML DBでサポートされているSOAPのバージョンは1.1です。アプリケーションはHTTPメソッドPOSTを使用して、SOAPリクエストをネイティブなOracle XML DBのWebサービスに送信します。ネイティブなOracle XML DB構成ファイルxdbconfig.xmlを使用すると、Oracle XML DBのすべてのWebサービスおよびWSDLドキュメントの格納場所を構成できます。またこの構成ファイルでは、Webサービスに関するセキュリティ設定も構成できます。
入力HTTPヘッダーのAccept-Charsetsフィールドでは、Webサービスの応答に使用するキャラクタ・セットを指定できます。このヘッダー・フィールドを省略すると、応答にはデータベースのキャラクタ・セットが使用されます。入力ドキュメントおよびエラー応答には、データベースのロケール言語が使用されます。
ネイティブなOracle XML DBのWebサービスのエラー処理では、フォルトのSOAPフレームワークを使用します。
|
関連項目:
|
セキュリティ上の理由により、Oracle XML DBに事前に組み込まれているネイティブなWebサービスはありません。ネイティブなOracle XML Webサービスを使用できるようにするには、Oracle XML DB HTTPサーバーを起動し、Webサービス構成を明示的に追加する必要があります。その後、Webサービスの使用を特定のユーザーにのみ許可するため、それらのユーザーに適切なロールを付与する必要があります。
Webサービスを構成します。「Oracle XML DBでのWebサービスの構成」を参照してください。
特定のユーザーに適切なロールを付与して、Webサービスを有効化します。「特定のユーザーに対するWebサービスの有効化」を参照してください。
Oracle XML DBでWebサービスを使用できるようにするには、ユーザーSYSとしてログオンし、例33-2の問合せ出力として示されているサーブレット構成をOracle XML DBの構成ファイルxdbconfig.xmlに追加します。
例33-1に、PL/SQLパッケージDBMS_XDBのプロシージャを使用してサーブレットを追加する方法を示しています。例33-2は、サーブレットが正しく追加されたことを確認する方法を示しています。
例33-1 Webサービス構成サーブレットの追加
DECLARE
SERVLET_NAME VARCHAR2(32) := 'orawsv';
BEGIN
DBMS_XDB.deleteServletMapping(SERVLET_NAME);
DBMS_XDB.deleteServlet(SERVLET_NAME);
DBMS_XDB.addServlet(NAME => SERVLET_NAME,
LANGUAGE => 'C',
DISPNAME => 'Oracle Query Web Service',
DESCRIPT => 'Servlet for issuing queries as a Web Service',
SCHEMA => 'XDB');
DBMS_XDB.addServletSecRole(SERVNAME => SERVLET_NAME,
ROLENAME => 'XDB_WEBSERVICES',
ROLELINK => 'XDB_WEBSERVICES');
DBMS_XDB.addServletMapping(PATTERN => '/orawsv/*',
NAME => SERVLET_NAME);
END;
/
例33-2 Webサービス構成サーブレット追加の検証
XQUERY declare default element namespace "http://xmlns.oracle.com/xdb/xdbconfig.xsd"; (: :)
(: This path is split over two lines for documentation purposes only.
The path should actually be a single long line. :)
for $doc in fn:doc("/xdbconfig.xml")/xdbconfig/sysconfig/protocolconfig/httpconfig/
webappconfig/servletconfig/servlet-list/servlet[servlet-name='orawsv']
return $doc
/
Result Sequence
-------------------------------------------------------------------------
<servlet xmlns="http://xmlns.oracle.com/xdb/xdbconfig.xsd">
<servlet-name>orawsv</servlet-name>
<servlet-language>C</servlet-language>
<display-name>Oracle Query Web Service</display-name>
<description>Servlet for issuing queries as a Web Service</description>
<servlet-schema>XDB</servlet-schema>
<security-role-ref>
<description/>
<role-name>XDB_WEBSERVICES</role-name>
<role-link>XDB_WEBSERVICES</role-link>
</security-role-ref>
</servlet>
1 item(s) selected.
特定のユーザーに対してWebサービスを有効化するには、SYSユーザーとしてログオンし、ロールXDB_WEBSERVICESを目的のユーザーに付与します。このロールはHTTPS経由でのWebサービスを有効化します。Webサービスを使用するために、このロールは必須です。
さらに、ユーザーSYSは、次のいずれかまたは両方のロールをユーザーに付与します。
XDB_WEBSERVICES_OVER_HTTP: HTTP(HTTPSだけでなく)を介したWebサービスの使用を有効にします。
XDB_WEBSERVICES_WITH_PUBLIC: PUBLICにアクセス可能なデータベース・オブジェクトに、Webサービスを使用してアクセスできるようにします。
XDB_WEBSERVICES_WITH_PUBLICが付与されていない場合、そのユーザーは、通常使用できるすべてのデータベース・オブジェクトのうちPUBLICオブジェクトを除くすべてに、所有者に関係なくWebサービスを使用してアクセスできます。ユーザーをWebサービスによってPUBLICオブジェクトにアクセス可能にするには、SYSユーザーがそのユーザーにXDB_WEBSERVICES_WITH_PUBLICロールを付与する必要があります。このロールを付与されたユーザーは、データベースにログオンすれば、通常使用できるすべてのPUBLICオブジェクトにアクセスできます。
データベース問合せに使用するOracle XML DBのWebサービスは、http://host:port/orawsvというURLにあります。ただし、hostおよびportはそれぞれ、使用しているデータベースのホストおよびHTTP(S)ポートのプロパティを表します。このWebサービスは、XML Schemaを使用して入力ドキュメントおよび出力ドキュメントのフォーマットを指定するWSDLドキュメントに関連付けられています。このWSDLドキュメントのURLは、http://host:port/orawsv?wsdlです。
データベース問合せは、例33-3に示されているXML Schemaに準拠したXML文書としてアプリケーションからWebサービスへ送信されます。
例33-3 Webサービスで処理されるデータベース問合せのXML Schema
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xdb="http://xmlns.oracle.com/xdb"
targetNamespace="http://xmlns.oracle.com/orawsv">
<element name="query">
<complexType>
<sequence>
<element name="query_text">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="type">
<simpleType>
<restriction base="NMTOKEN">
<enumeration value="SQL"/>
<enumeration value="XQUERY"/>
</restriction>
</simpleType>
</attribute>
</extension>
</simpleContent>
</complexType>
</element>
<choice maxOccurs="unbounded">
<element name="bind">
<complexType>
<simpleContent>
<extension base="string">
<attribute name="name" type="string"/>
</extension>
</simpleContent>
</complexType>
</element>
<element name="bindXML" type="any"/>
</choice>
<element name="null_handling" minOccurs="0">
<simpleType>
<restriction base="NMTOKEN">
<enumeration value="DROP_NULLS"/>
<enumeration value="NULL_ATTR"/>
<enumeration value="EMPTY_TAG"/>
</restriction>
</simpleType>
</element>
<element name="max_rows" type="positiveInteger" minOccurs="0"/>
<element name="skip_rows" type="positiveInteger" minOccurs="0"/>
<element name="pretty_print" type="boolean" minOccurs="0"/>
<element name="indentation_width" type="positiveInteger" minOccurs="0"/>
<element name="rowset_tag" type="string" minOccurs="0"/>
<element name="row_tag" type="string" minOccurs="0"/>
<element name="item_tags_for_coll" type="boolean" minOccurs="0"/>
</sequence>
</complexType>
</element>
</schema>
このXML Schemaは、WSDLドキュメントに記述されています。受信する問合せドキュメントの中で重要な部分は次のとおりです。
query_text: 問合せのテキストです。属性typeには、問合せのタイプとしてSQLまたはXQUERYを指定します。
bind: スカラー・バインド変数値です。属性nameには変数の名前を指定します。
bindXML: XMLTypeのバインド変数値です。
null_handling: 問合せにより戻されたNULL値の処理方法を指定します。
DROP_NULLS: 出力に何も含めません(要素なし)。これがデフォルトの動作です。
NULL_ATTR: NULL値出力に空の要素を使用します。要素内では属性xsi:nil = "true"を使用します。
EMPTY_TAG: NULL値出力に空の要素を使用します。nil属性は使用しません。
max_rows: 問合せに対して出力する行数の最大値です。デフォルトでは、すべての行が戻されます。
skip_rows: SOAPメッセージ内に戻されたデータの中に行を取り込む前に、スキップする問合せ出力行の数を指定します。これとmax_rowsをあわせて使用することにより、出力のページ区切りを生成できます。デフォルト値は0(ゼロ)です。
pretty_print: 出力ドキュメントをフォーマット出力用にフォーマットするかどうかを指定します。デフォルト値はtrueです。この場合ドキュメントはフォーマット出力されます。値がfalseの場合、フォーマット出力は実行されず、出力行は改行文字で改行されません。
indentation_width: ネストした要素の各行頭のインデント文字数を指定します。デフォルト値は1です。
rowset_tag: 出力ドキュメントのルート要素名です。
row_tag: 1行のみの問合せ出力を値に持つ要素名です。
item_tags_for_coll: collection_name_itemという名前でコレクション要素を生成するかどうかを指定します。ここで、collection_nameはコレクションの名前です。
これらの要素は、PL/SQLパッケージDBMS_XMLGENのプロシージャ内でそれぞれに対応しているパラメータと同じ意味を持っています。
例33-4および例33-5は、単純なSQL問合せの入力および出力を示したものです。
例33-4 問合せWebサービスを使用したSQL問合せの入力XML文書
<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope ">
<env:Body>
<query xmlns="http://xmlns.oracle.com/orawsv">
<query_text type="SQL">
<![CDATA[SELECT * FROM employees WHERE salary = :e]]>
</query_text>
<bind name="e">8300</bind>
<pretty_print>false</pretty_print>
</query>
</env:Body>
</env:Envelope>
例33-4では、問合せテキストは<![CDATA[...]]>で囲まれています。これは、この例の中では必ずしも必要なことではありませんが、問合せには通常<や>などの文字が含まれるため、一般的には適切な方法です。要素bindは、eというバインド変数に値(8300)をバインドするのに使用されます。要素pretty_printでは、出力内容のフォーマット出力が無効になっています。
例33-5 問合せWebサービスを使用したSQL問合せの出力XML文書
<?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2002/06/soap-envelope"> <soap:Body> <ROWSET><ROW><EMPLOYEE_ID>206</EMPLOYEE_ID><FIRST_NAME>William</FIRST_NAME><LAST_NAME>G ietz</LAST_NAME><EMAIL>WGIETZ</EMAIL><PHONE_NUMBER>515.123.8181</PHONE_NUMBER><HIRE_DATE>07-JUN- 94</HIRE_DATE><JOB_ID>AC_ACCOUNT</JOB_ID><SALARY>8300</SALARY><MANAGER_ID>205</MANAGER_ID ><DEPARTMENT_ID>110</DEPARTMENT_ID></ROW></ROWSET> </soap:Body> </soap:Envelope>
PL/SQLストアド・ファンクションおよびストアド・プロシージャへのアクセスに使用するOracle XML DBのWebサービスのURLは、http://host:port/orawsv/dbschema/package/fn_or_procです。またパッケージに含まれていない(スタンドアロン)ファンクションやプロシージャへのアクセスに使用するWebサービスのURLは、http://host:port/orawsv/dbschema/fn_or_procです。ここで、hostおよびportはそれぞれ使用しているデータベースのホストおよびHTTP(S)ポートのプロパティ、fn_or_procはストアド・ファンクションまたはストアド・プロシージャの名前、packageはストアド・ファンクションまたはストアド・プロシージャが含まれているパッケージ、dbschemaはそのパッケージを所有するデータベース・スキーマです。
入力XML文書には、ファンクションまたはプロシージャで必要となる入力内容が含まれます。また出力XML文書には、戻り値、およびOUT変数すべての値も含まれます。
入力ドキュメントおよび出力ドキュメント内のXML要素の名前は、ファンクションまたはプロシージャの変数名に対応しています。生成されたWSDLドキュメントには、正確なXML要素名が表示されます。使用されているネーミング規則は次のとおりです。
PL/SQLファンクションへの入力を指定するXML要素には、function-nameInputという形式の名前が付けられます。ここで、function-nameはファンクションの名前です(大文字)。
ファンクションの入力パラメータを指定するXML要素には、param-name-param-type-io-modeという形式の名前が付けられます。ここで、param-nameはパラメータの名前(大文字)、param-typeはそのSQLデータ型であり、io-modeは次のいずれかの入出力モードです。
IN: INモード
OUT: OUTモード
INOUT: IN OUTモード
PL/SQLファンクションからの出力を指定するXML要素には、Sreturn-type-function-nameOutputという形式の名前が付けられます。ここで、return-typeは戻り値のSQLデータ型(大文字)、function-nameはファンクションの名前(大文字)です。
ファンクションの出力パラメータを指定するXML要素には、出力パラメータ自体と同じ名前(大文字)が付けられます。戻り値を指定する要素には、RETURNという名前が付けられます。
ファンクションの戻り値は、出力ドキュメントのRETURN要素内にあります。この要素は常にドキュメントの先頭に表示されます。戻り値は、この表示位置によって、RETURNという名前になる可能性のあるOUTパラメータとは明確に区別できます。
ストアド・ファンクションまたはストアド・プロシージャはそれぞれ、生成済WSDLドキュメントを持つ、動的な個別Webサービスに関連付けられます。このWSDLドキュメントのURLは、http://host:port/orawsv/dbschema/package/fn_or_proc?wsdlまたはhttp://host:port/orawsv/dbschema/fn_or_proc?wsdlです。またオプションで、特定のパッケージ内のすべてのストアド・ファンクションおよびストアド・プロシージャで共用するWSDLドキュメントも生成できます。このWSDLドキュメントのURLは、http://host:port/orawsv/dbschema/package?wsdlです。
受信するXML文書および送信するXML文書内のデータ型は、表33-1に従って、ストアド・ファンクションまたはストアド・プロシージャで使用されるSQLデータ型にマップされます。
表33-1 XMLデータ型とSQLデータ型のWebサービスによるマッピング
| SQLデータ型 | XML Schemaデータ型 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
PL/SQL |
|
|
オブジェクト型 |
|
オブジェクト型は、同じ名前の複合型要素としてXMLで表現されます。オブジェクト属性は、その要素の子として表現されます。
この項では、単純なPL/SQLファンクションと、Webサービスを使用したアクセスについて説明します。このファンクションは、部門IDおよび部門名を入力として受け取り、その部門の全従業員の給与合計を戻します。またこのファンクションは、入出力パラメータおよび出力パラメータとしてそれぞれ、部門名およびその部門の従業員数を戻します。部門IDのデフォルト値は20です。この単純な例では、入出力パラメータdept_nameの入力値は実際には使用されません。それは無視され、正しい名前が戻されます。
例33-6は、ファンクションの定義を示したものです。例33-7は、このファンクションの定義から自動的に作成されたWSDLドキュメントです。例33-8は、ストアド・ファンクションを起動する入力ドキュメントです。例33-9は、結果の出力ドキュメントです。
例33-6 Webサービス・アクセスに使用するPL/SQLファンクションの定義
CREATE OR REPLACE PACKAGE salary_calculator AUTHID CURRENT_USER AS
FUNCTION TotalDepartmentSalary (dept_id IN NUMBER DEFAULT 20,
dept_name IN OUT VARCHAR2,
nummembers OUT NUMBER)
RETURN NUMBER;
END salary_calculator;
/
CREATE OR REPLACE PACKAGE BODY salary_calculator AS
FUNCTION TotalDepartmentSalary (dept_id IN NUMBER DEFAULT 20,
dept_name IN OUT VARCHAR2,
nummembers OUT NUMBER)
RETURN NUMBER IS
sum_sal NUMBER;
BEGIN
SELECT SUM(salary) INTO sum_sal FROM employees
WHERE department_id = dept_id;
SELECT department_name INTO dept_name FROM departments
WHERE department_name = dept_name;
SELECT count(*) INTO nummembers FROM employees
WHERE department_id = dept_id;
RETURN sum_sal;
END;
END;
/
例33-7 ストアドPL/SQLファンクションに対応するWSDLドキュメント
<definitions name="SALARY_CALCULATOR"
targetNamespace="http://xmlns.oracle.com/orawsv/HR/SALARY_CALCULATOR"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://xmlns.oracle.com/orawsv/HR/SALARY_CALCULATOR"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
<types>
<xsd:schema targetNamespace="http://xmlns.oracle.com/orawsv/HR/SALARY_CALCULATOR"
elementFormDefault="qualified">
<xsd:element name="SNUMBER-TOTALDEPARTMENTSALARYInput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="NUMMEMBERS-NUMBER-OUT">
<xsd:complexType/>
</xsd:element>
<xsd:element name="DEPT_NAME-VARCHAR2-INOUT" type="xsd:string"/>
<xsd:element name="DEPT_ID-NUMBER-IN" type="xsd:double"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="TOTALDEPARTMENTSALARYOutput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="RETURN" type="xsd:double"/>
<xsd:element name="NUMMEMBERS" type="xsd:double"/>
<xsd:element name="DEPT_NAME" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</types>
<message name="TOTALDEPARTMENTSALARYInputMessage">
<part name="parameters" element="tns:SNUMBER-TOTALDEPARTMENTSALARYInput"/>
</message>
<message name="TOTALDEPARTMENTSALARYOutputMessage">
<part name="parameters" element="tns:TOTALDEPARTMENTSALARYOutput"/>
</message>
<portType name="SALARY_CALCULATORPortType">
<operation name="TOTALDEPARTMENTSALARY">
<input message="tns:TOTALDEPARTMENTSALARYInputMessage"/>
<output message="tns:TOTALDEPARTMENTSALARYOutputMessage"/>
</operation>
</portType>
<binding name="SALARY_CALCULATORBinding" type="tns:SALARY_CALCULATORPortType">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="TOTALDEPARTMENTSALARY">
<soap:operation soapAction="TOTALDEPARTMENTSALARY"/>
<input>
<soap:body parts="parameters" use="literal"/>
</input>
<output>
<soap:body parts="parameters" use="literal"/>
</output>
</operation>
</binding>
<service name="SALARY_CALCULATORService">
<documentation>Oracle Web Service</documentation>
<port name="SALARY_CALCULATORPort" binding="tns:SALARY_CALCULATORBinding">
<soap:address location="httpS://example:8088/orawsv/HR/SALARY_CALCULATOR"/>
</port>
</service>
</definitions>
例33-8 Webサービスを使用したPL/SQL問合せの入力XML文書
<?xml version="1.0" ?><soap:Envelope xmlns:soap="http://www.w3.org/2002/06/soap-envelope"><soap:Body><SNUMBER- TOTALDEPARTMENTSALARYinput xmlns="http://xmlns.oracle.com/orawsv/HR/SALARY_CALCULATOR/TOTALDEPARTMENTSALARY"> <DEPT_ID-NUMBER-IN>30</DEPT_ID-NUMBER-IN><DEPT_NAME-VARCHAR2-INOUT>Purchasing </DEPT_NAME-VARCHAR2-INOUT><NUMMEMBERS-NUMBER-OUT/></SNUMBER- TOTALDEPARTMENTSALARYinput></soap:Body></soap:Envelope>
例33-9 Webサービスを使用したPL/SQL問合せの出力XML文書
<?xml version="1.0" ?>
<soap:Envelope xmlns:soap="http://www.w3.org/2002/06/soap-envelope">
<soap:Body>
<TOTALDEPARTMENTSALARYOutput
xmlns="http://xmlns.oracle.com/orawsv/HR/SALARY_CALCULATOR/TOTALDEPARTMENTSALARY">
<RETURN>24900</RETURN>
<NUMMEMBERS>6</NUMMEMBERS>
<DEPT_NAME>Purchasing</DEPT_NAME>
</TOTALDEPARTMENTSALARYOutput>
</soap:Body>
</soap:Envelope>
