Clé d'API de Guild Wars 2
Because I’m API !
Une API est une interface de programmation applicative (Application Programming Interface, en anglais). Pour faire simple, c’est un moyen d’échanger des données informatiques ou d’envoyer des instructions qui sont normalisées et donc exploitables par un grand nombre de langages différents.
Guild Wars 2 n’est pas le premier à en utiliser : d’autres MMORPG ou grands noms (Facebook, Twitter, LinkedIn) ont une API.
Chaque API est différente, c’est pour cette raison qu’il y a toujours une documentation technique qui les accompagne. Pour Guild Wars 2, elle est disponible en accès libre sur le wiki anglais : https://wiki.guildwars2.com/wiki/API:Main
Si, par exemple, pour Facebook et Twitter, il est possible de leur envoyer des données pour créer du contenu sur votre compte, connaître vos informations personnelles ou vos amis et leur activité, ce n’est absolument pas le cas avec l’API de Guild Wars 2.
L’API se décompose en deux parties : la première qui est accessible sans identification, c’est-à-dire sans clé, et qui fournit des informations sur le jeu (objets, recettes, succès, mécanismes du jeu, …) ; la seconde est celle qui donne des informations liées à votre compte (si l’autorisation paramétrée le permet).
Dans la grande majorité des cas, utiliser une clé d’API vous facilite la vie. Par exemple, avec GW2Efficiency, qui offre un panel impressionnant d’informations et d’outils pour vous aider en jeu, ou encore GW2Crafts qui permet de savoir quels matériaux vous avez déjà et ceux que vous devez acheter pour monter vos métiers ou encore GW2BLTC si vous avez l’âme d’un trader.
Vous pouvez aussi inventer vos propres utilisations, si explorer les données brutes de l’API ne vous fait pas peur ou en détournant l’utilisation de base d’applications à votre disposition.
Exemple : j’aide actuellement un joueur à monter son niveau de maîtrises ; pour ne pas l’embêter en lui préparant son programme, je lui ai demandé une clé d’API avec l’autorisation de base “account” ainsi que l'autorisation “progression” ; j’ai ajouté cette clé à GW2Efficiency, sur mon compte (il est possible d’en ajouter plusieurs et de passer d’une clé à l’autre en 2 clics) ; je peux ainsi naviguer de manière libre et autonome dans ses succès pour connaître sa progression et lui proposer des activités utiles lorsque nous jouons ensemble.
Créer une clé
Rendez-vous sur le site officiel, survolez “Services” et cliquez sur “Mon compte”. Identifiez-vous puis cliquez sur “Applications”. Sur cette page sont listées toutes les clés que vous avez créées. Vous pouvez les supprimer ou modifier leur nom. Pour en créer une nouvelle, cliquez sur "Nouvelle clé".
Donnez un nom à votre clé pour pouvoir vous rappeler à quoi vous l’avez attribuée quand vous voudrez faire un peu de nettoyage. Personnellement, j’indique l’adresse du site ou le nom de l’application.
Sélectionnez les autorisations utiles et validez en cliquant sur "Créer une clé d'application". Vous serez automatiquement redirigé sur la liste de vos clés, il ne vous restera plus qu’à trouver celle que vous venez de créer et l’utiliser.
Focus sur les autorisations
Lorsque vous créez une nouvelle clé API, vous pouvez choisir quel type d’informations vous souhaitez exposer. Si le site ou l'application tente d’accéder à ces informations alors que vous n’avez pas donné l’autorisation nécessaire, il n’aura comme donnée qu’une erreur lui indiquant qu’il n’a pas l’autorisation requise.
- account (cochée par défaut) : les informations de base liées à votre compte, nous le détaillons plus bas ;
- inventories : banque, banque de matériaux, recettes déverrouillées et sacs de vos personnages ;
- characters : informations sur vos personnages (histoire personnelle, nom, race, profession, genre, niveau, âge, nombre de morts, titres, métiers, armes, armure, bijoux, …) ;
- tradingpost : transactions du comptoir en cours et passées ;
- wallet : portefeuille des différentes monnaies du jeu (or, karma, monnaies de donjons, de cartes, …) ;
- unlocks : apparences déverrouillées (miniatures, armures, armes, teintures, …) ;
- pvp : statistiques, historiques, progression, parcours ;
- builds : compétences, aptitudes et spécialisations pour tous les modes de jeu (JcE, JcJ et McM) ;
- progression : succès, donjons, raids, points de maîtrises, … ;
- guilds : liste des membres, historique, MOTD des guildes dont vous êtes membre.
Sachez que vous pouvez à tout moment décider de supprimer une clé, ce qui coupe l’accès à vos données de l’API au tiers avec qui vous l’avez partagée.
Tester l’API de Guild Wars 2
Vous avez le goût de l’exploration et vous touchez un peu à l’informatique ? Vous pouvez tout-à-fait jeter un œil à l’API avec ou sans clé pour voir par vous-même quelles informations vous pouvez recueillir et exploiter.
Pour cela, un simple navigateur vous suffit (je recommande Firefox car il structure les réponses). Personnellement, j’utilise Postman, qui est gratuit et disponible sur Windows, Mac et Linux https://www.getpostman.com/.
L’interface n’est pas bien compliquée :
- Pour GW2, ce sont toujours des requêtes de type GET, saisissez l’URL du point d’accès que vous souhaitez explorer (sur l’image, c’est celui de "account", plus d'infos : https://wiki.guildwars2.com/wiki/API:2/account) ;
- Si le point d’accès requiert une autorisation, sélectionnez le type “Bearer Token” ;
- Si le point d’accès requiert une autorisation, saisissez votre clé d’API (valide ou non, si vous voulez tester les erreurs d’identification ou d'autorisations) ;
- Cliquez sur “Send” pour envoyer la requête ;
- Dans cet encadré, vous obtiendrez la réponse de l’API.
La documentation de l’API vous donnera toutes les informations utiles dont vous avez besoin (mais n’existe qu’en anglais) : les points d’accès, si l'authentification est requise ou non, et quelles sont les données retournées, .
Informations exposées par l’autorisation “account”
Pour vous prouver qu’il n’y a aucune information sensible, voici les données visibles avec ma clé d’API, sur le point d’accès "/account", au moment où je rédige cette page :
{
"id": "2067DAC0-CEEE-E111-BBF3-78E7D1936222",
"name": "Anthony.5487",
"age": 8223000,
"world": 2101,
"guilds": [
"247AB29E-CE9B-4D80-9717-0A0F3F8E6230",
"EE786128-083D-4C1F-8EFB-366E820D7E0C",
"9E833A56-9619-4ABA-837A-6D268D26D6A9",
"3B69F86C-6DE2-E711-81A1-0234DC5E07D2"
],
"guild_leader": [
"EE786128-083D-4C1F-8EFB-366E820D7E0C"
],
"created": "2012-08-25T16:04:00Z",
"access": [
"GuildWars2",
"HeartOfThorns",
"PathOfFire"
],
"commander": true,
"fractal_level": 95,
"daily_ap": 4649,
"monthly_ap": 47,
"wvw_rank": 46
}
En détail, voici ce qu’indiquent ces informations :
| Identifiant | Signification |
|---|---|
| id | Identifiant unique du compte, j’avoue que je ne connais pas son utilité puisque je n’ai jamais eu besoin de l’utiliser. |
| name | Nom de mon compte Guild Wars 2 (très utile quand vous voulez être sûr de l’orthographe du nom de compte des joueurs pour leur envoyer des cadeaux ;) ). |
| age | Temps de jeu total, en secondes. |
| world | Identifiant du monde (serveur) ; en utilisant cette valeur avec le point d’accès “worlds”, deux nouvelles données sont accessibles : le nom du monde et son niveau de population (bas, moyen, haut, très haut, complet). |
| guilds | Liste des identifiants de vos guildes. En utilisant ces identifiants, il est possible de connaître : le nom de la guilde, son tag, son emblème. Les informations détaillées des guildes (logs, membres, rangs, …) requièrent l’autorisation “guilds”. |
| created | Date de création du compte. |
| access | Type de compte et ce à quoi vous avez accès : “PlayForFree” si vous avez un compte gratuit ou “GuildWars2” si vous avez acheté le jeu, puis “HeartOfThorns” et “PathOfFire” si vous avez les extensions du même nom. |
| commander | Sa valeur est “false” si vous n’avez pas acheté le tag de commandant, “true” à l’inverse. |
Pour la capture d’écran, j’ai utilisé une clé avec toutes les autorisations cochées, il y a donc des informations supplémentaires fournies :
| Identifiant | Signification |
|---|---|
| guild_leader | Si vous êtes le propriétaire d’une ou plusieurs guildes, la liste de leur identifiant. Dans mon cas, je suis propriétaire de ma guilde personnelle que j’utilise comme banque. |
| fractal_level | Votre niveau en fractales. |
| daily_ap | Le nombre de points de succès que vous avez gagnés en faisant les quotidiennes. |
| monthly_ap | Le nombre de points de succès gagnés avec les mensuelles (ce système n’existe plus en jeu, mais les points apparaissent toujours sur l'écran des succès). |
| wvw_rank | Votre rang en McM. |
Cas d’utilisation des clés d’API pour Le Bus Magique
LBM Connect
Nous avons mis en place pour Discord un outil de vérification automatique de compte, pour éviter de se faire embêter par les bots et messages indésirables. Cette fonction permet d’attribuer le rôle “Vérifié”, et “[LBM]” si vous faites partie de la guilde au moment de la vérification. Chacun de ces rôles débloque l’accès à des ensembles de canaux.
Principe de fonctionnement :
- Vous créez ou utilisez une clé existante avec l’autorisation cochée par défaut “account”
- Vous visitez entrez une commande suivie de votre clé API dans l'un de nos canaux sur discord
- nous pouvons ainsi connaître votre nom de compte GW2 exact et remplacer votre pseudonyme sur le serveur Discord du LBM (vous pouvez utiliser un pseudo Discord différent pour chaque serveur que vous avez rejoint) par votre nom de compte ;
- nous vous attachons automatiquement le rôle “Vérifié” ;
- nous vérifions si, dans la liste de vos guildes, Le Bus Magique (sous l’identifiant “9E833A56-9619-4ABA-837A-6D268D26D6A9”) est bien présent pour vous attribuer le rôle “[LBM]”.
Pour le bon fonctionnement du script, les informations du compte Discord et la clé API sont simplement enregistrées dans une session de votre navigateur, qui est détruite à la fin de l’opération ou si elle a échoué. C’est-à-dire qu’aucune donnée n’est enregistrée en base de données ou dans un fichier, donc inaccessible par les membres de l’équipe du Bus, puisque si nous souhaitons avoir des logs, Discord nous indique très bien les vérifications qui sont faites par ce script.
Demande de ticket
Un peu avant la sortie de Path of Fire, nous avons mis en place un système d’invitations à rejoindre notre guilde pour automatiser le plus possible les tâches qui y sont liées. En effet, notre cas est un peu particulier car, atteignant régulièrement la limite de 500 membres dans notre guilde, il est parfois difficile de gérer les flux tendus comme à la sortie d’une nouvelle extension ou d’un nouvel épisode.
Du côté des joueurs, il suffit d’indiquer votre clé d’API avec l’autorisation de base “account” et une adresse e-mail valide. La clé nous permet de créer une ligne dans un tableau. L’adresse e-mail est utilisée uniquement pour notifier la personne qui fait la demande, qu’une invitation à rejoindre la guilde lui a été envoyée dans le jeu.
Derrière le guichet, la gestion des tickets
Si nous stockons ces informations en base de données, nous ne conservons pas la clé d’API utilisée, c’est-à-dire que nous conservons des données fournies à un instant T et qu'elles ne sont jamais mises à jour (sans la clé, c'est impossible).
Une fois que l’invitation est clôturée, les informations qui lui sont liées ne sont plus visibles dans notre tableau et sont utilisées à des fins statistiques (les deux graphiques, juste en dessous, qui nous sont utiles pour définir les dates des purges).
Personnalisation du contenu des guides
Nous essayons de plus en plus de personnaliser votre expérience sur le site, pour en tirer des enseignements avant de le mettre en place sur la prochaine version du site.
Aujourd’hui, pour certains guides, il vous est possible d’indiquer votre clé API pour connaître votre progression dans l’accomplissement du succès ou l’équipement en chats et zones de récolte de votre instance.
Sachez que cette clé est stockée dans votre navigateur, nous ne l’enregistrons jamais en base de données et elle n’est pas rattachée à votre compte sur le site, si vous en avez un.
Vous pouvez la renseigner directement en haut à droite des guides ou dans votre compte du site.
Date de dernière mise à jour : 26/11/2022