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> '.$curl_error.'</p>'; exit; }
echo '<hr>';
$curl_info = curl_getinfo($curl);
echo '<ul><li>Request time: '.$curl_info['total_time'].' sec.'
. '<li>Request header: '.$curl_info['request_header']
. '<li>Bytes transfered: '.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
)
)
