Pré-requis :
1) Un compte OT&E de test (activé via l'interface revendeur)
2) Un shell UNIX (aisément portable sous windows)
3) Un interpréteur python
Tout d'abord, créer un fichier python contenant les lignes suivantes :
dek@agami:~/gandi/doc/api$ cat api-gandi.py
import xmlrpclib
login = 'PP1-GANDI'
password = 'docapi'
proxy = xmlrpclib.ServerProxy('https://api.ote.gandi.net/xmlrpc/')
session = proxy.login(login, password)
dek@agami:~/gandi/doc/api$
Ce fichier comporte les déclarations suivantes :
1. L'import de xmlrpclib, une bibliothèque fournie avec python qui
dispose des fonctionnalités nécessaires pour faire de l'XML-RPC.
2. La définition d'une variable login qui est le nom de votre compte.
Ici le compte est 'PP1-GANDI'.
3. La définition d'une variable password, le password associé au
compte. Ici le mot de passe est 'docapi'.
4. La création d'une variable proxy, qui est une connexion au serveur
de l'OT&E Gandi.
5. La récupération d'une variable de session. Celle-ci s'effectue de
la manière suivante : la méthode 'login' est appelée sur l'objet
'proxy' qui représente la connexion au serveur XML-RPC. Cette méthode
prend en paramètre le login et le mot de passe et retourne une chaîne
de caractère qui est un identifiant de session. Cet identifiant sera
ensuite utilisé à chaque appel de méthode.
Pour obtenir un shell python, il suffit d'exécuter python avec l'option
-i qui permet d'entrer en mode interactif après avoir exécuté les
lignes précédentes. Si les paramètres sont corrects (serveur, compte
et mot de passe), il devrait se passer ceci :
dek@agami:~/gandi/doc/api$ python -i api-gandi.py
Le '>>>' indique une ligne de commande en mode interactif. À partir de
ce prompt on peut exécuter des commandes python et, c'est le but de ce
tutoriel, des commandes XML-RPC sur l'API Gandi.
Pour vérifier la disponibilité d'un ou plusieurs domaines, il suffit
de taper dans ce shell :
proxy.domain_available(session, ['abcdefgh.net', 'a1b2c3d4.com'])
{'abcdefgh.net': False, 'a1b2c3d4.com': False}
Manque de chance, ces deux domaines sont déjà pris dans le 'monde
virtuel' de l'OT&E des registres. Essayons un autre domaine :
proxy.domain_available(session, ['gandi-api-xml.net'])
{'gandi-api-xml.net': True}
Ha, celui-ci est disponible ! Le trouvant particulièrement joli, je
décide de l'acquérir. Vérifions s'il me reste un peu d'argent sur
mon compte prépayé :
proxy.account_balance(session)
497.68000000000001
proxy.account_currency(session)
'EUR'
Largement suffisant. D'après la documentation, l'enregistrement d'un
domaine se fait avec la méthode domain_create qui a la 'signature'
suivante :
int domain_create(string session, string domain, int period,
string owner_handle, string admin_handle, string tech_handle,
string billing_handle, array nameservers [, string lang])
Il suffit donc de l'appeler ainsi :
proxy.domain_create(session, 'gandi-api-xml.net', 1, login, login,
... login, login, ['ns1.example.org', 'ns2.example.org'])
1164
Dans cette ligne j'indique que je souhaite acheter le domaine
'gandi-api-xml.net' pour un an, et je me désigne (login valant
'PP1-GANDI') propriétaire, contact admin, contact technique et contact
de facturation. Aussi j'indique que les serveurs de noms pour ce domaine
seront ns1.example.org et ns2.example.org.
La méthode me retourne un identifiant d'opération, le numéro 1164.
Regardons ce que cette opération est :
import pprint
details = proxy.operation_details(session, 1164)
pprint.pprint(details)
{'object': 'domain',
'uid': 1164,
'date_update': <DateTime u'2007-01-18 18:15:04' at 827e4ac>,
'object_name': 'gandi-api-xml.net',
'param': {'source_ip': '217.70.181.9', 'period': 1},
'date_create': <DateTime u'2007-01-18 18:15:04' at 827e56c>,
'step': 'PENDING',
'type': 'domain_create'}
Tout d'abord, j'import pprint qui permet de formater proprement des
résultats à l'écran. Je récupère ensuite les détails de
l'opération dans la variable details que j'affiche avec la fonction
pprint de la bibliothèque du même nom.
Cette opération comporte plein de détails. On peut choisir de les
ignorer, le plus important est l'état, appelé 'step' qui ici est
'PENDING'. J'attends un peu et je regarde à nouveau.
details = proxy.operation_details(session, 1164)
pprint.pprint(details)
{'object': 'domain',
'uid': 1164,
'date_update': <DateTime u'2007-01-18 18:16:38' at 827e62c>,
'object_name': 'gandi-api-xml.net',
'param': {'source_ip': '217.70.181.9', 'period': 1, 'auth_id':
3768406},
'date_create': <DateTime u'2007-01-18 18:15:04' at 827e54c>,
'step': 'RUN',
'type': 'domain_create'}
Ha ! L'état vient de passer à RUN. Donc l'opération a été validée
par la facturation, regardons le compte :
proxy.account_balance(session)
483.32999999999998
Le domaine a donc été payé. Attendons un petit peu que la création
s'effectue...
details = proxy.operation_details(session, 1164)
pprint.pprint(details)
{'object': 'domain',
'uid': 1164,
'date_update': <DateTime u'2007-01-18 18:18:40' at 827e78c>,
'object_name': 'gandi-api-xml.net',
'param': {'source_ip': '217.70.181.9', 'period': 1, 'auth_id':
3768406},
'date_create': <DateTime u'2007-01-18 18:15:04' at 827e40c>,
'step': 'DONE',
'type': 'domain_create'}
Le domaine a été créé. Vérifions voir s'il est dans ma liste de
domaines...
proxy.domain_list(session)
['gandi-api-xml.net']
Et voilà ! Je suis l'heureux propriétaire, dans le monde virtuel de
l'OT&E du domaine gandi-api-xml.net. Je souhaite maintenant vérifier
sa date d'expiration etc., bref, toutes les informations possibles,
j'effectue donc un domain_info.
info = proxy.domain_info(session, 'gandi-api-xml.net')
pprint.pprint(info)
{'domain': 'gandi-api-xml.net',
'locked': True,
'registry_expiration_date': '2008-01-18 17:18:34',
'admin_handle': 'PP1-GANDI',
'registry_last_update': '2007-01-18 18:18:33',
'registry_creation_date': '2007-01-18 17:18:34',
'registrar_creation_date': '2007-01-18 18:18:33',
'billing_handle': 'PP1-GANDI',
'tech_handle': 'PP1-GANDI',
'owner_handle': 'PP1-GANDI'}
En quelques minutes et, à la main, j'ai donc acheté un domaine avec
l'API Gandi. Le fonctionnement de l'API en OT&E étant le même que
celui de l'API en production, on s'aperçoit que créer des petits
scripts pour administrer un grand nombre de domaines devient très
simple.
\o/ Pierrick "dek\" Prévert
G Gandi