PL/SQL 呼叫 Web Service 實作：UTL_DBWS 套件完整教學

背景與架構

Oracle 9i 釋出擴充套件支援 PL/SQL 呼叫 Web Service，10g 引入 UTL_DBWS 封裝 JPublisher，讓開發者僅需少數 API 即可完成呼叫。

環境建置

1. 安裝 Oracle Database（Enterprise/Standard/Personal Edition，**不可安裝 Instant Client**，需 sqlj 元件）。
2. 下載對應版本 UTL_DBWS：
       Pre-10g: dbws-callout-utility.zip
       10g: dbws-callout-utility-10R2.zip
3. 解壓至 $ORACLE_HOME/sqlj/lib。
4. 載入 JAR 至 SYS Schema：

$ORACLE_HOME/bin/loadjava -u sys/password -r -v -f -s -grant public -noverify -genmissing \
  $ORACLE_HOME/sqlj/lib/dbwsclient.jar

※ 官方文件稱 10g 內建，但實測全新安裝仍缺此包，需手動部署。

實作範例：呼叫 Hello World Web Service

假設已部署 hellows 服務，WSDL：https://localhost:8888/hellows/helloService?WSDL，方法 sayHello(String)。

建立 PL/SQL Function

CREATE OR REPLACE FUNCTION call_sayHello (username IN VARCHAR2)
RETURN VARCHAR2
AS
  l_service      UTL_DBWS.service;
  l_call         UTL_DBWS.call;
  l_result       ANYDATA;
  l_wsdl_url     VARCHAR2(1024) := 'https://localhost:8888/hellows/helloService?WSDL';
  l_service_name VARCHAR2(200)  := 'helloService';
  l_op_name      VARCHAR2(200)  := 'sayHello';
  l_input_params UTL_DBWS.anydata_list;
BEGIN
  -- 1. 建立 Service Handle
  l_service := UTL_DBWS.create_service(
    wsdl_document_location => URIFACTORY.getURI(l_wsdl_url),
    service_name           => l_service_name
  );

  -- 2. 建立 Call Handle
  l_call := UTL_DBWS.create_call(
    service_handle => l_service,
    port_name      => NULL,          -- 使用預設 Port
    operation_name => l_op_name
  );

  -- 3. 設定輸入參數
  l_input_params(1) := ANYDATA.ConvertVarchar2(username);

  -- 4. 呼叫 Web Service
  l_result := UTL_DBWS.invoke(
    call_handle  => l_call,
    input_params => l_input_params
  );

  -- 5. 釋放資源
  UTL_DBWS.release_call(call_handle => l_call);
  UTL_DBWS.release_service(service_handle => l_service);

  -- 6. 回傳結果
  RETURN ANYDATA.AccessVarchar2(l_result);

EXCEPTION
  WHEN OTHERS THEN
    -- 實務建議記錄錯誤日誌
    RETURN NULL;
END call_sayHello;
/

測試呼叫

SELECT call_sayHello('Oracle') FROM dual;
-- 回傳：Hello, Oracle!

關鍵 API 快速查閱

進階主題

• 複雜型別：需對應 WSDL 中的 Complex Type，使用 SYS.XMLTYPE 或自訂 Object Type 傳遞。
• 非同步/單向呼叫：設定 UTL_DBWS.set_property(l_call, 'SOAPACTION_USE', 'FALSE') 等。
• SSL/憑證：配置 Oracle Wallet，設定 UTL_DBWS.set_wallet。
• 錯誤處理：捕捉 UTL_DBWS.INVALID_CALL、UTL_DBWS.SOAP_FAULT 等特定例外。

替代方案

12c+ 可考慮 APEX_WEB_SERVICE（APEX 內建）或 Java Stored Procedure 呼叫 JAX-WS Client，功能更豐富、除錯更容易。