proxy-config.xml 檔定義一個原則來支援透過 Proxy 傳遞 URI 要求,以及定義如何將環境定義路徑,從用戶端對映至伺服器中的 URL。
您可以利用文字編輯器來修改 proxy-config.xml 檔。 請將這個檔案儲存在 Proxy Servlet 能夠找到的類別路徑中的位置。 proxy-config.xml 檔的變更並不是動態的;請重新啟動 Servlet,使變更生效。
請設想一個 JavaTM Platform Enterprise Edition (Java EE) 企業保存檔 (EAR),其中含有您的 Ajax 型應用程式。 您利用 Dojo Toolkit 來結合起源於另一部伺服器的內容,並提供咖啡屋的位置資訊。 另一部伺服器傳回的資料格式是「JavaScriptTM 物件表示法 (JSON)」資料。 請將傳回的 JSON 資料與您正在開發的 Ajax 型應用程式結合起來,這通常稱為一項用戶端結合。
輸入下列幾行程式碼:
GET http://www.myinformation.com/location/coffee HTTP/1.1傳回的 JSON 內容如下:
{ "locations":{ "location":[ { "id":"Jumpin Joes Example", "city":"Anywhere", "location":"Weston Pkwy", "address":"126 Weston Pkwy, Anywhere, NC 27513", "date":"May 2nd, 2008" }, { "id":"Coffee & Crepes Example", "city":"Anywhere", "location":"Crossroads Blvd", "address":"123 Crossroads Blvd, Anywhere, NC 27518", "date":"May 3rd, 2008" } ] } }
您可以在 proxy-config.xml 檔中新增下面幾行程式碼,利用 Ajax Proxy 來提供服務:
<?xml version="1.0" encoding="UTF-8"?> <proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/websphere/featurepack/v6.1/proxy-config" xsi:noNamespaceSchemaLocation="C:\temp\proxy-config.xsd"> <proxy:mapping contextpath="/location/coffee" url="http://www.myinformation.com"/> <proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> </proxy:policy> </proxy-rules>
上述環境定義路徑是所存取之服務的環境定義根目錄。 URL 是服務的根 URL。 例如,您可以利用 http://www.myinformation.com/location/coffee,直接在瀏覽器中存取服務
在程式碼內存取 Proxy 的路徑,會隨著已部署的 Ajax Proxy 而不同。 請設想 web.xml 中,可用於 Ajax Proxy 的 XML 片段:
<servlet-mapping> <servlet-name>ProxyServlet</servlet-name> <url-pattern>/proxymashup/*</url-pattern> </servlet-mapping>
var deferred = dojo.xhrGet( { url: "/proxy/proxymashup/location/coffee", timeout: 5000, handleAs : "text/json", headers: { "Content-Type":"text/html" }, } );
proxy-config.xml 檔的 XML 綱目在 AjaxProxy.war 檔的 WEB-INF/ 目錄中。 兩個綱目是 proxy-config_1.0.1.xsd 和 proxy-config_1.0.xsd。 proxy-config_1.0.1.xsd 對應於 1.0.1 版,其中含有「IP 過濾功能」之類的新特性。使用者可以繼續使用對應於 proxy-config_1.0.xsd 的舊版 proxy-config.xml。
<proxy:policy url="*" acf="none"> . . <proxy:mime-types> <proxy:mime-type>text/json</proxy:mime-type> </proxy:mime-types> . . </proxy:policy>
如果服務傳回 text/html,Proxy 的回應是向用戶端傳回錯誤狀況,因為 text/html 未列在可從伺服器接受的內容類型中。 如果未指定 <proxy:mime-types>,行為就是接受所有內容類型。
如果要控制 Cookie 的流程,請在 proxy-config.xml 檔中定義容許的 Cookie 名稱。 下列範例顯示如何將 Proxy 配置成只會傳遞 Cookie 索引鍵名稱為 Session-Cookie-0 的 Cookie
<proxy:policy url="*" acf="none"> . . <proxy:cookies> <proxy:cookie>Session-Cookie-0</proxy:cookie> </proxy:cookies> . . </proxy:policy>
<proxy:policy url="*" acf="none"> . . <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept*</proxy:header> <proxy:header>Content*</proxy:header> <proxy:header>Authorization*</proxy:header> <proxy:header>My-New-Header</proxy:header> <proxy:header>My-Other-New-Header</proxy:header> </proxy:headers> . . </proxy:policy>
許多服務都可能需要使用 SSL 的 Secure Socket 連線。 作為一個 Web 應用程式,Ajax Proxy 會使用 JavaTM Secure Socket Extension (JSSE),受到產品的全面支援。 請參閱對應的 WebSphere® SSL 憑證支援文件。
<proxy-meta-data> <proxy:name>unsigned_ssl_certificate_support</proxy:name> <proxy:value>true</proxy:value> </proxy-meta-data>
當啟用 unsigned_ssl_certificate_support 時,Ajax Proxy 會接受任何 SSL 憑證。 實際上,這個設定適用於開發,不應在正式作業環境中使用。
Ajax Proxy 可以用許多參數來調整。
maxconnectionperhost 是一個廣域值,指定任何主機或埠組合的保持作用中的連線數目上限。 依預設,這個值會設為 2。 如果您的應用程式會存取多個遠端網站來取得內容,請增加這個值。
<proxy:meta-data> <proxy:name>maxconnectionsperhost</proxy:name> <proxy:value>2</proxy:value> </proxy:meta-data>
maxtotalconnections 是 Proxy 所支援的連線總數上限。 預設值是 5。 您選擇的值必須夠高,足以支援您可能同時接收的連線數目。 實際上,請將 Web 儲存器的配置方式及儲存器同時支援的連線數目列入考量因素。
<proxy:meta-data> <proxy:name>maxtotalconnections</proxy:name> <proxy:value>5</proxy:value> </proxy:meta-data>
socket-timeout 定義建立好連線之後,等待資料的預設 Socket 逾時(毫秒)。 預設的逾時值是 0,表示無逾時限制。
<proxy:meta-data> <proxy:name>socket-timeout</proxy:name> <proxy:value>5000</proxy:value> </proxy:meta-data>
retries 定義在放棄建立連線之前,Ajax Proxy 所應執行的 Socket 重試次數。 預設值是重試兩次。
<proxy:meta-data> <proxy:name>retries</proxy:name> <proxy:value>3</proxy:value> </proxy:meta-data>
connection-timeout 定義建立連線之前的時間(毫秒)。 如果未指定任何值,就使用預設值 60000。 如果使用 0,這個值就表示不使用逾時值。
<proxy:meta-data> <proxy:name>connection-timeout</proxy:name> <proxy:value>3000</proxy:value> </proxy:meta-data>
connection-pool-time 定義嘗試連線之前的時間(毫秒)。這種情況適用於在超出 maxtotalconnections 之後的所有後續的要求。如果使用 0,這個值就表示不使用逾時值。 0 也是預設值。
<proxy:meta-data> <proxy:name>connection-pool-timeout</proxy:name> <proxy:value>1000</proxy:value> </proxy:meta-data>
依預設,Ajax Proxy 只會轉遞大於或等於 200,小於 400 的 HTTP 狀態碼。 在範圍之外的狀態碼,會自動改成「404 找不到檔案」錯誤。 唯一例外是 401 碼(未獲授權),除非這個特定要求啟用了 basic-auth-support 屬性,否則,它會導致「403 禁止」。
您可以在 proxy-config.xml 中設定 forward-http-errors meta 參數,以隨附訊息轉遞大於或等於 400 的 HTTP 碼
<proxy:meta-data> <proxy:name>forward-http-errors</proxy:name> <proxy:value>true</proxy:value> </proxy:meta-data>
Ajax Proxy 可以配置成先連接到另一個 Proxy,再存取網路。 如果 Ajax Proxy 需要先通往邊界防火牆,再存取網路,就可能需要連接到透通 Proxy。 Ajax Proxy 支援基本鑑別。
下列範例顯示虛擬 Proxy 防火牆的配置。 passthru_host 是必要的參數。 其他像是 passthru_type、passthru_username 和 passthru_password 則是選用參數。passthru_type 參數表示所用的鑑別類型。預設類型是 BASIC。或者,也可以使用 DIGEST 和 NTLM。 NTLM 需要 passthru_hostname 和 passthru_domain 等額外參數。passthru_port 和 passthru_realm 參數也是選用的。如果未指定 passthru_port 參數,就會使用 80 埠預設值。 如果未指定 passthru_realm 參數,就會所有鑑別嘗試都傳送認證。 請在正式作業環境中指定 passthru_realm 參數,以防止所有鑑別要求都顯示使用者名稱和密碼資訊。
<proxy-meta-data> <proxy:name>passthru_type</proxy:name> <proxy:value>BASIC</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_host</proxy:name> <proxy:value>9.17.237.132</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_port</proxy:name> <proxy:value>3128</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_realm</proxy:name> <proxy:value>MyRealm</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_username</proxy:name> <proxy:value>username</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_password</proxy:name> <proxy:value>password</proxy:value> </proxy-meta-data>
您可以在 proxy-config.xml 中,設定原則的 basic-auth-support 屬性來啟用基本鑑別。 例如:
<proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1"> <proxy:mapping contextpath="/proxy/*" /> <proxy:policy url="*" acf="none" basic-auth-support="true"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> </proxy:policy> </proxy-rules>
在這個範例中,Ajax Proxy 會將 HTTP 狀態和標頭資訊轉遞回目標服務和用戶端。 如果未設定 basic-auth-support,Ajax Proxy 會接收 401 要求,Proxy 會將要求對映至「403:禁止」的 HTTP 碼。
附註:目前「基本鑑別」機制是 Proxy 唯一支援的 HTTP 鑑別方法。
Ajax Proxy 的「IP 過濾功能」可讓您將 IP 位址列入白名單或黑名單中,以便保護 Ajax Proxy 所能連接的服務。 黑名單包含不允許用戶端連接的服務 IP 位址,白名單包含 Ajax Proxy 所能連接的服務 IP 位址。
proxy:ipfilter 定義要過濾的 IP 位址。 proxy:allow 定義 IP 位址或位址範圍的白名單。 proxy:deny 定義 IP 位址或位址範圍的黑名單。
例如:<proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1"> <proxy:mapping contextpath="/proxy/*" > <proxy:ipfilter> <proxy:deny>9.6.0.0/255.255.0.0</proxy:deny> <proxy:allow>9.6.1.0/255.255.255.0</proxy:allow> <proxy:deny>9.6.1.4</proxy:deny> </proxy:ipfilter> </proxy:mapping> <proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> </proxy:policy> </proxy-rules>
CWXJX1000E: 規則禁止指定的目標主機 IP 位址。
不過,Ajax Proxy 會存取 9.6.1.5 或 9.6.1.120,但拒絕存取 9.6.1.4。
另一個範例先將所有 IP 位址都列入黑名單中,但新增了其他 IP 範圍。 在這個範例中,下列程式碼元素封鎖了所有 IP 位址:*.*.*.*。 支援 98.137.80.1 至 98.137.254 範圍內的 IP 位址。
<proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1"> <proxy:mapping contextpath="/rss/economy" url="http://rss.news.yahoo.com"> <proxy:ipfilter> <proxy:deny>*.*.*.*</proxy:deny> <proxy:allow>98.137.80.0/255.255.255.0</proxy:allow> </proxy:ipfilter> </proxy:mapping> <proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> </proxy:policy> </proxy-rules>
當您新增過濾器規則時,您可以用許多種方式來組合它們,但 Ajax Proxy 一律會按照它們的定義順序來處理它們。 這表示最後相符的規則一律是最優先的,不論在它前面有任何允許或拒絕規則,都是如此。