この章の内容は次のとおりです。
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-name
Input
という形式の名前が付けられます。ここで、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要素には、S
return-type
-
function-name
Output
という形式の名前が付けられます。ここで、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>