Comment fonctionner sous API

De ISPWiki.

(Redirigé depuis API result is "list")

Ici on traite les exemples de la connexion aux fonctions d'ISPmanager avec l'emploi des différents langages de programmation et des commandes shell. L'un des exemples c'est la fonction d'affichage de la liste des sites. Toutes les autres fonctions doivent être appelées de la même façon. Dans ces exemples on n'examine que la connexion locale. Pour se connecter à distance à ISPmanager il est nécessaire d'utiliser le protocole HTPPS au lieu de HTTP et de s'identifier en s'adressant à URL.

https://Adresse IP/manager/ispmgr?out=xml&func=auth&username=nom_d'utilisateur&password=mot de passe

Lors du fonctionnement sous autres produits il faut indiquer le nom approprié dans l'adresse URL au lieu de ispmgr, c'est-à-dire billmgr, vdsmgr et etc.

Sommaire

Modes d'identification

Identification à l'aide de l'id de session

Cette méthode convient le plus à l'utilisation du panneau d'administration via navigateur. Pour appeler une fonction ISPmanager il est nécessaire de visiter l'URL suivante, en utilisant des fonctions correspondantes des langages de programmation ou des commandes shell.


https://Adresse IP/manager/ispmgr?auth=numéro_session&out=xml&func=fonction&paramètre1=valeur&paramètre2=valeur...

Pour s'identifier il faut visiter l'url suivante:

https://Adresse IP/manager/ispmgr?out=xml&func=auth&username=nom_d'utilisateur&password=mot de passe 

Après cela ISPmanager retourne le message d'erreur ou le document XML suivant:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
<auth id="numéro de session"/>
</doc>

Après cela vous devrez spécifier cet id de session dans le paramètre auth lors de chaque requête vers ISPmanager. L'id de session est valide pendant 30 minutes. A l'expiration de ce délai vous devrez vous identifier à nouveau.

Identification avec authinfo

Cette méthode d'identification convient pour la connexion distante au panneau de contrôle. Pour appeler une fonction de ISPmanager il est nécessaire d'ajouter un paramètre supplémentaire authinfo où vous devez spécifier le nom d'utilisateur et le mot de passe sous lesquels vous souhaitez exécuter une opération, par exemple

https://Adresse IP/manager/ispmgr?authinfo=admin1:mypasswd&out=xml&func=fonction&paramètre1=valeur&paramètre2=valeur...

Vous devez envoyer le paramètre authinfo lors de chaque requête vers le pannneau de contrôle.


Identification à l'aide des adresses IP de confiance

Cette méthode d'identification convient surtout pour la connexion distante au panneau de contrôle, quand tous les appels proviennent d'une certaine adresse IP. On peut citer en exemple, le serveur sur lequel est situé le système de billing qui appelle périodiquement le panneau d'administration pour obtenir l'information sur le trafic, l'espace disque, le nombre de sites etc. Cette méthode permet de refuser l'identification, si spécifier la ligne suivante dans le fichier de configaration du panneau d'administration /usr/local/ispmgr/etc/ispmgr.conf следующую строку:

TrustIP  adresse IP utilisateur

Au lieu de "adresse IP" il faut spécifier l'adresse du serveur depuis lequel les requêtes seront envoyées vers le panneau de contrôle. Au lieu de "utilisateur" - le nom de l'utilisteur avec les droits duquel les opérations seront exécutées dans le panneau de contrôle. Ce paramètre est optionnel; sans lui les requêtes seront traitées avec les droits root.

Identification et la connexion locale aux fonctions ISPmanager

Cette méthode d'identification est préférable quand il s'agit de l'appel local au panneau d'administration depuis des programmes ou des scripts externes, par exemple la connexion au panneau d'administration depuis son script qui est exécuté avec une certaine périodicité à l'aide de cron. Dans ce cas le panneau d'administration fixe lui-même l'UID du processus qui a envoyé une requête et le traite avec les droits d'un utilisateur qui a cet UID. Aucune identification supplémentaire n'est pas requise.

HTTP ou HTTPS?

HTTP n'est pas un protocole sécurisé, donc il est dangereux de transmettre des mots de passe ou des numéros de sessions par ce protocole. C'est pourquoi le panneau de contrôle controle que l'adresse IP d'une machine appelant corresponde à celle du serveur où il est installé, et si ces adresses sont identiques (en cas d'appel local des fonctions VDSmanager), il permet d'utiliser le protocole HTTP. Sinon, le protocole HTTPS seul peut être utilisé et lors de la tentative de connexion au panneau de contrôle par protocole HTTP le message d'erreur sera retourné.


Appel des fonctions d'ISPmanager avec les droits d'un autre utilisateur

Pour appeler une fonction d'ISPmanager avec les droits d'un autre utilisateur il faut ajouter un paramètre supplémentaire su=nom_utilisateur à l'URL. L'administrateur du serveur peut se connecter aux fonctions avec les droits de n'importe quels utilisateurs et l'administrateur de site ne peut le faire qu'avec les droits des utilisateurs de son site. Pour tous les autres c'est interdit.

Comment obtenir la liste des domaines WWW dans ISPmanager

Commande fetch

fetch -q -o - "http://Adresse IP/manager/ispmgr?out=xml&func=wwwdomain"

Commande curl

curl -k -s "http://Adresse IP/manager/ispmgr?out=xml&func=wwwdomain"


Langage Perl

Il est nécessaire d'installer la librairie LWPpour s'adresser à URL et XML::LibXML pour traiter les documents XML.

#!/usr/bin/perl -w
use CGI::Carp qw(fatalsToBrowser);
print "Content-type: text/html\n\n";

use LWP::UserAgent;
use XML::LibXML;

my $result;

# Nous créons un pseudo-navigateur qui "ferra semblant d'etre" MSIE et envoyons la requête
$ua = LWP::UserAgent->new;
$ua->agent("Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)");
my $req = HTTP::Request->new(POST => 'https://Adresse IP/manager/ispmgr');

$req->content("authinfo=login:mot de passe&out=xml&func=wwwdomain");

my $res = $ua->request($req);

# Puis nous vérifions le résultat
if ($res->is_success) {
	$result = $res->content;
} else {
	die $res->status_line."\n";
}

# Maintenant la variable  $result contient le document XML avec la liste des sites
#  ou le message d'erreur

my $parser = XML::LibXML->new();
my $doc = $parser->parse_string( $result );
my $root = $doc->documentElement();

# Nous obtenons la liste des noms des sites
my @sites = ();
for( $root->findnodes( "elem/name" ) ){
	push @sites, $_->textContent;
}

# Enfin nous affichons le résultat à l'écran
for( sort @sites ){
	print $_."<br>\n";
}


Language PHP

Le language PHP donne la possibilité de travailler avec URL qu'avec les fichiers standards. Pour traiter les documents XML, il faut utiliser la librairie DOM XML.

<?php
   $result = "";
   $fh = fopen( "http://127.0.0.1/manager/ispmgr?out=xml&func=wwwdomain", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );

   // Maintenant la variable $result contient le document XML avec la liste des sites WWW,
   // ou le message d'erreur

   if( $doc = domxml_open_mem( $result ) ){
      $root = $doc->document_element();
      for( $elem = $root->first_child(); $elem; $elem = $elem->next_sibling() ){
         for( $node = $elem->first_child(); $node; $node = $node->next_sibling() ){
            if( $node->node_name() == "name" ){
               echo $node->get_content();
               echo "\n";
            }
         }
      }
   }
?>

Language Python On utilise la librairie urllib2 pour les requêtes via URL. Pour traiter les documents XML, il faut utiliser la librairie xml.dom.minidom.

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from urllib2 import urlopen
from xml.dom import minidom

print "Content-type: text/html\n\n"
res = urlopen('http://127.0.0.1/manager/ispmgr?func=wwwdomain&out=xml')

# Maintenant la variable  res contient le document XML avec la liste des sites
# ou le message d'erreur

xmldoc = minidom.parse(res)

# On obtient la liste des noms de domaines WWW et affiche le résultat à l'écran

for node in xmldoc.getElementsByTagName('elem'):
        for name in node.getElementsByTagName('name'):
                print ('%s<br>' % name.firstChild.nodeValue)

Pour obtenit l'information lors de la création des scripts, veuillez parcourir des logs des panneaux d'administration, par exemple, /usr/local/ispmgr/var/ispmgr.log. Si vous réalisez cette action via le panneau d'administration manuellement, il peut obtenir la liste des fonctions API et leurs paramètres.

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

ISPmanager 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 d' ISPmanager 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 requete. 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 voyez à peu près la chose suivante:

# fetch -qo - "http://localhost/manager/ispmgr?func=wwwdomain&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elem>
		<name>foo.org</name>
		<owner>user</owner>
		<ssl/>
		<php/>
		<ssi/>
	</elem>
	<elem>
		<name>mydomain.com</name>
		<owner>user2</owner>
		<php/>
		<cgi/>
	</elem>
	<elem>
		<name>rotate.com</name>
		<owner>alm</owner>
		<ssl/>
		<php/>
	</elem>
	<elem>
		<name>test.com</name>
		<owner>john</owner>
		<php/>
		<cgi/>
	</elem>
	<elem>
		<name>test.net</name>
		<owner>user</owner>
	</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://127.0.0.1/manager/ispmgr?func=wwwdomain.edit&elid=mydomain.com&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elid>mydomain.com</elid>
	<domain>mydomain.com</domain>
	<alias>www.mydomain.com</alias>
	<ip>123.45.67.89</ip>
	<owner>user</owner>
	<admin>webmaster@mydomain.com</admin>
	<index>index.php index.htm</index>
	<php>phpcgi</php>
	<cgi/>
</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://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok>restart</ok>
</doc>

ou le message d'erreur

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>abrakadabra not found.</error>
</doc>

La sortie des résultats d'exécution des fonctions d' ISPmanager 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 requete. 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 à peu près la chose suivante:

# fetch -qo - "http://localhost/manager/ispmgr?func=wwwdomain&out=text"
name=foo.org owner=user ssl php ssi
name=mydomain.com owner=user2 php cgi
name=rotate.com owner=alm ssl php
name=test.com owner=john php cgi
name=test.net owner=user

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, rvant les paramètres du site vous voyez:


# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.edit&elid=mydomain.com&out=text"
elid=mydomain.com
domain=mydomain.com
alias=www.mydomain.com
ip=123.45.67.89
owner=user
php=phpcgi
admin=webmaster@mydomain.com
index=index.php index.htm
cgi

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://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=text"
OK


ou le message d'erreur

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=text"
ERROR: abrakadabra not found.


L'ordre de la description des fonctions d'ISPmanager

La description des fonctions d'ISPmanager est la suivante:

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

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).

Dans ce cas le document XML est le suivant:

<?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>foo.org</name>
		<admin>foo_admin</admin>
		<php/>
		<ssi/>
		<user used="1" limit="10"/>
		<disk used="0" limit="10"/>
		<traf used="3542" limit="8192"/>
	</elem>
	<elem>
		<name>example.com</name>
		<admin>example</admin>
		<cgi/>
		<php/>
		<ssi/>
		<frp/>
		<user used="5" limit="50"/>
		<disk used="39" limit="50"/>
		<traf used="1084" limit="4096"/>
	</elem>
</doc>

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

Dans ce cas le document XML est le suivant:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elid>id d'un objet</elid>
	paramètres d'un 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>example.com</elid>
	<name>example.com</name>
	<gid>1001</gid>
	<alias>www.example.com test.example.com</alias>
	<cgi/>
	<phptype>phpcgi</phptype>
	<ssi/>
	<frp/>
	<sslport>443</sslport>
	<alluser>50</alluser>
	<shelluser>5</shelluser>
	<domain>1</domain>
	<base>3</base>
	<traf>4096</traf>
	<disklimit>50</disklimit>
</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 le suivant:

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

S'il nécessaire de redémmarer le serveur web alors:

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

Pour redémarrer le serveur web il faut visiter cette URL:

http://IP-адрес/manager/ispmgr?out=xml&func=restart

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 le suivant:

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

On appele les fonctions d'ISPmanager de PHP

Le script doit être placé dans la cataloque suivante /usr/local/ispmgr/cgi pour que cela fonctionne correctement.

function send_str($socket, $str) {
       $binarydata = pack("L", strlen($str));
       socket_write($socket, $binarydata, 4);
       socket_write($socket, $str);
}
function query($command) {
       $socket=socket_create(AF_UNIX, SOCK_STREAM, 0);
       socket_connect($socket, "/tmp/ispmgr.sock");
       $sessid = substr(strrchr($_COOKIE['ispmgr4'], ":"), 1);
       send_str($socket, "REQUEST_METHOD=GET");
       foreach ($_SERVER as $key => $value)
               if ($key!="REQUEST_METHOD" && $key!="QUERY_STRING")
                       send_str($socket, $key."=".$value);
       send_str($socket, "QUERY_STRING=".$command."&auth=".$sessid);
       send_str($socket, "");
       while($r=socket_read($socket, 1024, PHP_BINARY_READ))
               $res .= $r;
       socket_close($socket);
       return $res;
}
Cet article vous a-t-il été utile? Oui | Non
Outils personnels