URLRequest  - AS3

針對這個要求，指定是否應處理驗證要求 (true 或 false)。如果為 false，則驗證挑戰會傳回 HTTP 錯誤。

支援的驗證方法為：

• Windows：HTTP 基本/摘要、Windows 整合式驗證 (包括 NTLM 和 Kerberos)、SSL 憑證驗證。
• Mac：HTTP 基本/摘要、NTLM、SSL 憑證驗證。

注意：FileReference.upload()、FileReference.download() 和 HTMLLoader.load() 方法不支援 URLRequest.authenticate 屬性。

預設值為 true。

相關 API 元素

指定是否應快取這個要求的成功回應資料。設定為 true 時，AIR 應用程式會使用作業系統的 HTTP 快取。

注意：HTMLLoader.load() 方法不支援 URLRequest.cacheResponse 屬性。

預設值為 true。

相關 API 元素

data 屬性中內容的 MIME 內容類型。

預設值為 application/x-www-form-urlencoded。

注意：FileReference.upload()、FileReference.download() 和 HTMLLoader.load() 方法不支援 URLRequest.contentType 屬性。

傳送 POST 要求時，contentType 和 data 屬性的值必須正確對應。contentType 屬性的值會指示伺服器如何解譯 data 屬性的值。

• 如果 data 屬性的值為 URLVariables 物件，contentType 的值就必須是 application/x-www-form-urlencoded。
• 如果 data 屬性的值為任何其它類型，contentType 的值就應該指出即將傳送之 POST 資料的類型 (包含在 data 屬性值中的二進位或字串資料)。
• 若為 FileReference.upload()，要求的 Content-Type 就會自動設定為 multipart/form-data，而且會忽略 contentType 屬性的值。

在 Flash Player 10 和更新版本中，如果您使用包含上載 (由 POST 主體中 "content-disposition" 檔頭的 "filename" 參數指示) 的多部分 Content-Type (例如 "multipart/form-data")，POST 作業會受限於上載所套用的安全性規則：

• 必須執行 POST 作業，以回應使用者啟動的動作 (例如按下滑鼠或按下按鍵)。
• 如果 POST 作業會跨越網域 (POST 目標與傳送 POST 要求的 SWF 檔不在同一部伺服器上)，目標伺服器必須提供允許跨網域存取的 URL 原則。

此外，多部分的 Content-Type 語法必須有效 (符合 RFC2046 標準)。如果語法無效，POST 作業會受限於上載所套用的安全性規則。

相關 API 元素

物件，其中包含要使用 URL 要求傳輸的資料。

這個屬性會與 method 屬性搭配使用。當 method 的值為 GET 時，data 的值會附加至 URLRequest.url (使用 HTTP 查詢字串語法) 的值。當 method 值為 POST (或是 GET 以外的任何值)，data 的值就會在 HTTP 要求主體中傳輸。

URLRequest API 會提供二進位 POST 支援和 URL 編碼變數的支援，以及字串的支援。 資料物件可以為 ByteArray、URLVariables 或 String 物件。

資料的使用方式會視使用的物件類型而定：

• 如果該物件為 ByteArray 物件，則 ByteArray 物件的二進位資料就會當作 POST 資料使用。 若為 GET，則不支援 ByteArray 類型的資料。 此外，FileReference.upload() 和 FileReference.download() 不支援 ByteArray 類型的資料。
• 如果物件為 URLVariables 物件，而且方法是 POST，就會使用 x-www-form-urlencoded 格式來編碼變數，而且產生的字串會當作 POST 資料使用。 FileReference.upload() 的呼叫則例外，因為變數會當作 multipart/form-data 張貼中的個別欄位傳送。
• 如果物件為 URLVariables 物件，而且方法是 GET，則 URLVariables 物件就會定義要使用 URLRequest 物件傳送的變數。
• 否則，物件會轉換成字串，而且字串會當作 POST 或 GET 資料使用。

此資料會等到方法 (例如 navigateToURL() 或 FileReference.upload()) 使用 URLRequest 物件時才會傳送。

注意：contentType 的值必須對應於 data 屬性中的資料類型。請參閱 contentType 屬性說明中的備註。

相關 API 元素

package {
    import flash.display.Sprite;
    import flash.net.navigateToURL;
    import flash.net.URLRequest;
    import flash.net.URLVariables;

    public class URLVariablesExample extends Sprite {

        public function URLVariablesExample() {
            var url:String = "http://www.[yourDomain].com/application.jsp";
            var request:URLRequest = new URLRequest(url);
            var variables:URLVariables = new URLVariables();
            variables.exampleSessionId = new Date().getTime();
            variables.exampleUserLabel = "guest";
            request.data = variables;
            navigateToURL(request);
        }
    }
}

字串，唯一識別儲存到 Flash Player 快取 (或從中擷取) 的已簽署 Adobe 平台組件。Adobe 平台組件是已簽署的檔案 (SWZ 檔)，內含持續快取在使用者電腦上的 SWF 內容。所有 SWZ 檔都由 Adobe 簽署。摘要與單一快取檔相對應，如果您以任何方式變更檔案，它的摘要會發生無法預期的變化。藉由使用摘要，您可以跨多個網域驗證快取檔。具有相同摘要的兩個檔案是相同的檔案，具有不同摘要的兩個檔案並非相同的檔案。實際情況中，您無法建立檔案進行窺控並偽裝成另一個摘要。

摘要是以 SHA-256 訊息摘要演算法 (採用十六進位格式的 64 個字元長度) 為基礎。

例如，Flex SDK 包含適用於 Flex 架構的 SWZ (而且它會為該 SWZ 檔提供摘要字串)。您可以將這個 SWZ 張貼到您的網站伺服器，並將它載入您的 SWF 檔 (使用 URLLoader 物件的 load() 方法)。如果一般使用者的電腦上已經快取相符的 SWZ 檔，應用程式會使用快取的 SWZ 檔 (SWZ 檔的 digest 符合您提供的摘要，即表示相符)。否則應用程式會從您指定的 URL 下載 SWZ 檔。

只有呼叫 URLLoader.load() 方法以載入 SWZ 檔時，才要設定 URLRequest 物件中的 digest 參數。如果在其它方法中使用 URLRequest 物件時設定它的 digest 屬性，應用程式會擲出 IOError 例外。

 
var myURLReq:URLRequest = new URLRequest();
myURLReq.url = "http://yourdomain/users/jdoe/test01/_rsc/Automated/AssetCaching_rsc/test01/rsl.swz";
myURLReq.digest = "3B0AA28C7A990385E044D80F5637FB036317BB41E044D80F5637FB036317BB41";
var myURLLoader:URLLoader = new URLLoader();
myURLLoader.dataFormat = URLLoaderDataFormat.BINARY;
myURLLoader.addEventListener("complete", onC);

myURLLoad.load(myURLReq);

function onC(e) {
    var someLoader:Loader = new Loader();
    addChild(someLoader);
    someLoader.loadBytes((ByteArray)(myURLLoad.data)); 
}

指定是 (true) 否 (false) 要追蹤重新導向。

注意：FileReference.upload()、FileReference.download() 和 HTMLLoader.load() 方法不支援 URLRequest.followRedirects 屬性。

預設值為 true。

相關 API 元素

指定這個要求的閒置逾時值 (以毫秒為單位)。

閒置逾時是指當建立連線後，在放棄要求之前，用戶端等候伺服器回應的時間 (毫秒)。

注意：HTMLLoader.load() 方法不支援 URLRequest.idleTimeout 屬性。HTMLLoader 類別定義自己的 idleTimeout 屬性。

預設值為 initialized from the URLRequestDefaults.idleTimeout property。

相關 API 元素

指定 HTTP 通訊協定堆疊是否應管理這個要求的 Cookie。如果為 true，則 Cookie 會加入要求而且會記住回應 Cookie。如果為 false，則 Cookie 不會加入要求而且不會記住回應 Cookie，但使用者可以藉由直接標頭操作自行管理 Cookie。注意：在 Windows 中，當 manageCookies 設定為 true 時，無法將 Cookie 手動新增至 URL 要求。在其他作業系統中，不論 manageCookies 設定為 true 或 false，都允許將 Cookie 新增至要求。當允許時，您可以將包含 Cookie 資料的 URLRequestHeader 物件新增至 requestHeaders 陣列，以便將 Cookie 手動新增至要求。

在 Mac OS 上，與 Safari 共享 Cookie。若要在 Mac OS 上清除 Cookie：

1. 開啟 Safari。
2. 選取「Safari > 偏好設定」，再按一下「安全性」面板。
3. 按一下「顯示 Cookie」按鈕。
4. 按一下「全部移除」按鈕。

若要在 Windows 上清除 Cookie：

1. 開啟「網際網路內容」控制台，再按一下「一般」索引標籤。
2. 按一下「刪除 Cookie」按鈕。

預設值為 true。

相關 API 元素

控制 HTTP 表單送出方法。

針對 Flash Player 中 (在瀏覽器中) 執行的 SWF 內容，這個屬性僅限於 GET 或 POST 作業，而且有效值為 URLRequestMethod.GET 或 URLRequestMethod.POST。

針對 Adobe AIR 中執行的內容，如果內容位於應用程式安全執行程序中，您可以使用任何字串值。否則，如同 Flash Player 中的執行內容，僅限於使用 GET 或 POST 作業。

針對 Adobe AIR 中執行的內容，當您使用 navigateToURL() 函數時，執行階段會將使用 POST 方法的 URLRequest (其 method 屬性設為 URLRequestMethod.POST 者) 視同使用 GET 方法的物件。

注意：如果在 Flash Player 中執行且參考的表單不含主體時，即使方法已設為 URLRequestMethod.POST，Flash Player 還是會自動使用 GET 作業。因此，建議您務必包含「虛擬」主體，以便確保使用正確的 method。

預設值為 URLRequestMethod.GET。

相關 API 元素

package {
    import flash.display.Sprite;
    import flash.net.navigateToURL;
    import flash.net.URLRequest;
    import flash.net.URLRequestMethod;
    import flash.net.URLVariables;

    public class URLRequest_method extends Sprite {

        public function URLRequest_method() {
            var url:String = "http://www.[yourDomain].com/application.jsp";
            var request:URLRequest = new URLRequest(url);
            
            var variables:URLVariables = new URLVariables();
            variables.exampleSessionId = new Date().getTime();
            variables.exampleUserLabel = "guest";
            request.data = variables;
            request.method = URLRequestMethod.POST;
            
            navigateToURL(request);
        }
    }
}

要附加至 HTTP 要求之該 HTTP 要求檔頭的陣列。 此陣列是由 URLRequestHeader 物件所構成。 陣列中的每個物件必須是 URLRequestHeader 物件，其中包含名稱字串和值字串，如下所示：

     var rhArray:Array = new Array(new URLRequestHeader("Content-Type", "text/html"));
     

Flash Player 和 AIR 執行階段會對要求檔頭施加某些限制；如需詳細資訊，請參閱 URLRequestHeader 類別說明。

並非所有接受 URLRequest 參數的方法都會支援 requestHeaders 屬性；請參閱您要呼叫之方法的文件。例如，FileReference.upload() 和 FileReference.download() 方法不支援 URLRequest.requestHeaders 屬性。

由於瀏覽器的限制，只有 POST 要求會支援自訂 HTTP 要求檔頭，GET 要求並不支援。

相關 API 元素

要求的 URL。

務必對統一資源定位器規格 (請參閱 http://www.faqs.org/rfcs/rfc1738.html) 中描述為不安全的任何字元，或在 URLRequest 物件的 URL 配置中保留的任何字元 (未做為保留用途時) 進行編碼。例如，使用 "%25" 代表百分比 (%) 符號，使用 "%23" 代表數字符號 (#)，如下所示："http://www.example.com/orderForm.cfm?item=%23B-3&discount=50%25"。

根據預設，URL 必須與呼叫的檔案位於相同的網域中，除非內容是在 Adobe AIR 應用程式安全執行程序中執行。若要從不同網域載入資料，請將 URL 原則檔案放在存放資料的伺服器上。如需詳細資訊，請參閱 URLRequest 類別的說明。

針對 Adobe AIR 中執行的內容，應用程式安全執行程序中的檔案 (使用 AIR 應用程式所安裝的檔案) 可以存取使用下列任何 URL 配置的 URL：

• http 和 https
• file
• app-storage
• app

注意：AIR 和 Flash Player 9.0.115.0 和更新版本支援 IPv6 (網際網路通訊協定第 6 版)。IPv6 為「網際網路通訊協定」的其中一個版本，可支援 128 位元的位址 (與先前僅支援 32 位元的 IPv4 通訊協定相較之下，此為一大革新)。 您可能必須啟動您的網路介面上的 IPv6。 如需詳細資訊，請參閱存放資料之作業系統的「說明」。 如果主機系統上支援 IPv6，您可以在 URL 中指定數字的 IPv6 常值位址，並在前後加上方括弧 ([])。如下所示：

     rtmp://[2001:db8:ccc3:ffff:0:444d:555e:666f]:1935/test
     

var url:String = "http://www.helpexamples.com/flash/images/image2.jpg";
var urlRequest:URLRequest = new URLRequest(url);
var loader:Loader = new Loader();
loader.load(urlRequest);
addChild(loader);

指定這個 URLRequest 取得資料之前是否應查閱本機快取。

注意：HTMLLoader.load() 方法不支援 URLRequest.useCache 屬性。

預設值為 true。

相關 API 元素

指定 HTTP 要求中所要使用的 user-agent 字串。

預設值是 Flash Player 所使用的相同使用者代理程式字串，這個字串在 Mac、Linux 和 Windows 上各不相同。

注意：當 URLRequest 物件與 HTMLLoader 物件的 load() 方法搭配使用時，這個屬性不會影響使用者代理字串。若要設定 HTMLLoader 物件的使用者代理字串，請設定 HTMLLoader 物件的 userAgent 屬性或設定靜態 URLRequestDefaults.userAgent 屬性。

相關 API 元素

會建立 URLRequest 物件。 如果 System.useCodePage 為 true，就會使用系統字碼頁 (而非 Unicode) 來編碼該要求。 如果 System.useCodePage 為 false，就會使用 Unicode (而非系統字碼頁) 來編碼該要求。

相關 API 元素

// Requires
// - Button symbol on Stage (or a display object, such as a MovieClip) with instance name "buttonSymbol"
//
buttonSymbol.addEventListener(MouseEvent.CLICK, buttonSymbol_click);
 
function buttonSymbol_click(evt:MouseEvent):void {
    var req:URLRequest = new URLRequest("http://www.adobe.com/");
    navigateToURL(req, "_blank");
}

允許以來源 URLRequest 中的重新導向 URL 替代新 URLRequest 中 URL 的某些部分。重新導向初始要求之後，這讓後續要求可以直接傳送到重新導向的伺服器位置。

完成初始 URLRequest 之後，如果 HTTPStatusEvent.redirected 為 true，則可以使用初始要求呼叫這個方法做為 sourceRequest。根據預設，重新導向的 URL 中的網域將用來取代這個 URLRequest 的 URL 中的網域。在呼叫這個方法之前，必須先設定 URLRequest.url。載入這個 URLRequest 之前，則必須先呼叫方法。或者，如果 wholeURL 參數為 true，則來源 URLRequest 的整個 URL (不含檔案名稱) 將會取代這個 URLRequest 中的整個 URL (不含最終檔案名稱)。此外，呼叫者可以選擇在 pattern 參數中提供字串或規則運算式。模式會經過搜尋並取代為 replace 參數中的字串。這個搜尋和取代會在 URL 替代之後進行。

參數

相關 API 元素

若要執行此範例，請將名為 XMLFile.xml 的檔案與 SWF 檔放置於相同的目錄中。

package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.*;

    public class URLRequestExample extends Sprite {
        private var loader:URLLoader;
        
        public function URLRequestExample() {
            loader = new URLLoader();
            configureListeners(loader);

            var request:URLRequest = new URLRequest("XMLFile.xml");
            try {
                loader.load(request);
            } catch (error:Error) {
                trace("Unable to load requested document.");
            }
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
        }

        private function completeHandler(event:Event):void {
            var loader:URLLoader = URLLoader(event.target);
            trace("completeHandler: " + loader.data);
        }

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            trace("progressHandler loaded:" + event.bytesLoaded + " total: " + event.bytesTotal);
        }

        private function securityErrorHandler(event:SecurityErrorEvent):void {
            trace("securityErrorHandler: " + event);
        }

        private function httpStatusHandler(event:HTTPStatusEvent):void {
            trace("httpStatusHandler: " + event);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }
    }
}