Différences

Ci-dessous, les différences entre deux révisions de la page.

--- blocks:usestats:technique:mnet [2026/01/13 08:19] – créée - modification externe 127.0.0.1
+++ blocks:usestats:technique:mnet [2026/10/18 00:15] (Version actuelle) – admin
@@ Ligne 1: / Ligne 1: @@
 <html><!-- nomoodle --></html>{{ :blocks:logo-apl.png?nolink |}}<html><!-- /nomoodle --></html>
-===== Bloc Use Stats (Mesure d'activité) :Services et fonctions MNET =====
+===== Bloc Use Stats (Mesure d'activité) : Services web et fonctions MNET =====
-Le bloc Use Stats fournit deux fonctions d'extraction de résultats liés à l'utilisateur. Le format de sorte dans les deux cas est un fichier XML. Ces fonctions permettent de collecter localement les statistiques de temps de score sur les cours suivis par l'utilisateur. Elles peuvent également être utilisées pour récupérer les scores déportés d'un utilisateur sur un autre Moodle connecté par le réseau MNET (collecte distribuée).
+Le bloc Use Stats expose ses résultats de deux façons :
-==== Services MNET ====
+  * par des **web services Moodle** (trois fonctions, version PRO), qui retournent des structures de données standard de Moodle ;
+  * par un **service MNET** (deux fonctions RPC), qui permet de collecter les statistiques d'un utilisateur déporté sur un autre Moodle connecté par le réseau MNET (collecte distribuée).
-Service : Accès distant aux statiques d'usage.
+==== Web services (PRO) ====
-==== Fonctions RPC ====
+Les trois fonctions sont enregistrées dans le service externe de Moodle et demandent la capacité ''block/use_stats:export'' (voir [[:blocks:usestats:technique:capabilities|Capacités]]). Elles ne sont disponibles que dans la distribution **PRO** : en version communautaire, l'appel retourne l'erreur //WS Not available in this distribution//.
-=== use_stats_rpc_get_stats ===
+=== Fonction : block_use_stats_get_user_stats(uidsource, uid, cidsource, cid, from, to, score) ===
-Récupère les temps de connexion agrégés dans les différents cours, modules d'activité ou le temps global.
+**Synopsis :** récupère les statistiques de temps d'un utilisateur.
-== Paramètres ==
+**Paramètres**
-   * callinguser : L'identité de l'utilisateur appelant
+   * **uidsource :** source de l'identifiant d'utilisateur : ''id'', ''idnumber'', ''username'' ou ''email''.
-   * targetuser :  L'identité de l'utilisateur objet de la demande
+   * **uid :** identifiant utilisateur correspondant.
-   * whereroot : L'hôte sur lequel les résultats sont demandés. Si vide, examine les résultats sur le Moodle courant.
+   * **cidsource :** source de l'identifiant de cours : ''id'', ''idnumber'' (par défaut) ou ''shortname''.
-   * statsscope : La portée des statistiques (le niveau d'agrégation)
+   * **cid :** identifiant de cours correspondant. S'il n'est pas donné ou vaut 0, les statistiques portent sur l'ensemble des cours de l'utilisateur sur la période.
-   * timefrom : Date de début de la compilation
+   * **from :** timestamp Unix de début de la période. Si 0, la totalité de la trace est calculée.
-   * json_response : le format de la réponse
+   * **to :** timestamp Unix de fin de la période. Si non fourni ou 0, la période se termine à l'instant courant.
+   * **score :** si 1 (valeur par défaut), la réponse contient la note finale de chaque cours (''-'' quand il n'y a pas de note).
-== Sortie ==
+**Sortie**
-Un fichier XML répondant à la structure :
+Une structure composite de 4 éléments :
-   <USE_STATS>
+   * **user :** références de l'utilisateur (id, idnumber, username)
-      <USER>
+   * **query :** rappel de la période d'extraction (from, to)
-         <USERNAME></USERNAME>
+   * **sessions :** statistiques sur les sessions (nombre, première et dernière session, durées minimale, maximale et moyenne)
-         <FIRSTNAME></FIRSTNAME>
+   * **courses :** statistiques cours par cours (id, idnumber, shortname, fullname, ''activitytime'', ''coursetime'', ''coursetotal'', ''othertime'', ''sitecoursetime'', ''score'')
-         <LASTNAME></LASTNAME>
-         <FROM></FROM>
-         <ELAPSED></ELAPSED>
-      </USER>
-      <COURSES>
-         <COURSE>
-            <NAME></NAME>
-            <SHORTNAME></SHORTNAME>
-            <IDNUMBER></IDNUMBER>
-            <ELAPSED></ELAPSED>
-         </COURSE>
-      </COURSES>
-   </USE_STATS>
-ou
-   <USE_STATS>
+Dans ''courses'' : ''activitytime'' est le temps passé dans les activités, ''coursetime'' le temps passé dans le cours hors activités, ''coursetotal'' le temps total dans le cours, ''othertime'' le temps passé hors de tout cours (zones système) et ''sitecoursetime'' le temps passé dans la page d'accueil du site pendant les sessions. Tous les temps sont en secondes.
-      <USER>
-         <USERNAME></USERNAME>
-         <FIRSTNAME></FIRSTNAME>
-         <LASTNAME></LASTNAME>
-         <FROM></FROM>
-         <ELAPSED></ELAPSED>
-      </USER>
-      <MODULES>
-         <MODULE>
-            <NAME></NAME>
-            <TYPE></TYPE>
-            <IDNUMBER></IDNUMBER>
-            <ELAPSED></ELAPSED>
-         </MODULE>
-      </MODULES>
-   </USE_STATS>
-suivant la valeur du paramètre "statsscope".
+**Exemple de structure de sortie**
-=== use_stats_rpc_get_scores ===
+<code>
+StdObject {
+   [user] => stdClass Object
+       (
+           [id] => 687
+           [idnumber] => ID93465
+           [username] => john.doe
+       )
-Cette fonction est un add-on pour récupérer les scores (notes) à partir du même service et sous un format et une méthode similaire à la collecte des statistiques.
+   [query] => stdClass Object
+       (
+           [from] => 0
+           [to] => 1497089144
+       )
-{...a terminer...}
+   [sessions] => stdClass Object
+       (
+           [sessions] => 232
+           [firstsession] => 1466104903
+           [lastsession] => 1497085452
+           [sessionmin] => 0
+           [sessionmax] => 22265
+           [meansession] => 2421
+       )
-==== Web Services ====
+   [courses] => Array
+       (
+           [0] => stdClass Object
+               (
+                   [id] => 2
+                   [idnumber] => TESTMODS
+                   [shortname] => TEST_MODULES
+                   [fullname] => Test modules
+                   [activitytime] => 70240
+                   [coursetime] => 92611
+                   [coursetotal] => 164929
+                   [othertime] => 0
+                   [sitecoursetime] => 7855
+               )
-A compter de la version 2017090600, les statistiques peuvent être récupérées par Web Services Moodle :
+       )
+}
+</code>
-=== Fonction : block_use_stats_get_user_stats(uidsource, uid, cidsource, cid, from, to, score) ===
+=== Fonction : block_use_stats_get_users_stats(uidsource, uids, cidsource, cid, from, to, score) ===
-**Synopsis :** Récupère les données de statistiques de temps pour un utilisateur.
+**Synopsis :** similaire à la précédente, mais retourne un tableau de structures de réponse, une par utilisateur de la liste fournie.
-==Paramètres==
+**Paramètres :** ceux de la fonction précédente, sauf **uids** qui remplace ''uid'' et doit contenir un tableau d'identifiants compatibles avec ''uidsource''.
-   * **uidsource :** La source de l'identifiant d'utilisateur (peut être 'id', 'idnumber', 'username' ou 'email')
+**Sortie :** un tableau de structures identiques à la sortie de ''get_user_stats''.
-   * **uid :** L'identifiant utilisateur correspondant.
-   * **cidsource :** La source d'idrntifiant de cours (peut être 'id', 'idnumber' ou 'shortname')
-   * **cid :** L'identifiant de cours correspondant. Si il n'est pas donné ou vaut 0 alors les statistiques sont calculées sur la totalité de l'usage de l'utilisateur dans tous les cours sur la période de référence.
-   * **from :** Timestmap unix de début de période d'extraction. Si mis à 0, la totalité de la trace est calculée.
-   * **to :** timestamp unix de fin de période d'extraction. Si non fourni, ou mis à 0, calclera jusqu'à la date actuelle.
-   * **score :** Si mis à 1, les structures de réponse contiendront la note de cours pour chaque cours.
-==Sortie==
+=== Fonction : block_use_stats_get_users_course_stats(uidsource, uids, cidsource, cid, from, to, score) ===
-Une structure composite de données contenant 4 éléments :
+**Synopsis :** variante centrée sur un seul cours, qui retourne pour chaque utilisateur de la liste ses références (''user'') et les statistiques du cours demandé (''coursedata'' : temps, nombre de sessions, première et dernière session, note). Le cours est obligatoire (''cid''). Si l'utilisateur n'a aucune trace dans le cours, les valeurs sont à 0.
-   * **user :** Les références de l'utilisateur
+**Paramètres :** identiques à ceux de ''block_use_stats_get_users_stats''.
-   * **query :** Un rappel des périodes d'extraction
-   * **sessions :** Des statistiques sur les sessions
-   * **courses :** Des statstiques cours par cours.
-==Exemple de structure de sortie==
+==== Service MNET ====
-    StdObject {
+**Service :** //Accès distant aux statistiques d'usage// (''use_stats'', API version 1). Il publie deux fonctions RPC. L'utilisateur appelant doit être identifié localement et détenir la capacité ''block/use_stats:seesitedetails'' ou ''block/use_stats:seecoursedetails''.
-       [user] => stdClass Object
-           (
-               [id] => 687
-               [idnumber] => ID93465
-               [username] => john.doe
-           )
-       [query] => stdClass Object
-           (
-               [from] => 0
-               [to] => 1497089144
-           )
-       [sessions] => stdClass Object
-           (
-               [sessions] => 232
-               [firstsession] => 1466104903
-               [lastsession] => 1497085452
-               [sessionmin] => 0
-               [sessionmax] => 22265
-               [meansession] => 2421
-           )
-       [courses] => Array
-           (
-               [0] => stdClass Object
-                   (
-                       [id] => 2
-                       [idnumber] => TESTMODS
-                       [shortname] => TEST_MODULES
-                       [fullname] => Test modules
-                       [activitytime] => 70240
-                       [coursetime] => 92611
-                       [coursetotal] => 164929
-                       [othertime] => 0
-                       [sitecoursetime] => 7855
-                   )
-           )
-    }
+=== block_use_stats_rpc_get_stats ===
-=== Fonction : block_use_stats_get_users_stats(uidsource, uids, cidsource, cid, from, to, score) ===
+Récupère les temps de connexion agrégés dans les différents cours, modules d'activité ou le temps global.
+**Paramètres**
+   * **callinguser :** l'identité de l'utilisateur appelant
+   * **targetuser :** l'identité de l'utilisateur objet de la demande
+   * **whereroot :** l'hôte sur lequel les résultats sont demandés. Si vide, les résultats sont calculés sur le Moodle courant.
+   * **statsscope :** la portée des statistiques (niveau d'agrégation : site, cours ou module)
+   * **timefrom :** date de début de la compilation
+   * **json_response :** si vrai, la réponse est encodée en JSON
+**Sortie**
+Une réponse dont le message est un document XML répondant à l'une des deux structures suivantes, selon la valeur de ''statsscope'' :
+<code>
+<USE_STATS>
+   <USER>
+      <USERNAME></USERNAME>
+      <FIRSTNAME></FIRSTNAME>
+      <LASTNAME></LASTNAME>
+      <FROM></FROM>
+      <ELAPSED></ELAPSED>
+   </USER>
+   <COURSES>
+      <COURSE>
+         <NAME></NAME>
+         <SHORTNAME></SHORTNAME>
+         <IDNUMBER></IDNUMBER>
+         <ELAPSED></ELAPSED>
+      </COURSE>
+   </COURSES>
+</USE_STATS>
+</code>
+ou
+<code>
+<USE_STATS>
+   <USER>
+      <USERNAME></USERNAME>
+      <FIRSTNAME></FIRSTNAME>
+      <LASTNAME></LASTNAME>
+      <FROM></FROM>
+      <ELAPSED></ELAPSED>
+   </USER>
+   <MODULES>
+      <MODULE>
+         <NAME></NAME>
+         <TYPE></TYPE>
+         <IDNUMBER></IDNUMBER>
+         <ELAPSED></ELAPSED>
+      </MODULE>
+   </MODULES>
+</USE_STATS>
+</code>
-**Synopsis :** similaire à la précédente, mais récupère une tableau de structures de réponse correspondant à une liste d'utilisateurs fournis en entrée.
+=== block_use_stats_rpc_get_scores ===
-==Paramètres==
+Récupère la note finale d'un utilisateur dans un cours, à partir du même service et suivant une méthode similaire à celle de la collecte des statistiques.
-   * **uids :** Remplace le paramètre uid de la fonction précédente, et doit contenir un tableau d'identifiants compatibles avec la valeur du paramètre //uidsource//.
+**Paramètres**
-==Sortie==
+   * **callinguser, targetuser, whereroot :** comme pour ''get_stats''
+   * **scorescope :** portée des notes. Seule la valeur ''notes/global'' (note finale du cours, valeur par défaut) est implémentée.
+   * **courseidfield :** champ d'identification du cours : ''id'' (par défaut), ''idnumber'' ou ''shortname''
+   * **courseidentifier :** identifiant du cours
+   * **jsonresponse :** si vrai (par défaut), la réponse est encodée en JSON
-Un tableau de structures identiques à la sortie de la fonction précédente, pour la liste d'utilisateurs demandée.
+**Sortie :** un document XML ''<USER_SCORES>'' contenant les références de l'utilisateur et la note finale du cours (''<SCORE>''). Pour tout autre ''scorescope'', la réponse est ''<ERROR>Not implemented</ERROR>''.
 ----------
 <html><!-- nomoodle --></html>
-[[:blocks:usestats:Technique|Revenir à l'index du guide technique]] - [[:Plugins|Revenir à l'index des plugins]] - [[:start|Revenir au catalogue]]
+[[:blocks:usestats:technique|Revenir à l'index du guide technique]] - [[:Plugins|Revenir à l'index des plugins]] - [[:start|Revenir au catalogue]]
 <html><!-- /nomoodle --></html>