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