Documentation sur les web services

De Maarch // Wiki.

Sommaire 1 Protocole de communication 2 Prérequis pour utiliser le serveur de web services Maarch 3 Accès au catalogue des web services 4 Se connecter à un web service 4.1 Exemple de connexion au web services Maarch en PHP avec l'utilisateur Bernard Blier  5 Utiliser un web service 6 Comment déclarer un nouveau web service Maarch 6.1 Exemple : (dans « core/class/ws.php ») 6.2 Déclaration du tableau complexe « users »  6.3 La fonction « get » dans users_controler.php 7 Comment écrire un nouveau web service Maarch

Protocole de communication

Un service web est un programme informatique permettant la communication et l'échange de données entre applications et systèmes hétérogènes dans des environnements distribués. Il s'agit donc d'un ensemble de fonctionnalités exposées sur internet ou sur un intranet, par et pour des applications ou machines, sans intervention humaine, et de manière synchrone.

Prérequis pour utiliser le serveur de web services Maarch

Pour pouvoir utiliser les web services Maarch, il faut :

• Un serveur web (apache,...) avec PHP5
• Maarch Entreprise installé sur le même ou sur un autre serveur (Guide d'installation de Maarch Entreprise )
• Installer la librairie PEAR SOAP-0.12.0 (exemple pour windows : C:\xampp\php\pear install SOAP-0.12.0)
• Créer une zone de stockage (docserver) pour les versements de documents via "web_services"
• Indiquer à la base de données où se trouve la zone de stockage "web_services"

Toutes les installations sont expliquées dans le Tutoriel sur les web services

Accès au catalogue des web services

Le catalogue des web services Maarch est accessible depuis l'addresse : http://127.0.0.1:80/maarch_entreprise/ws_server.php?WSDL si votre Maarch Entreprise est installé sur votre poste, sinon il va falloir personnaliser cette adresse. Le serveur demande un nom d'utilisateur et un mot de passe Maarch. Prenons par exemple bblier/maarch, ou tout utilisateur déclaré dans Maarch.

• Maarch Entreprise n'est pas sur votre ordinateur, il faut alors modifier le « http://127.0.0.1 » par l'addresse ip du serveur où est installé Maarch Entreprise ;
• Le serveur web où est installé Maarch Entreprise n'écoute pas sur le port 80, il faut alors modifier le « :80 » par le port sur lequel est installé le serveur web d'installation de Maarch ;

• Maarch Entreprise n'est pas installé à la racine du serveur web, il faut alors préciser le chemin avant "/maarch_entreprise/ws_server.php?WSDL";

Par exemple, si Maarch Entreprise est installé dans le dossier « SAE » sur un serveur d'adresse ip « 192.168.1.45 » qui écoute sur le port « 8080 » ; L'adresse d'accès au catalogue devient : http://192.168.1.45:8080/SAE/maarch_entreprise/ws_server.php?WSDL

Se connecter à un web service

Pour vous connecter aux web services Maarch Entreprise, vous devez utiliser un login/mot de passe utilisateur de Maarch Entreprise.

Il existe par défaut dans l'installation de Maarch Entreprise des utilisateurs, comme Bernard Blier. Son login est « bblier » et son mot de passe est « maarch ».

Les exemples de clients de web services sont en PHP mais peuvent bien entendu être dans un autre langage de développement (JAVA, .NET, Python, ...).

Exemple de connexion au web services Maarch en PHP avec l'utilisateur Bernard Blier 

<?php
require('SOAP/Client.php');
$proxy = array('user' => 'bblier', 'pass' => 'maarch', 'timeout' => '600');
$wsdl = new SOAP_WSDL('http://127.0.0.1/maarch_entreprise/ws_server.php?WSDL', $proxy, false);
$client = $wsdl->getProxy();

Utiliser un web service

Exemple de client de web service permettant de visionner un document de la table « res_x » de Maarch Entreprise :

<?php 
require('SOAP/Client.php');
$proxy = array('user' => 'bblier', 'pass' => 'maarch', 'timeout' => '600');
$wsdl = new SOAP_WSDL('http://127.0.0.1/maarch_entreprise/ws_server.php?WSDL', $proxy, false);
$client = $wsdl->getProxy();


$viewID = 450; //ID du document à afficher


$fileContentArray = array();
$fileContentArray = $client->viewResource( $viewID, 'res_x', 'adr_x', true);
if($fileContentArray->status == "ok") {
    $fileContent = base64_decode($fileContentArray->file_content);
    $Fnm = $fileContentArray->tmp_path.DIRECTORY_SEPARATOR.rand() ."_". md5($fileContent) .".". strtolower
($fileContentArray->ext);
    $inF = fopen($Fnm, "w");
    fwrite($inF, $fileContent);
    fclose($inF);
    header("Pragma: public");
    header("Expires: 0");
    header("Cache-Control: must-revalidate, post-check=0, pre-check=0");
    header("Cache-Control: public");
    header("Content-Description: File Transfer");
    header("Content-Type: ".strtolower($fileContentArray->mime_type));
    header("Content-Disposition: inline; filename=". basename('maarch.'.strtolower($fileContentArray->ext)) 
.";");
    header("Content-Transfer-Encoding: binary");
    readfile($Fnm);
    exit();
}

Comment déclarer un nouveau web service Maarch

Les web services Maarch Entreprise se déclarent dans les fichiers « ws.php ».

Il en existe plusieurs dans Maarch Entreprise :

• dans « core/class/ »
• dans « apps/maarch_entreprise/class/ »
• et dans certains modules ( « basket », « life_cycle »)
  • basket : « modules/basket/class/ »
  • life_cycle : « modules/life_cycle/ » </nowiki>

Exemple : (dans « core/class/ws.php »)

$SOAP_dispatch_map['userGet'] = array(
    'in'  => array('user' => 'string'),
    'out' => array('out' => '{urn:MySoapServer}users'),
    'method' => "core#users::getWs"
);

Déclaration du tableau complexe « users » 

$SOAP_typedef['users'] = array(
    'user_id'=>'string',
    'password'=>'string',
    'firstname'=>'string',
    'lastname'=>'string',
    'phone'=>'string',	
    'mail'=>'string',
    'loginmode'=>'string'
);

La fonction « get » dans users_controler.php

public function get($userId, $compWhere='', $canBeDisabled=false)
    {
    self::set_foolish_ids(array('user_id', 'docserver_location_id'));
    self::set_specific_id('user_id');
    $user = self::advanced_get($userId, USERS_TABLE, $compWhere);

    if (isset($user)
    && ($user->__get('status') == 'OK' 
    || $user->__get('status') == 'ABS')
    ) {
        return $user;
    } else {
        return null;
    }
}

Comment écrire un nouveau web service Maarch

Il est possible d'écrire ses propres web services dans Maarch Entreprise, pour cela vous devez :

• Écrire la fonction dans un des fichiers « …...._controler.php »
• Écrire la dispatch_map de la fonction dans un des ws.php
• Déclarer les tableaux complexes dans le ws.php (si il y en a dans votre dispatch_map)
  

Vous retrouvez alors votre web service dans le catalogue WSDL.

• Il ne vous reste plus qu'à écrire le ou les clients adaptés pour utiliser votre web service.

Pour en savoir plus : Tutoriel_sur_les_web_services.