透過 PL/SQL 呼叫 Web Services：UTL_DBWS 實戰指南

Oracle 10g 引入 UTL_DBWS 套件，封裝 JPublisher 功能，讓 PL/SQL 開發者能以簡單 API 呼叫外部 Web Services。本文以呼叫 sayHello 服務為例，完整示範環境建置、程式撰寫與測試流程。

環境建置

1. 安裝 Oracle Database（企業版/標準版/個人版，**不可安裝快捷版**，缺少 SQLJ 元件）
2. 下載對應版本 UTL_DBWS：
   • Pre-10g: dbws-callout-utility.zip
   • 10g R2: 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 內建，但實測全新安裝仍缺少此套件，需手動載入。

呼叫 Web Service 範例

假設已部署 WSDL 為 https://localhost:8888/hellows/helloService?WSDL 的服務，含 sayHello 操作。

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_OPERATION     VARCHAR2(200)  := 'sayHello';
  L_INPUT_PARAMS  UTL_DBWS.ANYDATA_LIST;
BEGIN
  -- 建立服務與呼叫控制代碼
  L_SERVICE := UTL_DBWS.CREATE_SERVICE(
    WSDL_DOCUMENT_LOCATION => URIFACTORY.GETURI(L_WSDL_URL),
    SERVICE_NAME           => L_SERVICE_NAME
  );
  L_CALL := UTL_DBWS.CREATE_CALL(
    SERVICE_HANDLE => L_SERVICE,
    PORT_NAME      => NULL,
    OPERATION_NAME => L_OPERATION
  );

  -- 設定輸入參數並呼叫
  L_INPUT_PARAMS(1) := ANYDATA.CONVERTVARCHAR2(USERNAME);
  L_RESULT := UTL_DBWS.INVOKE(
    CALL_HANDLE  => L_CALL,
    INPUT_PARAMS => L_INPUT_PARAMS
  );

  -- 釋放資源並回傳
  UTL_DBWS.RELEASE_CALL(L_CALL);
  UTL_DBWS.RELEASE_SERVICE(L_SERVICE);
  RETURN ANYDATA.ACCESSVARCHAR2(L_RESULT);

EXCEPTION
  WHEN OTHERS THEN
    UTL_DBWS.RELEASE_CALL(L_CALL);
    UTL_DBWS.RELEASE_SERVICE(L_SERVICE);
    RETURN NULL;
END CALL_SAYHELLO;

測試驗證

SELECT CALL_SAYHELLO('World') FROM DUAL;
-- 預期回傳: "Hello World"

關鍵物件與方法對照

常見問題與對策

• ClassNotFound / NoClassDefFoundError：確認 loadjava 成功載入所有 JAR，檢查 DBA_OBJECTS 中 JAVA CLASS 狀態
• 網路逾時：設定 UTL_HTTP 代理或防火牆規則，必要時調整 UTL_DBWS.SET_PROPERTY 逾時參數
• WSDL 變更：重新建立 SERVICE 控制代碼，或實作快取機制定期刷新
• 複雜型別：需對應 JPublisher 產生的 SQL 類型，或手動組裝 XML

UTL_DBWS 讓資料庫直接參與服務導向架構，減少中介層跳轉，適合資料密集型整合場景。