用瀏覽器打開一個 WSDL 檔,常常只會看到一句「This XML file does not appear to have any style information associated with it. The document tree is shown below.」,然後是一大串難以閱讀的巢狀結構。本文以一份實際的 WCM 內容服務 WSDL 為例,說明該從哪裡讀起。
<wsdl:definitions xmlns:impl="https://content.front.wcm.it.huawei.com"
xmlns:intf="https://content.front.wcm.it.huawei.com"
xmlns:tns2="https://busi.wcm.it.huawei.com"
xmlns:tns3="https://search.wcm.it.huawei.com"
xmlns:tns4="https://common.vo.wcm.it.huawei.com"
xmlns:wsaw="https://www.w3.org/2006/05/addressing/wsdl"
xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
xmlns:wsdlsoap="https://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsi="https://ws-i.org/profiles/basic/1.1/xsd"
xmlns:xsd="https://www.w3.org/2001/XMLSchema"
targetNamespace="https://content.front.wcm.it.huawei.com">
幾個判讀重點:targetNamespace 是這個服務自己的命名空間;impl 與 intf 指向同一個 URI,這是 Java 端工具(Axis 系列)產生 WSDL 時的典型特徵,分別代表實作與介面;tns2 到 tns4 則是它依賴的外部型別命名空間。另外帶有 wsi 命名空間,說明這份文件宣稱符合 WS-I Basic Profile 的互操作性規範。
WSDL 的 types 區段通常就是整份文件最長的部分,因為所有資料結構都定義在這裡。本案例中,WcmContentVO 定義於 https://busi.wcm.it.huawei.com 命名空間:
<complexType name="WcmContentVO">
<sequence>
<element name="tactic" nillable="true" type="xsd:string"/>
<element name="password" nillable="true" type="xsd:string"/>
<element name="username" nillable="true" type="xsd:string"/>
<element name="dcreatedate" nillable="true" type="xsd:string"/>
<element name="ddocname" nillable="true" type="xsd:string"/>
<element name="ddoctitle" nillable="true" type="xsd:string"/>
<element name="did" nillable="true" type="xsd:string"/>
<!-- ……其餘欄位 -->
</sequence>
</complexType>
這個 VO 同時是許多操作的入參與出參,因此它的欄位幾乎涵蓋了整個內容服務的資料面。
認證資訊:username、password、dusername、ipAddress、sysNum。把帳密直接放在資料物件裡傳遞,是這類老系統常見的做法,但也意味著傳輸層務必走 HTTPS,並留意呼叫端不要將憑證寫進日誌。
文件 metadata(d 系列):ddocname、ddoctitle、ddoctype、ddocauthor、ddocaccount、dcreatedate、dindate、doutdate、dreleasedate、dformat、dextension、dwebextension、doriginalname、dfulltextcharset、dfulltextformat。這一組是內容庫的核心描述資料。
版本與安全:drevisionid、drevlabel、drevclassid、dsecuritygroup、dwebflag 對應的 xwebflag、xforcefoldersecurity、xreadonly、xhidden。
檔案與呈現:url、webfilesize、vaultfilesize、srfdocsnippet、contentDetail、conversiontemplate、conversionstyle、xhw_dynamic_url、xhw_static_url、xhw_default_url、xhw_image、xhw_related_thumbnail、xvideorenditions。
企業擴充(xhw_ 前綴):包含聯絡人區塊(xhw_contact_*)、方案與成功案例多媒體(xhw_solution_product_1..3、xhw_solution_subsolution_1..3、xhw_solution_successtory_1..3、xhw_solution_video_1..5)、PBI 層級(xhw_pbi1_lt 到 xhw_pbi7_lt)、以及大量 xhw_reserved_field* 保留欄位。
分類與統計:ent_content_type、ent_product_lev1..3、ent_solution_lev1..3、industry_insight_l1..3、totalRows。其中 totalRows 的存在暗示這個 VO 也被用在分頁查詢的結果上。
面對這種長度可觀的 WSDL,有效率的閱讀順序是:
1. 先在 wsdl:portType 找操作清單,確認有哪些方法可用;
2. 再到 wsdl:types 搜尋對應的請求與回應 element,看它引用了哪些 complexType;
3. 最後才深入 complexType 看欄位;
4. 所有 nillable="true" 的欄位都要視為可選,呼叫端必須容錯。
另外提醒一點:這份型別把 password 與大量 metadata 混在同一個物件裡,代表查詢結果物件也可能帶回認證欄位。整合時最好在邊界層做一次欄位白名單過濾,別讓不必要的欄位流進你的應用層或前端。