Les principales fonctions du Grimport
L’extraction des données
Il existe 2 méthodes principales pour l’extraction des données depuis un code source : les expressions réguières et l’extraction par selecteur CSS.
1) L’extraction par sélecteur CSS
Chaque élement d’une page Internet est immatriculé par un ou plusieurs sélecteur CSS unique. Pour trouver un sélecteur CSS, une méthode pratique est d’ouvrir sous Chrome ou Firefox l’explorateur DOM (sur Chrome clic droit > Inspecter, sous Firefox clic droit > Copier > Sélecteur CSS). Ce tutoriel vous donnera les principales.
Un sélecteur CSS se forme selon la nomenlature suivante :
Afin d’extraire l’information propre à un sélecteur CSS, nous utilisons la fonction select (alias de selectInCode).
select(cssSelector, _code, _selection)Les arguments commençant pas _ sont facultatifs.
Le premier paramètre est celui du selecteur CSS. Le second correspond au code dans lequel la recherche sera faite, si l’argument n’existe pas ou est à null, alors le code source entier de la page en cours de crawling sera utilisé. Le dernier argument est appelé selection. En effet, si le sélecteur CSS indique quel élément est désigné, il ne mentionne pas ce qui doit être extrait. Voici les valeurs possibles pour selection :
• innerHTML ou html (par défaut) = le code HTML à l’interieur de la balise
• outerHTML = le code HTML à l’extérieur de la balise, autrement dit, l’interieur de la balise + la balise de début et de fin
• text = le texte de l’élement (on ignore par exemple les élements HTML à l’intérieur tels que les images)
• object = retourne l’objet Jsoup Element de l’élement DOM
• Si une autre valeur est indiquée, alors c’est la valeur de l’attribut de la balise qui sera retourné. Par exemple, indiquer « href » sur un lien (balise a) retournera l’URL du lien hypertexte. Autrement dit, select("a","<a href="http://site.com/page">Mon Lien</a>","href") retournera "http://site.com/page"
Il existe deux types de fonctions qui permettent l’extraction par sélecteur CSS. select retourne le contenu du premier selecteur trouvé.
Vous pouvez aussi utiliser selectAll, qui ira trouver tous les élements correspondant au sélecteur. Par exemple sur :
<ul>
<li>Element 1</li>
<li>Element 2</li>
<li>Element 3</li>
</ul>selectAll("li")va retourné le tableau suivant : ["Element 1","Element 2","Element 3"]
2) L’extraction par expression régulière
Les expressions régulières sont un outil puissant pour faire de la recherche dans un texte. Afin de vous premettre de construire vos expressions réulières, nous mettons à disposition ce tutoriel.
Pour rechercher avec une expression régulière dans du code source, on utilise la fonction regex. L’expression régulière doit contenir un masque qui identifiera l’élement à retourner. Les masques sont indiqués par des parenthèses. Pour avoir le numéro du masque, comptez les parenthèses ouvrantes depuis le début. Par exemple, dans ((http)|(ht(tp)s))://, le masque 4 retourne « tp » et les masque 2 et 3 peuvent ne pas exister en fonction des situations.
On indique également souvent des flags en début d’expression régulières. Il est conseillé d’utiliser dans la plupart des cas le groupe (?si) pour indiquer un contexte insensible à la casse et multiligne. Voici les principaux flags existants :
Ainsi une expression régulière classique s’écrira comme il suit :
regex(/(?si)<a href="([^<>"]+)" class="link">/)regexAll fonctionne comme selectAll pour les expréssions régulières.
Le nettoyage des données
Plusieurs fonctions permettent de nettoyer la donnée afin de la standardiser. Voici les principales :
standardizeText(html) permet de corriger un grand nombre de problèmes comme les erreurs d’encodage, il convertit les codes HTML comme é en caractère accentué ou encore il remplace certains apostrophes au code Unicode original en ce qu’il y a de plus standard.
stripTags(html) permet d’enlever d’un code tous les tags HTML
number(html) permet d’extraire le nombre d’un code HTML
htmlToPrice(html) permet d’extraire un prix d’un code potentiellement « sale ».
Il existe une classe de fonction combinant des nettoyages classiques avec les fonctions de type select ou regex comme cleanSelect ou cleanRegexAll qui combine un post traitement pour laver la donnée.
L’export de la donnée
Grimport Crawler peut d’exécuter avec un site interfacé ou non. Dans un site interfacé, il est possible d’envoyer des commandes pour créer dans la base du site des entités comme des produits ou des articles sur WordPress ou Prestashop. Vous pouvez aussi extraire les informations en CSV ou Excel.
1) L’export fichier
La fonction CSV permet d’exporter les données dans un tableau. La fonction est très simple d’utilisation, indiquez le nom du fichier, suivit d’un tableau associatif [nom de colonne→valeur de la case]. Exemple, pour écrire un fichier sur le bureau :
csv( path("desktop")+"my_csv_on_the_desktop.csv", [
"Product Title" : name,
"Product Price" : price,
])Pensez à éventuellement supprimer en début de script un éventuel précédent fichier csv (avec delete) afin de ne pas réécrire à la suite de ce qui a été extrait lors d’un précédent crawl.
Pour écrire dans un Excel, vous pouvez utiliser la fonctionne
writeExcel(string path, string valueToInsert, boolean isXLSXformat, int row, int column, int _sheet)La fonction
write(string path, string text)
2) L’export sur serveur distant
Il est possible d’insérer la donnée dans une base MySQL par exemple, utilisez pour cela sqlQuery. Pour les deux premiers arguments aidez-vous du tableau fournit par la documentation de la fonction. Indiquez votre login et votre mot de passe, puis composez votre requête SQL. Aidez-vous de sqlEscape pour échapper les données lors de la construction de votre requête
sqlQuery("com.mysql.jdbc.Driver", "jdbc:mysql://myhostname/databaseName","my login", "my password", "UPDATE my_table SET field="+sqlEscape(fieldToInsert)+" WHERE id=1234")Vous pouvez créer un fichier qui sera importé sur le serveur FTP. Par exemple, utiliser la fonction csv pour créer votre fichier CSV dans le répertoire temporaire (le chemin du fichier serait path("tmp")+"mon_csv_temporaire.csv"). Puis uploadez-le sur un serveur avec la fonction ftpUpload :
ftpUpload("68.258.354.12","admin","sd44f88t4h","/var/www/download/myFile.csv",path("tmp")+"my_temp_csv.csv")
3) L’export avec un site interfacé
Si vous avez installé l’un de nos modules sur un CMS comme Wordpress ou Prestashop, vous pouvez alors utiliser des fonctions dédiés à l’insertion dans ce CMS. Pour cela, il faut bien comprendre la philosophie de Grimport Crawler. Afin d’être économe en ressources, Grimport Crawler mettre vos commandes dans une pile qui ne sera exécutée qu’à la fin du script.
Pour effectuer ces insertions, on utilise la fonction « function » qui permet d’appeler des fonctions en PHP, il peut s’agir de fonctions déjà existante dans PHP nativement ou de fonctions créées dans la bibliothèque du module. Le premier argument est le nom de cette fonction et le second contient un tableau des arguments de la fonction. On peut également utiliser la fonction « php » qui envoit directement du code PHP à exécuter.
Insérons par exemple un produit dans Prestashop avec une image, un nom et un prix.
product_name = cleanSelect("h1") //we extract the title of the product
product_price = cleanSelect(".priceVAT",null,null,"price") //we extract the price which is in a “priceVAT” class tag. The last argument extracts the price and cleans the data like htmlToPrice
product_image = cleanSelect("img.main",null,"src") //we extract the image from the src attribute of the tag
//let's start inserting the extracted data
function("add_product" , [product_name,product_price] ) //we create a product with a name and a price. Be careful at this point, nothing is created! This command is simply put on hold in a stack and will only be sent when send() is called.
function("add_image" , [product_image] ) //creation of the image. Note that we do not re-specify the identifier of the product previously created, the Grimport will memorize this product and it will be implicitly indicated to this function
send() //the commandes are finally sent and the product is created with an associated image Pour voir toutes les fonctions PHP disponibles cliquez sur le bouton PHP en bas du panneau de script, une documentation dynamique les liste en bas de page.
Parfois il est nécessaire de ne pas attendre send() pour lancer une commande à part. On utilisera functionNow ou phpNow pour cela. C’est par exemple utile si on veut savoir si le produit existe avant de mettre à jour un prix. Exemple :
product_price = cleanSelect(".priceVAT",null,null,"price") //price extraction
product_exists = functionNow("id_product_reference",[ product_reference ]) //product_exists will be false if the product does not exist and contains the product id otherwise
if(product_exists) product_price=null //the price will not be updated if the product is already in the database
function("add_or_update_product", [product_name,product_price,product_reference] )
send()L’utilisation de l’EDI de Grimport Crawler
Un EDI est fournit pour favoriser la programmation. Vous trouverez 3 onglets dans la colonne de gauche. Le premier permet de gérer les scripts et d’interagir avec votre site, le second est dédié aux tests et permet de vérifier si le script développé fonctionne sur une page ou si le selecteur CSS ou l’expression régulière est valide sur la page testée. Enfin le dernier onglet est dédié au debuggage et permet d’inspecter les variables lors de la mise en place de points d’arrêt.
Commencez par interfacez votre site avec l’EDI, pour cela vous trouverez un fichier GRS dans la configuration de notre module sur votre CMS, sinon allez dans les scripts locaux. Créez un nouveau script, le panneau central est alors actif. Indiquez la page d’accueil du site cible et donnez un nom au script.
Un script de crawling se compose de 3 sous-scripts, le premier est exécuté avant le crawl, celui propre aux pages s’exécute sur chaque page crawlé et enfin le dernier n’exécute à la toute fin du crawling. Séléctionnez le script sur lequel vous voulez travailler dans la liste déroullante. Un onglet Options permet de modifier le comportement du crawleur, vous pourrez vous identifiez avec un autre user-agent, ne pas dépasser une certaines profondeur de crawling (la page d’accueil est la profondeur 1, les pages ayant un lien sur la page d’accueil ont une profondeur 2, etc.), un délai entre chaque appel de page pour ne pas flooder le site cible ou encore des URL sur lesquels le crawleur ne doit pas aller.
L’écriture d’un script
Pour vous assister dans l’écriture du script vous pouvez accéder aux variables disponibles et aux fonctions Grimport en pressant Ctrl + Espace. Une liste déroulante vous affiche les fonctions avec leurs paramètres ainsi qu’une documentation intégrée expliquant le fonctionnement de chaque fonction.
Survollez une fonction déjà écrite pour afficher à nouveau la documentation.
Pour avoir la documentation HTML des fonctions cliquez sur le bouton en haut à droite « Documentation des fonctions Grimport », vous pouvez y effectuer une recherche rapide. Si vous séléctionnez une fonction au préalable, vous serez redirigé sur la documentation HTML de la fonction.
Tester un script
Vous avez finit d’écrire votre script ? Parfait, mais ne commencez pas par le lancer, car en cas de bug, une erreur serait reproduites sur toutes les données que vous extrairez. Prenez une des pages concernée par le script d’extraction, copiez l’URL et collez-le dans l’onglet Tester. Ensuite lancez le script sur la page. Contrôlez que la console ne retourne pas de message d’erreur et que les données extraites sont conformes à votre cahier des charges.
Vous pouvez y tester des sélecteur CSS et des expressions régulière. N’hésitez pas à mettre des points d’arrêt où vous voulez dans le code, entrez ensuite le nom de la variable pour voir ce qu’elle contient en cours d’exécution. Pour mettre un point d’arrêt, utilisez le bouton ¤. Lorsque vous avez fini votre inspection, cliquez sur le bouton Play pour continuer.
Vous pouvez également ne lancer qu’un bout de code sélectionné avec le 3ième bouton en haut à gauche.
Gestion des scripts et des crawls
Le premier bouton en haut à gauche sert à lancer tous les scripts d’un site les uns à la suite des autres. Le paramètre Ordre dans options permet de définir un ordre dans cette exécution. Le second bouton en haut à gauche ne lance que le script qui est ouvert.
En cours de crawling, il est possible que Grimport Crawleur n’en finisse pas de tourner. Générez les rapports des liens visités et à visiter. Après inspection, vous verrez peut-être des liens indésirables. Excluez-les avec la fonction d’exclusion de lien (F3) en modifiant l’expression régulière des liens à exclure.
Les logs du crawleur sont inscrits dans le dossier C:/Users/VOTRE_UTILISATEUR/Grimport Crawler/analysis logs. Ils contiennent toutes les informations utiles à un debuggage. Si vous souhaitez une assistance d’idIA Tech, vous devez TOUJOURS les joindre à vos emails. Une fonction existe pour nous les envoyer directement.
Il est possible d’ajouter des options à votre crawling grâce au bouton Engrenage. Vous pouvez par exemple accéder aux contenu de chaque requête HTTP dans le logiciel Fiddler4 en ajoutant l’option fiddlerProxy.
Lorsque vous définissez un contexte de crawling, celui-ci est ajouté aux lanceurs du panneau de Lanceurs. Lorsque vous allez dans les options de ce lanceur, vous pouvez récupérer un CRON utilisable sur votre serveur pour automatiser la tâche.
En cas de soucis pour développer un script, n’hésitez pas à nous demander un devis en cliquant sur le bouton en haut à droite.