How to program in Grimport?

Ask us for help with programming in Grimport TRANSLATE THIS PAGE

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">/)

regex contient deux autres arguments. Le second est pour indiquer le code sur lequel est exécuté l’expression régulière, un peu comme le second argument de select. Le troisième permet d’indiquer le numéro du masque.

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 &eacute; 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")+"mon_csv_sur_le_bureau.csv",  [
          "Titre du produit" : titre,
          "Prix  du produit" : prix,
        ])

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)
qui fonctionne de manière semblable, en indiquant les rangées, colonnes et feuillets. Pour la colonne A, la rangée 1 ou le premier feuillet, indiquez la valeur 0.

La fonction

write(string path, string  text)
permet de construire un fichier avec le contenu souhaité. Utilisez writeEnd pour écrire à la suite d’un fichier existant.

 

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")+"mon_csv_temporaire.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.

nom_produit = cleanSelect("h1")  //on extrait le titre du produit
prix_produit =  cleanSelect(".priceVAT",null,null,"price") //on  extrait le prix qui est dans une balise de classe « priceVAT ». Le  dernier argument extrait le prix et nettoie la donnée à la manière  de htmlToPrice
image_produit =  cleanSelect("img.main",null,"src") //on extrait  l’image depuis l’attribut src de la balise

//commençons à insérer les données  extraites
function("add_product" ,  [nom_produit,prix_produit] )  //on crée un produit avec un nom et un  prix. Attention à ce stade rien n’est créé ! Cette commande  est simplement placée en attente dans une pile et ne sera envoyée  que lors de l’appel de send()
function("add_image" ,  [image_produit] )  //création de l’image. Notez qu’on ne  reprécise pas l’identifiant du produit précédemment créé, le  Grimport mémorisera ce produit et il sera implicitement indiqué à  cette fonction
send() // les commandes sont enfin  envoyé et le produit est créé avec une image associée

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 :

prix_produit =  cleanSelect(".priceVAT",null,null,"price")   //extraction du prix

existence_produit =  functionNow("id_product_reference",[ reference_produit ])  //existance_produit sera à false si le produit n’existe pas et  contient l’id du produit sinon
if(existence_produit)  prix_produit=null //le prix ne sera pas mis à jour si le produit est  déjà dans la base
function("add_or_update_product",  [titre_produit,prix_produit,reference_produit] )
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.