Chargement de données externes

Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures

ActionScript 3.0 comprend des mécanismes permettant de charger des données depuis des sources externes. Ces sources peuvent fournir un contenu statique, tel que des fichiers texte, ou un contenu dynamique généré par un script Web. Les données peuvent être formatées de plusieurs façons, et ActionScript propose une fonctionnalité permettant de décoder les données et d’y accéder. Vous pouvez également envoyer des données au serveur externe lors de leur récupération.

Utilisation de la classe URLRequest

Un grand nombre d’API qui chargent des données externes font appel à la classe URLRequest pour définir les propriétés de la requête réseau requise.

Propriétés de la classe URLRequest

Vous pouvez définir les propriétés suivantes d’un objet URLRequest dans tout sandbox de sécurité :

Propriété

Description

contentType

Type de contenu MIME des données envoyées avec la requête d’URL. Si contentType n’est pas défini, les valeurs sont envoyées sous la forme application/x-www-form-urlencoded.

data

Objet contenant des données à transmettre avec la demande d’URL.

digest

Chaîne qui identifie de manière unique le composant de la plate-forme Adobe signé à enregistrer dans (ou extraire de) la mémoire cache d’Adobe® Flash® Player.

method

Méthode de requête HTTP, telle que GET ou POST. (Le contenu s’exécutant dans le domaine de sécurité de l’application AIR peut spécifier des chaînes autres que "GET" ou "POST" comme propriété method. Tous les verbes HTTP sont autorisés et "GET" est la méthode par défaut. Voir Sécurité AIR.)

requestHeaders

Tableau d’en-tête de requête HTTP à ajouter à la fin de la requête HTTP. Notez que l’autorisation de définir certains en-têtes est restreinte dans Flash Player, ainsi que dans un contenu AIR qui s’exécute en dehors du sandbox de sécurité d’application.

url

Spécifie l’URL qui fait l’objet de la requête.

AIR permet de définir d’autres propriétés de la classe URLRequest, dont ne dispose que le contenu AIR qui s’exécute dans le sandbox de sécurité d’application. Le contenu du sandbox d’application peut également définir des URL à l’aide des nouveaux modèles d’URL (parallèlement aux modèles standard tels que file et http).

Propriété

Description

followRedirects

Indique si des redirections sont utilisées (true, valeur par défaut) ou non (false). La définition de cette propriété n’est gérée que dans le sandbox d’une application AIR.

manageCookies

Indique si la pile du protocole HTTP doit gérer les cookies (true, valeur par défaut) ou non (false) pour cette requête. La définition de cette propriété n’est gérée que dans le sandbox d’une application AIR.

authenticate

Indique si les requêtes d’authentification doivent être traitées (true) pour cette requête. La définition de cette propriété n’est gérée que dans le sandbox d’une application AIR. Par défaut, les requêtes sont authentifiées ; il est par conséquent possible qu’une boîte de dialogue d’authentification s’affiche si le serveur requiert des informations d’identification. Vous pouvez également définir le nom d’utilisateur et le mot de passe par le biais de la classe URLRequestDefaults (voir Définition des paramètres par défaut des objets URLRequest (AIR uniquement)).

cacheResponse

Indique si les données de réponse doivent être mises en mémoire cache pour cette requête. La définition de cette propriété n’est gérée que dans le sandbox d’une application AIR. Par défaut, la réponse est mise en mémoire cache (true).

useCache

Indique si le cache local doit être consulté avant que la classe URLRequest récupère les données. La définition de cette propriété n’est gérée que dans le sandbox d’une application AIR. Par défaut, le cache local doit être utilisé, s’il est disponible (true).

userAgent

Indique la chaîne agent utilisateur à utiliser dans la requête HTTP.

Remarque : la classe HTMLLoader possède des propriétés associées pour les paramètres associés au contenu chargé par un objet HTMLLoader. Pour plus d’informations, voir A propos de la classe HTMLLoader.

Définition des paramètres par défaut des objets URLRequest (AIR uniquement)

La classe URLRequestDefaults permet de définir les paramètres par défaut propres à une application des objets URLRequest. Par exemple, le code suivant définit les valeurs par défaut des propriétés manageCookies et useCache. Tous les nouveaux objets URLRequest utiliseront les valeurs spécifiées de ces propriétés au lieu des valeurs par défaut standard :

URLRequestDefaults.manageCookies = false; 
URLRequestDefaults.useCache = false;
Remarque : la classe URLRequestDefaults est réservée au contenu qui s’exécute dans Adobe AIR. Elle n’est pas prise en charge dans Flash Player.

La classe URLRequestDefaults inclut une méthode setLoginCredentialsForHost() qui vous permet de spécifier un nom d’utilisateur et un mot de passe par défaut pour un hôte spécifique. L’hôte, défini dans le paramètre hostname de la méthode, peut être un domaine, tel que "www.example.com", ou un domaine et un numéro de port, par exemple "www.example.com:80". Notez que "example.com", "www.example.com" et "sales.example.com" sont considérés comme hôtes uniques.

Ces informations d’identification ne sont utilisées que lorsque le serveur les demande. Si l’utilisateur s’est déjà authentifié (à l’aide de la boîte de dialogue d’authentification, par exemple), appeler la méthode setLoginCredentialsForHost() ne modifie pas l’utilisateur authentifié.

Le code suivant permet de définir le nom d’utilisateur et le mot de passe par défaut à utiliser pour les requêtes envoyées à www.example.com :

URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X"); 

Les paramètres URLRequestDefaults ne s’appliquent qu’au domaine d’application actuel, à une exception près. Les informations d’identification transmises à la méthode setLoginCredentialsForHost() sont utilisées pour les requêtes effectuées dans tout domaine de l’application AIR.

Pour plus d’informations, voir la classe URLRequestDefaults dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.

Modèles d’URI

Les modèles d’URI standard, tel le modèle ci-dessous, peuvent être utilisés dans les requêtes effectuées à partir de tout sandbox de sécurité :

http: et https:

A utiliser pour les URL Internet standard (comme elles sont utilisées dans un navigateur Web).

file:

Utilisez file: pour spécifier l’URL d’un fichier qui réside dans le système de fichiers local. Exemple :

file:///c:/AIR Test/test.txt 

Dans AIR, vous disposez également des modèles suivants lorsque vous définissez l’URL d’un contenu s’exécutant dans le sandbox de sécurité de l’application :

app:

Le modèle app: permet de spécifier un chemin relatif au répertoire racine de l’application installée. Par exemple, le chemin suivant pointe vers un sous-répertoire de ressources du répertoire de l’application installée :

app:/resources 

Lorsqu’une application AIR est lancée à l’aide de l’application de débogage du lanceur AIR (ADL), le répertoire d’application correspond à celui qui contient le fichier descripteur d’application.

L’URL (et la propriété url) d’un objet File créé avec File.applicationDirectory fait appel au modèle d’URI app, comme dans l’exemple suivant :

var dir:File = File.applicationDirectory; 
dir = dir.resolvePath("assets"); 
trace(dir.url); // app:/assets 

app-storage:

Le modèle app:storage permet de spécifier un chemin relatif au répertoire de stockage de données de l’application. Pour chaque application installée (et utilisateur), AIR crée un répertoire de stockage d’application unique. Cet emplacement est utile pour stocker des données spécifiques à l’application concernée. Par exemple, le chemin suivant pointe vers le fichier prefs.xml, qui réside dans le sous-répertoire settings du répertoire de stockage de l’application :

app-storage:/settings/prefs.xml 

L’URL (et la propriété url) d’un objet File créé avec File.applicationStorageDirectory utilise le modèle d’URI app-storage, comme suit :

var prefsFile:File = File.applicationStorageDirectory; 
prefsFile = prefsFile.resolvePath("prefs.xml"); 
trace(dir.prefsFile); // app-storage:/prefs.xml 

mailto :

Vous pouvez utiliser le modèle mailto dans les objets URLRequest transmis à la fonction navigateToURL(). Voir Ouverture d’une URL dans une autre application.

Vous pouvez faire appel à un objet URLRequest basé sur l’un de ces modèles d’URI pour définir la requête d’URL d’un certain nombre d’objets, tels qu’un objet FileStream ou Sound. Vous pouvez par ailleurs utiliser ces modèles dans le contenu HTML qui s’exécute dans AIR. Il est ainsi possible d’y faire appel dans l’attribut src d’une balise img.

Néanmoins, vous ne pouvez utiliser ces modèles d’URI spécifiques à AIR (app: et app-storage:) que dans le contenu du sandbox de sécurité de l’application. Pour plus d’informations, voir Sécurité AIR.

Définition des variables URL

Bien qu’il soit possible d’ajouter directement des variables à la chaîne de l’URL, il s’avère souvent plus facile de définir toute variable requise par une requête à l’aide de la classe URLVariables.

Les méthodes permettant d’ajouter des paramètres à un objet URLVariables sont au nombre de trois :

  • Au sein du constructeur URLVariables

  • A l’aide de la méthode URLVariables.decode()

  • Sous forme de propriétés dynamiques de l’objet URLVariables en tant que tel

L’exemple suivant illustre les trois méthodes et indique comment affecter les variables à un objet URLRequest :

var urlVar:URLVariables = new URLVariables( "one=1&two=2" ); 
urlVar.decode("amp=" + encodeURIComponent( "&" ) ); 
urlVar.three = 3; 
urlVar.amp2 = "&&"; 
trace(urlVar.toString()); //amp=%26&amp2=%26%26&one=1&two=2&three=3 
 
var urlRequest:URLRequest = new URLRequest( "http://www.example.com/test.cfm" ); 
urlRequest.data = urlVar;

Lorsque vous définissez des variables au sein du constructeur URLVariables ou à l’aide de la méthode URLVariables.decode(), veillez à coder au format URL les caractères dont la signification est particulière dans une chaîne d’URI. Ainsi, lorsque vous insérez une esperluette dans un nom de paramètre ou une valeur, vous devez la coder de sorte à remplacer & par %26, car l’esperluette fait office de délimiteur de paramètres. Vous disposez à cet effet de la fonction de niveau supérieur encodeURIComponent().

Utilisation de la classe URLLoader

La classe URLLoader permet d’envoyer une requête à un serveur et d’accéder aux informations renvoyées. Vous disposez également de la classe URLLoader pour accéder aux fichiers du système de fichiers local dans les contextes où l’accès aux fichiers locaux est autorisé (le sandbox local avec système de fichiers de Flash Player et le sandbox d’application AIR, par exemple). La classe URLLoader télécharge des données à partir d’une URL sous forme de texte, de données binaires ou de variables codées au format URL. La classe URLLoader distribue des événements tels que complete, httpStatus, ioError, open, progress et securityError.

Le modèle de gestion des événements d’ActionScript 3.0 est sensiblement différent du modèle d’ActionScript 2.0, qui utilisait les gestionnaires d’événement LoadVars.onData, LoadVars.onHTTPStatus et LoadVars.onLoad. Pour plus d’informations sur la gestion des événements en ActionScript 3.0, voir Gestion des événements.

Les données téléchargées ne sont pas disponibles tant que le téléchargement n’est pas terminé. Pour surveiller la progression du téléchargement (nombre d’octets chargés et nombre total d’octets), écoutez la distribution de l’événement progress. Toutefois, si le chargement d’un fichier est rapide, l’événement progress risque de ne pas être distribué. Une fois que le téléchargement d’un fichier est terminé, l’événement complete est distribué. En définissant la propriété dataFormat de la classe URLLoader, vous pouvez recevoir les données sous forme de texte, de données binaires brutes ou d’objet URLVariables.

La méthode URLLoader.load() (et éventuellement le constructeur de la classe URLLoader) gère un seul paramètre, request, qui correspond à un objet URLRequest. Un objet URLRequest contient toutes les informations d’une requête HTTP unique, telles que l’URL cible, la méthode de requête (GET ou POST), d’autres informations d’en-tête et le type MIME.

Pour charger un paquet XML dans un script côté serveur, par exemple, vous pouvez utiliser le code ci-après :

var secondsUTC:Number = new Date().time; 
var dataXML:XML =  
    <clock> 
        <time>{secondsUTC}</time> 
    </clock>; 
var request:URLRequest = new URLRequest("http://www.yourdomain.com/time.cfm"); 
request.contentType = "text/xml"; 
request.data = dataXML.toXMLString(); 
request.method = URLRequestMethod.POST; 
var loader:URLLoader = new URLLoader(); 
loader.load(request); 

L’extrait ci-dessus crée un document XML appelé dataXML, qui contient le paquet XML à envoyer au serveur. L’exemple définit la propriété contentType de l’objet URLRequest sur "text/xml" et affecte le document XML à la propriété data de l’objet URLRequest. Il crée enfin un objet URLLoader et envoie la requête au script distant par le biais de la méthode load().

Utilisation de la classe URLStream

La classe URLStream permet d’accéder aux données en cours de téléchargement au fur et à mesure de leur arrivée. Elle permet également de fermer un flux continu avant la fin du téléchargement. Les données téléchargées sont disponibles au format binaire brut.

Lorsque vous lisez les données issues d’un objet URLStream, faites appel à la propriété bytesAvailable pour déterminer si les données disponibles sont suffisantes avant de les lire. Une exception EOFError est renvoyée si vous essayez de lire des données qui ne sont pas disponibles.

Evénement httpResponseStatus (AIR)

Dans Adobe AIR, la classe URLStream distribue un événement httpResponseStatus en plus de l’événement httpStatus. L’événement httpResponseStatus est envoyé avant toute donnée de réponse. L’événement httpResponseStatus (représenté par la classe HTTPStatusEvent) inclut une propriété responseURL, qui correspond à l’URL que la réponse a renvoyée, et une propriété responseHeaders, qui est un tableau d’objets URLRequestHeader représentant les en-têtes de réponse que la réponse a renvoyés.

Chargement de données à partir de documents externes

Lorsque vous programmez des applications dynamiques, il peut s’avérer utile de charger des données issues de fichiers externes ou de scripts côté serveur. Vous pouvez ainsi programmer des applications dynamiques sans avoir à les modifier ou les recompiler. Par exemple, si vous créez une application « conseil du jour », vous pouvez écrire un script côté serveur qui récupère un conseil au hasard dans une base de données et l’enregistre dans un fichier texte une fois par jour. Votre application peut ensuite charger le contenu du fichier texte statique au lieu d’envoyer une requête à la base de données à chaque fois.

L’extrait de code suivant crée un objet URLRequest et URLLoader, qui charge le contenu d’un fichier texte externe nommé params.txt :

var request:URLRequest = new URLRequest("params.txt"); 
var loader:URLLoader = new URLLoader(); 
loader.load(request);
Par défaut, si vous ne définissez aucune méthode de requête, Flash Player et AIR chargent le contenu à l’aide de la méthode HTTP GET. Pour envoyer la requête avec la méthode POST, définissez la propriété request.method sur POST à l’aide de la constante statique URLRequestMethod.POST, comme l’illustre le code suivant :
var request:URLRequest = new URLRequest("sendfeedback.cfm"); 
request.method = URLRequestMethod.POST;

Le document externe, params.txt, chargé au moment de l’exécution, contient les données suivantes :

monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

Le fichier contient deux paramètres, monthNames et dayNames. Chacun des paramètres contient une liste séparée par des virgules qui est analysée sous forme de chaîne. Vous pouvez transformer cette liste en tableau à l’aide de la méthode String.split().

Evitez d’utiliser des mots réservés ou des éléments de langage comme noms de variables dans les fichiers de données externes, car cela complique la lecture et le débogage du code.
Une fois les données chargées, l’événement complete est distribué et le contenu du document externe peut alors être utilisé dans la propriété data de URLLoader, comme l’illustre le code suivant :
function completeHandler(event) 
{ 
    var loader2 = event.target; 
    air.trace(loader2.data); 
}

Si le document distant contient des paires nom-valeur, vous pouvez analyser les données à l’aide de la classe URLVariables en transmettant le contenu du fichier chargé, comme suit :

private function completeHandler(event:Event):void 
{ 
    var loader2:URLLoader = URLLoader(event.target); 
    var variables:URLVariables = new URLVariables(loader2.data); 
    trace(variables.dayNames); 
}

Chaque paire nom-valeur issue du fichier externe devient une nouvelle propriété de l’objet URLVariables. Chaque propriété de cet objet dans l’exemple de code précédent est traité comme une chaîne. Si la valeur de la paire nom-valeur est une liste d’éléments, vous pouvez convertir la chaîne en tableau en appelant la méthode String.split(), comme suit :

var dayNameArray:Array = variables.dayNames.split(",");
Si vous chargez des données numériques à partir de fichiers externes, convertissez-les en valeurs numériques à l’aide d’une fonction de niveau supérieur, telle que int(), uint() ou Number().

Au lieu de charger le contenu du fichier distant sous forme de chaîne et de créer un objet URLVariables, vous pouvez attribuer à la propriété URLLoader.dataFormat la valeur de l’une des propriétés statiques de la classe URLLoaderDataFormat. Les trois valeurs possibles de la propriété URLLoader.dataFormat sont les suivantes :

  • URLLoaderDataFormat.BINARY : la propriété URLLoader.data contient des données binaires stockées dans un objet ByteArray.

  • URLLoaderDataFormat.TEXT : la propriété URLLoader.data contient du texte sous forme d’objet String.

  • URLLoaderDataFormat.VARIABLES : la propriété URLLoader.data contient des variables encodées au format URL issues d’un objet URLVariables.

Le code suivant montre comment vous pouvez automatiquement analyser les données chargées dans un objet URLVariables en attribuant à la propriété URLLoader.dataFormat la valeur URLLoaderDataFormat.VARIABLES.

package 
{ 
    import flash.display.Sprite; 
    import flash.events.*; 
    import flash.net.URLLoader; 
    import flash.net.URLLoaderDataFormat; 
    import flash.net.URLRequest; 
 
    public class URLLoaderDataFormatExample extends Sprite 
    { 
        public function URLLoaderDataFormatExample() 
        { 
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt"); 
            var variables:URLLoader = new URLLoader(); 
            variables.dataFormat = URLLoaderDataFormat.VARIABLES; 
            variables.addEventListener(Event.COMPLETE, completeHandler); 
            try 
            { 
                variables.load(request); 
            }  
            catch (error:Error) 
            { 
                trace("Unable to load URL: " + error); 
            } 
        } 
        private function completeHandler(event:Event):void 
        { 
        var loader:URLLoader = URLLoader(event.target); 
        trace(loader.data.dayNames); 
        } 
    } 
}
Remarque : la valeur par défaut de URLLoader.dataFormat est URLLoaderDataFormat.TEXT.

Comme le montre l’exemple suivant, le chargement de données XML à partir d’un fichier externe s’effectue comme le chargement de données URLVariables. Vous pouvez créer une occurrence d’URLRequest et une occurrence d’URLLoader et vous en servir pour télécharger un document XML distant. Lorsque le fichier est complètement téléchargé, l’événement Event.COMPLETE est distribué et le contenu du fichier externe est converti en occurrence de XML, que vous pouvez analyser avec les méthodes et propriétés XML.

package 
{ 
    import flash.display.Sprite; 
    import flash.errors.*; 
    import flash.events.*; 
    import flash.net.URLLoader; 
    import flash.net.URLRequest; 
 
    public class ExternalDocs extends Sprite 
    { 
        public function ExternalDocs() 
        { 
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml"); 
            var loader:URLLoader = new URLLoader(); 
            loader.addEventListener(Event.COMPLETE, completeHandler); 
            try 
            { 
                loader.load(request); 
            } 
            catch (error:ArgumentError) 
            { 
                trace("An ArgumentError has occurred."); 
            } 
            catch (error:SecurityError) 
            { 
                trace("A SecurityError has occurred."); 
            } 
        } 
        private function completeHandler(event:Event):void 
        { 
            var dataXML:XML = XML(event.target.data); 
            trace(dataXML.toXMLString()); 
        } 
    } 
}

Communication avec des scripts externes

Outre le chargement de fichiers de données externes, la classe URLVariables permet d’envoyer des variables à un script côté serveur et de traiter la réponse du serveur. Cela s’avère utile, par exemple, si vous programmez un jeu et souhaitez envoyer le score de l’utilisateur à un serveur afin de vérifier s’il faut l’ajouter à la liste des scores les plus élevés ; ou encore envoyer les informations de connexion de l’utilisateur au serveur pour validation. Un script côté serveur peut traiter le nom d’utilisateur et le mot de passe, les comparer à une base de données et confirmer en retour la validité des informations fournies par l’utilisateur.

L’extrait de code ci-après crée un objet URLVariables nommé variables, qui génère une nouvelle variable appelée name. Ensuite, un objet URLRequest est créé pour spécifier l’URL du script côté serveur à laquelle doivent être envoyées les variables. Vous pouvez alors définir la propriété method de l’objet URLRequest pour envoyer les variables sous forme de requête HTTP POST . Pour ajouter l’objet URLVariables à la requête URL, définissez la propriété data de l’objet URLRequest sur l’objet URLVariables créé plus tôt. Enfin, l’occurrence de URLLoader est créée et la méthode URLLoader.load() appelée ; cette dernière lance la requête.

var variables:URLVariables = new URLVariables("name=Franklin"); 
var request:URLRequest = new URLRequest(); 
request.url = "http://www.[yourdomain].com/greeting.cfm"; 
request.method = URLRequestMethod.POST; 
request.data = variables; 
var loader:URLLoader = new URLLoader(); 
loader.dataFormat = URLLoaderDataFormat.VARIABLES; 
loader.addEventListener(Event.COMPLETE, completeHandler); 
try 
{ 
    loader.load(request); 
} 
catch (error:Error) 
{ 
    trace("Unable to load URL"); 
} 
 
function completeHandler(event:Event):void 
{ 
    trace(event.target.data.welcomeMessage); 
}

Le code suivant reprend le contenu du document Adobe ColdFusion® greeting.cfm utilisé dans l’exemple précédent :

<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0> 
    <cfset Form.Name = "Stranger" /> 
</cfif> 
<cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)# 
</cfoutput>