mercredi 6 avril 2011

Karotz API Web - Tuto de base


API REST Web : Développer une application en mode Web

1 - On passe sur les créations de comptes, accès au lab, etc... acquis à ce stade sur karotz.com.

2 - Créer une application dans le Lab et noter la clé publique de l'appli générée.

3 - Copier et créer le descripteur ci-dessous (cf plus bas descriptor.xml), le zipper avec son fichier screen.xml, charger le tout -bouton "Envoyer le code"-, rendre l'application privée et la tester (acheter et installer sur le kz) -bouton "Tester"-.

Deux tags importants : <deployment> ("external" pour un site web) et <callback> qui indique l'url du site web -le vôtre- qui va récupérer les informations de session interactiveid et installid.

Ne pas oublier de modifier les tags <apikey> et <callback> avec les bonnes informations...

3b - Ftposter le script php de test sur votre serveur (cf plus bas kztest.php).

4 - Dans votre navigateur, allez à http://www.karotz.com/authentication/run/karotz/votre_api_key_récupérée_au_2
C'est aussi ce lien que l'on pourra indiquer sur un site web ou dans un mail.

5 - L'url amène alors sur karotz.com qui requiert une identification -email+pass de son compte Karotz.com-...

6 - ... qui à son tour -après validation de l'identification- renvoie sur l'url de callback saisie dans le descripteur -soit ici http://mon_site_web/kztest.php- AVEC les fameux interactiveID et installID passés en paramètres !

Conclusion : La -grosse- différence avec les Nabz est que désormais il faut s'identifier... fini le temps où il suffisait de coller un "serialnumber/token" dans la requête ! Pour le coup, cela va sembler moins ouvert à certains ;-)) ne serait-ce que pour envoyer un message à son(sa) voisin(e)... A confirmer. Mais beaucoup de possibilités offertes... à nos cla(p)viers !

NB : Après avoir énoncé son texte ou bougé les oreilles, la session peut rester activée -si l'ordre "stop" n'a pas été traité correctement pour une raison quelconque. Le Karotz clignote alors en blanc. Lui cliquer (rapidement) 3 fois sur la tête afin de lui faire reprendre ses esprits... ou attendre 15 minutes -délai actuel du timeout-.

Descripteur descriptor.xml : peut sans doute être réduit, certaines infos n'ayant pas d'intérêt pour une application "externe". Finalement le tag <api_key> n'est pas obligatoire.
 <descriptor> <name>WWW</name>
<apikey>votre_api_key_récupérée_au_2</apikey>
<version>1.0</version>
<accesses>
<access>ears</access>
<access>led</access>
<access>tts</access>
</accesses>
<editor>Bunny</editor>
        <asrName>webapi</asrName>
<deployment>external</deployment>
<interruptible>true</interruptible>
<awake>true</awake>
<callback>http://mon_site_web/kztest.php</callback>
</descriptor>
Paramètres screen.xml
<screen nanoTrigger="false"
permanentTrigger="false"
scheduledTrigger="false"
scheduledDateTrigger="false"
voiceTrigger="false">
<button label="Cliquez-ici pour lancer Mon_Appli..." link="http://www.karotz.com/authentication/run/karotz/votre_api_key_récupérée_au_2" />
</screen>
Script kztest.php
<?php
 # Wizz.cc
 # http://www.karotz.com/authentication/run/karotz/YOUR-APIKEY

 echo 'Referer:'.$_SERVER['HTTP_REFERER'].'<br>';

 $interID = $HTTP_GET_VARS['interactiveid'];
 echo 'interactiveID = ['.$interID.']<br>';
 echo 'installID = ['.$HTTP_GET_VARS['installid'].']<br>';

 # Play with Karotz
 #
 $curl = curl_init(); if (!$curl) exit;

 curl_setopt($curl, CURLINFO_HEADER_OUT, true);
 curl_setopt($curl, CURLOPT_HEADER, false);
 curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

 # Parler : Quoi de neuf Docteur ?
 curl_setopt($curl, CURLOPT_URL, 'http://www.karotz.com/api/karotz/tts?action=speak&lang=FR&text=quoi%20de%20neuf%20docteur&interactiveid='.$interID);
 $result = curl_exec($curl);
 # Erreur
 if (curl_errno($curl)) { $curl_error = curl_error($curl); echo '<p>Err>&nbsp;'.$curl_error.'</p>'; exit; }

 echo '<hr>';
 $curl_info = curl_getinfo($curl);
 echo '<ul><li>Request time:&nbsp;'.$curl_info['total_time'].' sec.'
. '<li>Request header:&nbsp;'.$curl_info['request_header']
. '<li>Bytes transfered:&nbsp;'.number_format($curl_info['size_download'], 0, '', ' ')
.'</ul>';

 # Decode Xml response from server
 #
 $code = '';
 if ($result!='') try {
   $xml = new SimpleXMLElement($result);
   echo '<p>Speak response:</p><pre>'; print_r($xml); echo '</pre>';
   # Le code retourné
   $code = $xml->response->code;
 } catch(Exception $e) { echo '<b>Error</b>: <font color="red">'.$e->getMessage().' (severity '.$e->getCode().')</font><br>'; }
 echo '<hr>';
 if ($code=='OK') echo '<font color="green">Cool !</font><br>';

 # Bouger les oreilles
 curl_setopt($curl, CURLOPT_URL, 'http://www.karotz.com/api/karotz/ears?left=20&right=-30&interactiveid='.$interID);
 curl_exec($curl);

 # Flash
 curl_setopt($curl, CURLOPT_URL, 'http://www.karotz.com/api/karotz/led?action=light&color=FF00FF&interactiveid='.$interID);
 curl_exec($curl);

 # Libérer le Kz au bout de 5 sec
 sleep(5);
 curl_setopt($curl, CURLOPT_URL, 'http://www.karotz.com/api/karotz/interactivemode?action=stop&interactiveid='.$interID);
 curl_exec($curl);

 curl_close($curl);
?>
Résultat :
Referer:http://www.karotz.com/login
interactiveID = [3a0ce7bc-c169-4266-ab3d-0c51d564d651]
installID = [7319bdb4-169d-4181-8cd4-fea9de4f4e9a]

Request time: 0.395879 sec.
Request header: GET /api/karotz/tts?action=speak&lang=FR&text=quoi%20de%20neuf%20docteur&interactiveid=3a0ce7bc-c169-4266-ab3d-0c51d564d651 HTTP/1.1 Host: www.karotz.com Accept: */*
Bytes transfered: 234

Speak response:
SimpleXMLElement Object
(
    [id] => eb310b17-a77e-4cfb-ad21-a99c114a52eb
    [correlationId] => 2e6fa6a2-f2a8-4795-b20c-c6366c001adb
    [interactiveId] => 3a0ce7bc-c169-4266-ab3d-0c51d564d651
    [response] => SimpleXMLElement Object
        (
            [code] => OK
        )
)

1 commentaire:

  1. Bonjour,
    merci pour toutes vos infos sur le karotz, ca aide vraiment bien.
    J'ai testé plusieurs approches de dev, et celles ci me parait la plus fonctionnelle, cependant des que je lui demande de dire qq chose, l'appel de la fonction stop, lui fait redire la meme chose.
    Je précise que j'ai bien l'instruction speak une seule fois.

    Si par exemple, je saute l'instuction stop, ca marche, mais du coup, il reste en veille, donc c est pas génial non plus.
    C'est comme si il fallait caller le delai de sleep exactement sur la durée de prononciation de la phrase.

    Auriez vous une idée du bug ?

    Merci
    yoyoz

    RépondreSupprimer