WEB-INF/proxy-config.xml 檔


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>	
在上述範例中,ProxyServlet 是 Ajax Proxy 的 Servlet。 <url-pattern> 是指向 /proxymashup/* 的 Servlet 對映。 如果 Web 應用程式保存檔 (WAR) 的環境定義根目錄是 /proxy,您就利用 Dojo,以下列程式碼來存取服務:
var deferred = dojo.xhrGet( {
                             url: "/proxy/proxymashup/location/coffee",
                             timeout: 5000,
                             handleAs : "text/json",
                             headers: { "Content-Type":"text/html" },
                             } );


XML 綱目

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。

過濾 MIME 類型

「多用途網際網路郵件延伸 (MIME)」類型會控制 Proxy 所能接受來自服務的媒體類型。 在先前的範例中,如果您想要確定只將 text/json 內容類型傳回用戶端,您可以新增下列項目到 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

您可以指定 Cookie 原則,利用 Ajax Proxy 來控制指向用戶端的 Cookie 流程。 只有符合 Cookie 原則值的 Cookie 能夠通過 Ajax Proxy。 如果未指定 Cookie 原則,則任何 Cookie 都不可通過 Ajax Proxy。

如果要控制 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>

過濾 HTTP 標頭

依預設,Ajax Proxy 允許將下列 HTTP 標頭傳給用戶端:User-Agent, Accept*, Content*, Authorization*。 (*) 代表萬用字元。 在要求傳給服務之前,Ajax Proxy 會除去所有其他標頭。 對大部分應用程式而言,這些標頭就已足夠。 您可以將下列配置插入 Proxy 配置檔中,以定義您自己的一組容許的 HTTP 標頭:
<proxy:policy url="*" acf="none">
    .
    .
    <proxy:headers>
       <proxy:header>User-Agent</proxy:header>
       <proxy:header&gtAccept*</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>

過濾 HTTP 方法

在上述範例中,Ajax Proxy 配置成只接受用戶端所發出的 GET 要求。 POST 或其他 HTTP 方法要求會將錯誤狀況傳回用戶端。 Ajax Proxy 支援 GET、POST、PUT、HEAD 或 DELETE 要求。 您必須指定至少一個支援的 HTTP 方法。

SSL 的支援

許多服務都可能需要使用 SSL 的 Secure Socket 連線。 作為一個 Web 應用程式,Ajax Proxy 會使用 JavaTM Secure Socket Extension (JSSE),受到產品的全面支援。 請參閱對應的 WebSphere® SSL 憑證支援文件。

使用未簽署的 SSL 憑證

依預設,Ajax Proxy 不支援未簽署的憑證。 相反地,您會收到含有無法辨識 SSL 信號交換 訊息的 SSL 異常狀況。 如果您需要未簽署的 SSL 憑證以便進行測試或開發,您可以在 proxy-config.xml 檔中啟用下列選項:
    <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 可以用許多參數來調整。

maxconnectionsperhost

maxconnectionperhost 是一個廣域值,指定任何主機或埠組合的保持作用中的連線數目上限。 依預設,這個值會設為 2。 如果您的應用程式會存取多個遠端網站來取得內容,請增加這個值。

<proxy:meta-data>
   <proxy:name>maxconnectionsperhost</proxy:name>
       <proxy:value>2</proxy:value>
</proxy:meta-data>

maxtotalconnections

maxtotalconnections 是 Proxy 所支援的連線總數上限。 預設值是 5。 您選擇的值必須夠高,足以支援您可能同時接收的連線數目。 實際上,請將 Web 儲存器的配置方式及儲存器同時支援的連線數目列入考量因素。

<proxy:meta-data>
   <proxy:name>maxtotalconnections</proxy:name>
   <proxy:value>5</proxy:value>
</proxy:meta-data>

socket-timeout

socket-timeout 定義建立好連線之後,等待資料的預設 Socket 逾時(毫秒)。 預設的逾時值是 0,表示無逾時限制。

<proxy:meta-data>
   <proxy:name>socket-timeout</proxy:name>
   <proxy:value>5000</proxy:value>
</proxy:meta-data>

retries

retries 定義在放棄建立連線之前,Ajax Proxy 所應執行的 Socket 重試次數。 預設值是重試兩次。

<proxy:meta-data>
   <proxy:name>retries</proxy:name>
   <proxy:value>3</proxy:value>
</proxy:meta-data>

connection-timeout

connection-timeout 定義建立連線之前的時間(毫秒)。 如果未指定任何值,就使用預設值 60000。 如果使用 0,這個值就表示不使用逾時值。

<proxy:meta-data>
   <proxy:name>connection-timeout</proxy:name>
   <proxy:value>3000</proxy:value>
</proxy:meta-data>

connection-pool-timeout

connection-pool-time 定義嘗試連線之前的時間(毫秒)。這種情況適用於在超出 maxtotalconnections 之後的所有後續的要求。如果使用 0,這個值就表示不使用逾時值。 0 也是預設值。

<proxy:meta-data>
   <proxy:name>connection-pool-timeout</proxy:name>
   <proxy:value>1000</proxy:value>
</proxy:meta-data>

forward-http-errors

依預設,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>

連接至另一個 Proxy

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 鑑別方法。

過濾 IP 位址

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>

在這個範例中,Ajax Proxy 會進行下列過濾: 因此,在這個情況下,Proxy 不允許存取 IP 位址 9.6.2.5 或 9.6.120.7,且會回應下列訊息:
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 一律會按照它們的定義順序來處理它們。 這表示最後相符的規則一律是最優先的,不論在它前面有任何允許或拒絕規則,都是如此。


使用條款 | 意見