11.10. Services web

Administration menu → Web services

Note

Les services web ne sont accessibles que par les adminsitrateurs.

Les services web vous permettent d’interconnecter votre site Mahara avec d’autres applications qui elles aussi supportent les services web / API. Cela nécessite de configurer vos sites web ou de développer des fonctions de services web spécifiques à ce que vous désirez accomplir. Les services web de Mahara forment un ensemble de fonctionnalités desquelles il est possible de développer de nouvelles fonctionnalités de manière relativement simple. Il suffit la plupart du temps de configurer une nouvelle fonction qui défini les fontionnalités requises en plus de la défnition d’une interface associée.

Afin de pouvoir utiliser les services web, votre site doit posséder un certificat SSL. Lorsque votre site n’est pas en production, vous pouvez tester les services web sans certificat SSL.

11.10.1. Configuration

Administration menu → Web services → Configuration

Sur cette page, vous pouvez paramétrer les différents services web que vous activez ou désactivez.

11.10.1.1. Activer les fonctionnalités des services web

You can enable web services globally and then configure protocols individually to suit your needs. Once a protocol is enabled, it can be used for all functions, accounts, and tokens.

Switch web services and individual protocols on and off

Activez les services web puis chacun des protocoles

  1. Allow outgoing web service requests: If set to “Yes”, web services are available to be used on your site for outgoing calls.

  2. Accept incoming web service requests: If set to “Yes”, web services are available to be used on your site for incoming calls, for example via Mahara Mobile.

  3. SOAP : Activez ce procole si vous désirez pouvoir utiliser les services de Simple Object Access Procol.

  4. XML-RPC: Set this to “Yes” if you want to make remote procedure calls to XML content. This protocol is used by MNet.

    Note

    Tant que MNet est supporté par Mahara, vous pouvez l’utiliser pour configurer des échanges de données avec Moodle.

  5. REST: Allow the REpresentational State Transfer protocol by switching this setting to “Yes”. The REST interface also supports JSON authentication.

  6. OAuth: If you want to use the OAuth (Open Authentication) protocol, switch this setting to “Yes”.

Note

Si vous désactiver les services web, chaque protocole qui était activé sous la rubrique « Protocole » est désactivé. Vous devrez les réactiver manuellement lorsque vous activez à nouveau les services web.

11.10.1.2. Certificats de réseau

In this section, the public key of your Mahara certicate that is created on Administration menu → Configure site → Networking is displayed for convenience.

11.10.1.3. Gérer les groupes de services

Service groups are the units of allocation of access to an account (simple authentication) or user tokens. They are a collection of functions. Mahara already comes with a series of service groups and functions that you can configure. More service groups can be added.

Overview of the available service groups and their basic settings

Aperçu des groupes de services disponibles et de leurs paramètres de base

  1. Service : Le nom du groupe de services contenant un certain nombre de fonctions que vous pouvez activer ou désactiver.

  2. Component: The area through which a service group is available. It is generally “webservice”.

  3. Activé : Si le groupe de services est activé, l’icône Activé est affichée, dans le cas contraire, c’est l’icône Désactivé qui est affichée.

  4. Seuls les utilisateurs autorisés : Si ce groupe de service peut être utilisé par des utilisateurs qui se sont authentifiés sur la plateforme, l’icône Activé est affichée. Si le service ne peut pas être utilisé par un tel utilisateur, c’est alors l’icône Désactivé qui est affichée.

  5. Accès par jeton pour l’utilisateur : Cette option est activée si l’accès aux fonctions de ce groupe nécessite un jeton. Si l’accès par jeton n’est pas autorisé, l’icône Désactivé est alors affichée.

  6. Fonction : Liste des fonctions associées à un groupe de services.

    Note

    En cliquant sur le nom d’une fonction, on accède à sa documentation. Des informations complémentaires sur la fonction du service web sont disponibles ici en plus de la description de l’API, les paramètres d’entrée et de sortie et la gestion des erreurs.

  7. Cliquez sur le bouton Modifier pour effectuer des modifications au groupe de services, comme expliqué ci-dessous.

  8. Cliquez sur le bouton Supprimer pour complètement supprimer le groupe de services.

    Note

    Dans la plupart des cas, il n’est pas souhaitable de supprimer un groupe de services, car, si vous désirez l’utiliser ultérieurement, vous aurez à le recréer à la main et y associer toutes les fonctions qui étaient préalablement présentes. Désactiver le groupe de service est souvent suffisant.

  9. Si vous désirez créer un nouveau groupe de services, ajoutez son nom dans cette rubrique et cliquez sur le bouton Ajouter. Vous verrez alors apparaître votre nouveau groupe de services dans la liste et pourrez le configurer en utilisant le button Modifier .

Lorsque vous sélectionnez le groupe de services que vous voulez modifier, vous accédez à l’écran suivant.

Edit the settings of a service group

Modifier les paramètres d’un groupe de services

  1. Nom : Nom du groupe de services

  2. Nom court : Nom court du service, qui est requis par les applications désirant se connecter à Mahara et accéder au service.

  3. Service: Set this switch to “Yes” if you want to use this service group. You can tweak the individual functions below.

  4. Authorised users only: Set this switch to “Yes” if only people with a username and password should be affected by this service group.

  5. User token access: Set this switch to “Yes” if you want users to have individual tokens in order to access certain functionalities.

    Note

    L’accès par jeton permet à tout utilisateur présent dans la base de données des utilisateurs d’accéder à l’API. Toutefois et généralement, ce système d’accès par jeton ne devrait être utilisé qu’avec les groupes de services qui ne donnent accès qu’au contenu du portfolio des utilisateurs, avec des fonctions comme mahara_user_get_my_user avec comme référence l’utilisateur courant.

  6. Le nom de la fonction

  7. Activé : Cette option active ou désactive l’usage de cette fonction.

  8. Nom de la classe : Le nom de la classe qui est membre de la fonction.

  9. Nom de la méthode : Le nom de la méthode qui est appelée par l’API. Le lien sur le nom de chaque méthode vous permet d’afficher la documentation concernant cette méthode.

  10. Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.

11.10.1.4. Gérer les jetons du service d’accès

You can generate access tokens for individual accounts and associate service groups to which that account shall have access.

Overview of the access tokens

Aperçu des jetons d’accès

  1. Token: The token that was generated for a particular account.

  2. Institution: Lists the institution to which the account belongs.

  3. Nom d’utilisateur : Le nom d’utilisateur de la personne est affiché et lié à sa page d’administration de ses préférences.

  4. Service : Le groupe de services pour lequel le jeton a été généré.

  5. Activé : Si ce groupe de services est activé, l’icône Activé est affichée. Dans le cas contraire, c’est l’icône Désactivé qui est affichée à la place.

  6. Sécurité des services web : Si la sécurité est activée, l’icône Activé est affichée, sinon c’est l’icône Déactivé qui est affichée à la place.

  7. Fonctions : Liste des différentes fonctions que le jeton peut utiliser dans le service sélectionné.

  8. Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.

  9. Cliquez sur le bouton Supprimer pour supprimer le jeton.

  10. Username: Type a username for whom you wish to add a token. You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type.

  11. Click the Generate token button for a new access token to be created for that account. You are taken to a screen where you can associate a service group to this token (see below). You can only enter one username.

When you create a token, you need to provide some additional information.

Configure a service access token

Configurer un accès au service par jeton

  1. Véfifiez que vous êtes bien entrain de modifier le bon jeton.

  2. Institution: Select the institution to which the account belongs.

  3. Username: Verify that you have the correct username for which you want to set up a token. The username is linked to the person’s settings page in the administration.

  4. Service: Choose the service group from the drop-down list for which you want to enable the token. Only services that allow token access can be chosen.

  5. Activé : Le jeton est automatiquement activé quand le groupe de services l’est aussi.

    Note

    Si vous désirez désactiver un groupe de services, veuillez vous rendre dans la section Gérer les groupes de services.

  6. Seuls les utilisateurs autorisés : Ce sélecteur n’est pas utilisé dans ce contexte car ici vous créez un jeton. C’est pourquoi il a été désactivé.

  7. Fonctions : La liste des fonctions que le jeton permet d’accéder.

    Note

    Lorsque vous modifiez le service, la liste des fonctions n’est pas automatiquement mise à jour. La mise à jour n’est visible qu’après avoir enregistré la page.

  8. Activer la sécurité des WS (XML-RPC seulement) : Cette fonction de sécurité des services web n’est disponible que pour les authentifications avec XML-RPC.

  9. Clé publique : Entrez la clé publique pour ajouter la sécurité des services web (seulement disponible lorsque XML-RPC est utilsé pour l’authentification).

  10. Date d’échéance de la clé publique : Date à laquelle la clé publique que vous avez entrée échoit. Cette valeur est mise à jour au moment où vous enregistrez le formulaire.

  11. Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.

11.10.1.5. Gérer les utilisateurs dans le service

Si vous ne désirez pas utiliser les jetons pour donner accès aux services web à vos utilisateurs, vous pouvez leur donner accès aux fonctions par leur nom d’utilisateur. Cette manière de faire est d’ailleurs plus recommandée que la première. Les utilisateurs doivent :

  • peuvent n’être configurés qu’une seule fois.

  • have the “webservice” authentication method in an institution in which they are a member.

    Note

    Accounts with the authentication method “webservice” can only access Mahara via web services and cannot use the standard login form.

Manage service users overview section

Aperçu de la section de gestion des services des utilisateurs

  1. Utilisateur : Le nom d’utilisateur de la personne à laquelle vous voulez donner l’accès un groupe de services apparaît ici. Son nom est lié à sa page d’administration des préférences.

  2. Institution: Lists the institution to which the account belongs.

  3. Service: The service group that is associated with the account.

  4. Activé : Si ce groupe de services est activé, l’icône Activé est affichée. Dans le cas contraire, c’est l’icône Désactivé qui est affichée à la place.

  5. Sécurité des services web : Si la sécurité est activée, l’icône Activé est affichée, sinon c’est l’icône Déactivé qui est affichée à la place.

  6. Fonctions : La liste des fonctions auxquelles cet utilisateur a accès pour le service sélectionné.

  7. Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.

  8. Click the Delete button to remove the account from the access to the associated service group.

  9. Username: Type a username for whom you wish to manage the services. You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type. The account must have web services as authentication method.

  10. Click the Generate token button for a new access token to be created for that account. You are taken to a screen where you can associate a service group to this token (see below). You can only enter one username.

When you add an account, you need to provide some additional information.

Associate a user with a specific service group

Associer un utilisateur à un groupe de services particulier

  1. Propriétaire du service : Le nom d’utilisateur est affiché. Il doit correspondre au nom d’utilisateur d’en-dessous.

  2. Institution: Verify that the institution associated with the account is correct. If it is not, you can change the institution on the account settings page.

  3. Nom d’utilisateur : Vérifiez que vous avez le bon nom d’utilisateur associé à ce jeton.

  4. Service: Choose the service group from the drop-down menu to which you want to give the person access. Only services that allow access via a username can be chosen.

  5. Activé : Cette option est automatiquement activée lorsque le groupe de services l’est aussi.

    Note

    Si vous désirez désactiver un groupe de services, veuillez vous rendre dans la section Gérer les groupes de services.

  6. Authorised users only: This switch is set to “Yes” automatically when the service group is configured to allow access via a username.

  7. Functions: A list of functions that the account has access to.

    Note

    Lorsque vous modifiez le service, la liste des fonctions n’est pas automatiquement mise à jour. La mise à jour n’est visible qu’après avoir enregistré la page.

  8. Activer la sécurité des WS (XML-RPC seulement) : Cette fonction de sécurité des services web n’est disponible que pour les authentifications avec XML-RPC.

  9. Clé publique : Entrez la clé publique pour ajouter la sécurité des services web (seulement disponible lorsque XML-RPC est utilsé pour l’authentification).

  10. Date d’échéance de la clé publique : Date à laquelle la clé publique que vous avez entrée échoit. Cette valeur est mise à jour au moment où vous enregistrez le formulaire.

  11. Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.

11.10.2. Connexions vers l’application

Administration menu → Web services → Application connections

Il s’agit d’un aperçu des toutes les connexions que vous avez autorisées via un jeton d’utilisateur ou par jeton d’accès OAuth.

Overview of the application connections

Aperçu des connexions de l’application

  1. The section Personal user tokens displays all the tokens that you have generated for individuals and whether they have been accessed or not amongst others.

  2. Accès au service : Cette colonne affiche le groupe de services pour lesquel le jeton a été créé.

  3. Activé : Si le groupe de services est activé, l’icône Activé est affichée, sinon c’est l’icône Désactivé qui l’est à la place.

  4. App client : Affiche la manière dont a été créé le jeton d’accès.

  5. Jeton : Le jeton est affiché ici.

  6. Fonctions : Les fonctions qui font partie d’un groupe de services sont affichées et liées à la définition des fonctions. Le lien permet de se rendre vers la documentation concernant la fonction sélectionnée.

  7. Dernier accès : Liste la date et l’heure de la dernière utilisation du jeton.

  8. Échéance : Affiche la date d’échéance du jeton.

  9. Cliquez sur le bouton Générer pour générer un nouveau jeton aléatoire.

  10. Cliquez sur le bouton Supprimer pour supprimer le jeton. Le groupe utilisateur et les fonctions restent disponibles. Vous pouvez alors cliquer sur Générer pour recréer un nouveau jeton.

    Note

    Le bouton Supprimer n’est disponible que lorsqu’un jeton a été créé.

  11. Dans la section Jeton d’accès pour OAuth vous pouvez voir l’ensemble des jetons générés pour être utilisés avec OAuth.

11.10.3. Gestionnaire des connexions

Administration menu → Web services → Connection manager

Le gestionnaire de connexion facilite l’utilisation des services web en rendant plus facile le paramétrage des connexions.

Pour plus d’information sur ce sujet, veuillez vous rendre sur le wiki (idée de base) et sur la base de demandes de nouvelles fonctionnalités.

Overview page for the connection manager

Aperçu du gestionnaire de connexions

11.10.4. Enregistrer une app externe

Administration menu → Web services → External apps

Vous pouvez utiliser cette page pour enregistrer les apps externes qui sont connectées via OAuth. Un exemple est le service LTI (Learning Tool Interoperability). Vous pouvez activer les outils externes pour certaines institutions et autres définitions de services, pour lesquelles un utilisateur recevra une clé et une phrase secrète qui seront générées automatiquement.

Register an external application

Enregistrer une app externe

  1. Application : Liste des applications qui sont connectées via OAuth.

  2. Owner: The person who has set up the OAuth service.

  3. Clé client : La clé client pour le service OAuth.

  4. Mot de passe : Le mot de passe pour le service OAuth.

  5. Activé : Si l’application est activée, l’icône Activé est affichée, sinon c’est l’icône Désactivé qui l’est à la place.

  6. Institution: The institution for which the external app has been set up.

  7. Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.

  8. Cliquez sur le bouton Supprimer pour supprimer l’application. Cette application ne pourra alors plus accéder à Mahara par OAuth.

  9. Click the Manage button to decide on more settings where available.

  10. Application : Indiquez l’application que vous désirez nommer.

  11. Sélectionnez l’institution qui aura accès par OAuth à l’application choisie.

  12. Sélectionnez le groupe de services que vous désirez associer à cette application.

  13. Cliquez sur le bouton Ajouter pour créer l’authentification par OAuth pour le service sélectionné. Vous être alors redirigé vers un écran où vous pouvez configurer votre application (voir ci-dessous).

You can see details about the connection that you are setting up by clicking the Edit button .

Configure an OAuth service

Configurer un service OAuth

  1. Consumer key: The consumer key for the external service.

  2. Consumer secret: The consumer secret for the external service.

  3. Application title: You can change the title for the application.

  4. Service owner: Person who has set up the external service. new in Mahara 20.04 You can change the owner of the service so that it is not all tied to a site administrator. This is handy when you want to set up a specific account that handles all web services calls.

  5. Application URI: URI of the application. If it is not needed, it is ignored.

  6. Callback URI: The callback URI for the application. If it is not needed, it is ignored.

  7. Institution: Select the institution for which you want to set up the external service.

  8. Service: Select the service group that you want to set up.

  9. Activé : L’application est automatiquement activée quand OAuth l’est aussi.

  10. Fonctions : Liste des fonctions auxquelles l’application a accès.

    Note

    Lorsque vous modifiez le service, la liste des fonctions n’est pas mise à jour automatiquement. Vous ne verrez les modifications qu’après avoir enregistré la page.

  11. Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.

11.10.5. Journal du service Web

Administration menu → Web services → Web services logs

Vous pouvez afficher le journal pour l’ensemble des services web puis restreindre l’affichage en effectuant des recherches sur les éléments qui vous intéressent.

Search the web services logs

Rechercher dans les services web

  1. User : Entrez le no d’utilisateur d’une personne pour laquelle vous désirez afficher le journal des services web. Vous pouvez entrer qu’un seul nom d’utilisateur. Vous pouvez soit commencer à taper le nom ou le nom d’utilisateur d’une personne enregistrée sur votre site. Au fur et à mesure de la saisie vous recevrez une liste de suggestion de laquelle vous pouvez directement cliquer sur le nom que vous recherchez.

  2. Protocol: Select the web services protocol that is associated with the account. You can only see the protocols that are enabled.

  3. Auth type: Choose the type of authentication that you selected for the account. The options are:

    • Tous : Affiche le journal pour tout type d’authentification.

    • Token: Only display logs when the account has a user token.

    • User: Display the logs when the account uses the username for the web service.

    • OAuth: Select this option if you only want to see logs when the person logs in via OAuth.

  4. Fonction : Permet d’affiche que le journal pour une fonction particulière des services web.

  5. Only errors: Switch to “Yes” if you only want to see log information that contains an error.

  6. Cliquez sur le bouton Aller pour lancer votre recherche.

Si votre recherche a des résultats, ils seront affichés dans la zone Résultats.

Results for the search of the web services logs

Résultats de la recherche sur la journalisation des services web

  1. User: Display the username of the account for which there is a log entry.

  2. Institution: Display the name of the institution to which the account belongs.

  3. Protocol: Show the protocol that is associated with the account for the chosen context.

  4. Authentication type: Show the authentication type that is associated with the account.

  5. Fonction : Affiche la fonction pour laquelle il existe des informations de journalisations.

  6. Temps utilisé : Le temps utilisé pour obtenir les informations de journalisation demandées.

  7. Date : Affiche la date à laquelle la journalisation a été effectuée.

  8. Vous pouvez modifier l’ordre de tri pour cette colonne en cliquant sur son en-tête.

  9. Info Les messages d’erreur sont affichés ici.

11.10.6. Client de test pour les services web

Administration menu → Web services → Web services test client

Le client de test vous permet de tester votre configuration des services web. Soyez attentif au fait que les fonctions exécutées le sont pour de vrai sur le système.

Web services test client

Client de test pour les services web

Note

Lorsque vous débutez la configuration, vous ne voyez que le protocole et le type d’authentification, si vous n’avez qu’un seul protocole sélectionné. Les autres rubriques ne sont affichées qu’après que vous ayez décidé ce que vous désirez tester.

  1. Protocole : Vous ne voyez que les protocoles des services web que vous avez activés. Si vous voyez plus d’un protocole, sélectionnez celui que vous désirez tester.

  2. Type d’authentification : Sélectionnez le type d’authentification que vous désirez inclure dans votre test. Cliquez sur le bouton Suivant pour afficher les options suivantes.

  3. Service : Sélectionnez le groupe service que vous désirez utiliser pour le test. Cliquez sur le bouton Suivant pour afficher les options suivantes.

  4. Fonctions : Sélectionnez la fonction que vous désirez utiliser pour le test. Cliquez sur le bouton Suivant pour afficher les options suivantes.

  5. wstoken: Enter the web services token for the account that you want to test.

    Note

    If you selected “User” for the authentication type, you’ll also see a field wspassword that you can fill in.

  6. Cliquez sur le bouton Exécuter si vous désirez lancer le test, ou cliquez sur Annuler si vous désirez interrompre la procédure.

Une fois que le test a été effectué, les résultats sont affichés à l’écran.