DNSmanager API. Information générale (DNSmanager)

De ISPWiki.

DNSmanager offre la possibilité d’utiliser toutes ses fonctions à partir des programmes extérieurs qui peuvent être placés localement (sur le même serveur) ou à distance (sur un autre serveur). Pour appeler une fonction de DNSmanager, l’[auth.api identification] peut être nécessaire.

Sommaire

Format de sortie des résultats d'exécution des fonctions de DNSmanager

DNSmanager donne la possibilité d'obtenir des résultats d'exécution de ses fonctions au format XML, aussi bien qu'au format textuel.

La sortie des résultats d'exécution des fonctions de DNSmanager au format XML

Pour obtenir les données en XML il est nécessaire d’indiquer un paramètre supplémentaire out=xml dans la requête. Le résultat dépend du type de fonction à laquelle vous vous adressez. Alors, quand vous obtenez la liste des éléments, la fonction retourne le document XML composé de la liste des noeuds XML, l'un sur chaque élément. Chaque noeud à son tour est composé d'ensemble de noeuds définissant les paramètres de cet élément. Par exemple, en vous connectant au panneau d'administration pour obtenir la liste des sites vous verrez:

# fetch -qo - "https://12.34.56.78/manager/dnsmgr" <?xml version="1.0" encoding="UTF-8"?> <doc> <elem> <name>dnsadmin</name> <view>main.com</view> <owner>dnsadmin</owner> <level>admin</level> <domains used="0" limit="1000"/> </elem> <elem> <name>dnsuser1</name> <view>dns.com</view> <owner>resel</owner> <level>user</level> <domains used="2" limit="100"/> </elem> </doc>

Lors de l'appel d'une fonction qui donne l'ensemble de paramètres, p.ex. lors de sa visualisation ou édition, le panneau d'administration retourne le document XML avec la liste des noeuds correspondant aux paramètres d'un élément édité. Par exemple, en affichant les paramètres du site vous voyez:

# fetch -qo - "http://12.34.56.78/manager/dnsmgr?func=user.edit&elid=dnsuser1&out=xml" <?xml version="1.0" encoding="UTF-8"?> <doc> <elid>dnsuser1</elid> <name>dnsuser1</name> <level>user</level> <domlimit>100</domlimit> </doc>

Si vous appelez la fonction qui doit effectuer une opération p.ex. désactiver le site et tous ses utilisateurs, le panneau d'administration retourne le document XML de réussite de l'opération

# fetch -qo - "http://12.34.56.78/manager/dnsmgr?func=user.delete&elid=dnsuser1&out=xml" <?xml version="1.0" encoding="UTF-8"?> <doc> <ok/> </doc>

ou le message d'erreur

# fetch -qo - "http://12.34.56.78/manager/dnsmgr?func=user.delete&elid=dnsuser1&out=xml" <?xml version="1.0" encoding="UTF-8"?> <doc> <error>user not found.</error> </doc>

La sortie des résultats d'exécution des fonctions d'DNSmanager au format textuel

Pour obtenir les données au format textuel il est nécessaire d'indiquer un paramètre supplémentaire out=text dans la requête. Le résultat dépend aussi du type de fonction à laquelle vous vous adressez. Ainsi, si vous obtenez la liste des éléments, la fonction retourne la liste des lignes chacune desquelles correspond à un seul élément et est composée d'ensemble de paramètres de cet élément. P.ex. quand vous vous connectez au panneau d'administration pour obtenir la liste des sites vous verrez:

# fetch -qo - "http://12.34.56.78/manager/dnsmgr?func=user&out=text" name=admin view=admin.com owner=admin level=admin domains=0/0 name=resel view=dnsres.com owner=admin level=reseller domains=2/100 name=dnsuser1 view=dnsuser.com owner=resel level=user domains=0/100 name=dnsuser2 view=dns.com owner=resel level=user domains=1/100

Lors de l'appel d'une fonction qui retourne l'ensemble de paramètres d'un élément p.ex. lors de sa visualisation et edition, le panneau d'administration retourne la liste des paramètres d'un élément, l'un pour chaque ligne. Par exemple, avant les paramètres du site vous voyez:

# fetch -qo - "http://12.34.56.78/manager/dnsmgr?func=user.edit&elid=dnsuser1&out=xml" elid=dnsuser1 name=dnsuser1 level=user view=dnsuser.com domlimit=100

Si vous appelez la fonction qui doit effectuer une opération p.ex. désactiver le site et tous ses utilisateurs, en cas de réussite de l'opération le panneau d' administration retourne

# fetch -qo - "http://12.34.56.78/manager/dnsmgr?func=user.delete&elid=dnsuser1&out=xml" OK

ou le message d'erreur

# fetch -qo - "http://12.34.56.78/manager/dnsmgr?func=user.delete&elid=dnsuser1&out=xml" ERROR: user dnsuser1 not found.

L'ordre de la description des fonctions de DNSmanager

La description des fonctions de DNSmanager est présentées d'une manière suivante:

Fonction: le nom de fonction qu'il est nécessaire d'indiquer dans le paramètre func de la requête.

Paramètres: la liste des paramètres avec une description brève. Si la fonction n'accepte aucuns paramètres, ils ne sont pas indiqués dans la description. Les paramètres sont spécifiés au format paramètre=valeur.

Résultat: il existe quelques types de résultats, cela dépend du type d'une fonction requise:

  • Liste des éléments (tableau).
  • Liste des paramètres d'un objet (formulaire).
  • Réussite de l'opération (action).
  • Message d'erreur.

Ci-dessous nous présentons chacun de ces types de résultat avec description et des exemples.

Liste des éléments (tableau)

Dans ce cas le document XML est présenté d’une manière suivante:

<?xml version="1.0" encoding="UTF-8"?> <doc> <elem>paramètres d\'un élément dans la liste</elem> <elem>paramètres d\'un élément dans la liste</elem> ... <elem>paramètres d\'un élément dans la liste</elem> </doc>

Nous n'envisageons que les paramètres d'un élément dans la liste qui représentent un ou plusieurs noeuds XML avec des attributs et valeurs possibles car tout le reste est identique pour tous les listes des éléments. Exemple:

<?xml version="1.0" encoding="UTF-8"?> <doc> <elem> <name>dnsadmin</name> <view>main.com</view> <owner>dnsadmin</owner> <level>admin</level> <domains used="0" limit="1000"/> </elem> <elem> <name>dnsuser1</name> <view>dns.com</view> <owner>resel</owner> <level>user</level> <domains used="2" limit="100"/> </elem> </doc>

Liste des paramètres d'un objet (formulaire)

En ce cas le document XML est présenté d’une manière suivante:

<?xml version="1.0" encoding="UTF-8"?> <doc> <elid> un identificateur d\'un objet </elid> paramètres d\'objet </doc>

Nous n'envisageons que les paramètres d'un objet qui représentent un ou plusieurs noeuds XML avec des attributs et valeurs possibles décrivant les propriétés de cet objet. Tout le reste est identique pour tous les listes des éléments. Exemple:

<?xml version="1.0" encoding="UTF-8"?> <doc> <elid>dnsuser1</elid> <name>dnsuser1</name> <level>user</level> <domlimit>100</domlimit> </doc>

Réussite de l'opération (action)

Ce résultat est obtenu lors de la création, modification, suppression, activation ou désactivation d'un objet. Dans ce cas le document XML est présenté d'une manière suivante :

<?xml version="1.0" encoding="UTF-8"?> <doc> <ok/> </doc>

Message d’erreur

Ce résultat est obtenu lors de l'apparition d'une erreur au cours du traitement de votre requête. Dans ce cas le document XML est présentée d'une manière suivante:

<?xml version="1.0" encoding="UTF-8"?> <doc> <error>message d’erreur.</error> </doc>

Cet article vous a-t-il été utile? Oui | Non
Affichages
Outils personnels