Un tutoriel pratique
Avec ce tutoriel, je veux vous montrer une façon de créer une compétence Amazon Alexa avec PHP. Ce sera un exemple de compétence très simple, mais cela aidera à comprendre comment cela fonctionne pour mettre en œuvre une nouvelle compétence.
Commençons par le Skill sur le site Amazon. Il sera plus clair pourquoi c’est la bonne façon plus tard. Tout d’abord, nous avons besoin d’un compte de développeur Amazon sur https://developer.amazon.com/. Avec le compte développeur, nous pouvons commencer par le tutoriel sur https://developer.amazon.com/alexa/console/ask. Sur cette page, commencez avec la nouvelle compétence en cliquant sur le bouton “Créer une compétence”.
Tout d’abord, sélectionnez un nom pour la compétence et choisissez une langue.
L’étape suivante consiste à ajouter des informations d’hébergement. Ici, nous sélectionnons une catégorie. Dans notre cas, nous souhaitons créer une « Custom Skill » et lui fournir notre propre serveur PHP.
Ensuite, choisissez le modèle de compétence. Ici, le choix est le modèle “Start from Scratch”.
Maintenant, passez en revue et créez la compétence. La création de la compétence peut prendre quelques secondes.
Les bases de la compétence sont faites. Maintenant, il est temps de développer la compétence. Le navigateur a maintenant ouvert la vue de construction de la compétence. Ici, tout ce qui est nécessaire pour la compétence peut être configuré.
Pour revenir à cette page à partir de la liste des compétences, utilisez le bouton d’édition.
L’étape suivante consiste à configurer le backend où les requêtes doivent être envoyées à l’application PHP (doit être implémentée).
Vient maintenant la partie où vous devez décider comment votre compétence doit fonctionner. Pour cela, vous devez définir vos créneaux (ou utiliser des créneaux déjà définis comme la saisie de nombre, la saisie de date, etc.) et vos intentions. Les intentions sont vos combinaisons logiques de discours d’entrée. Pour le rendre plus clair, voir l’exemple suivant :
Dans ce tutoriel, je vais créer une compétence répondant au texte que l’utilisateur a dit. Donc, à la fin, j’aurai un slot couvrant l’entrée complète de l’utilisateur et une intention de gérer ce slot.
Un autre exemple pourrait être d’avoir deux emplacements :
- Saisie numérique (nom : numéro)
- N’importe quel mot (nom : mot)
Et ensuite, nous définissons une intention avec l’exemple d’énoncé suivant :
Répétez le mot {mot} {nombre} fois.
Cette intention implémenterait la répétition du mot donné plusieurs fois.
Répétez le mot foo trois fois. => toc toc toc
Après cela, nous donnons à la compétence un nom d’invocation. Comment l’utilisateur doit-il appeler Alexa pour ouvrir la Skill ?
Il est important de sauvegarder le modèle afin de ne pas perdre de données. Enregistrez toujours le modèle car il est possible de le construire et de vérifier les erreurs et les avertissements.
L’étape suivante consiste à créer l’emplacement afin que vous puissiez l’utiliser à l’étape suivante de l’intention. Cela ne doit être fait que lorsque les créneaux Amazon donnés ne fonctionnent pas pour le cas d’utilisation.
Créez maintenant une nouvelle intention et utilisez l’emplacement que vous avez créé. Pour cela, ajoutez l’emplacement (et peut-être d’autres emplacements dont vous avez besoin) à l’intention et écrivez quelques exemples d’énoncés. Le nombre d’exemples d’énoncés dont vous avez besoin dépend du cas d’utilisation.
Lorsque les emplacements et les intentions sont configurés, il est utile de consulter l’éditeur JSON. Cet éditeur est un outil vraiment utile. Vous pouvez voir la configuration complète et la modifier ou l’importer.
Certaines erreurs de build peuvent n’être visibles que dans l’éditeur JSON et non dans les interfaces utilisateur. Pour les erreurs de construction, il est toujours utile de regarder le JSON.
La configuration de la partie Amazon est terminée. Commençons par la partie PHP.
Pour cela, je crée un nouveau projet avec composer init . Je recommande d’utiliser composer, mais bien sûr, ce n’est pas nécessaire.
Dans ce tutoriel, j’ai montré l’implémentation de Skill avec la bibliothèque https://github.com/maxbeckers/amazon-alexa-php. Pour ajouter cette bibliothèque au fournisseur, utilisez composer require maxbeckers/amazon-alexa-php .
Ce didacticiel n’a qu’une seule intention personnalisée ; tous les autres sont des intentions Amazon pour lesquelles la bibliothèque a des gestionnaires. Toutes les intentions que la compétence pourrait utiliser sont définies dans le JSON. Là-dedans, vous verrez AMAZON.CancelIntent , AMAZON.HelpIntent , AMAZON.StopIntent , AMAZON.NavigateHomeIntent , AMAZON.FallbackIntent et l’auto-créé MyCustomFulltextIntent .
Les objectifs des intentions d’Amazon sont explicites. Pour l’intention auto-créée, je vais implémenter ce qui suit MyCustomFulltextIntentRequestHandler:
<?phpnamespace Maxbeckers\MyCoolTestskill;
use MaxBeckers\AmazonAlexa\Helper\ResponseHelper;
use MaxBeckers\AmazonAlexa\Request\Request;
use MaxBeckers\AmazonAlexa\Request\Request\Standard\IntentRequest;
use MaxBeckers\AmazonAlexa\RequestHandler\AbstractRequestHandler;
use MaxBeckers\AmazonAlexa\Response\Response;
class MyCustomFulltextIntentRequestHandler extends AbstractRequestHandler
{
/**
* @var ResponseHelper
*/
private $responseHelper;
public function __construct(ResponseHelper $responseHelper, array $supportedApplicationIds)
{
$this->responseHelper = $responseHelper;
$this->supportedApplicationIds = $supportedApplicationIds;
}
public function supportsRequest(Request $request): bool
{
return $request->request instanceof IntentRequest && 'MyCustomFulltextIntent' === $request->request->intent->name;
}
public function handleRequest(Request $request): Response
{
$input = $request->request->intent->slots[0]->value;
return $this->responseHelper->respond($input, true);
}
}
Dans le supportsRequest méthode, il est important de vérifier l’intention. Cela peut être fait en vérifiant le nom de l’intention 'MyCustomFulltextIntent' === $request->request->intent->name .
Le handleRequest La méthode est pour la logique de l’intention. C’est, dans ce cas, très simple car l’intent a un slot (dans tous les cas). Il n’est donc pas nécessaire de vérifier si l’emplacement est défini et de vérifier le nom de l’emplacement correct. Après cela, l’entrée $input est utilisé et répondu directement. Le ResponseHelper rend la vie plus facile.
Finalement, le endSession -flag est ajouté pour mettre fin à la session après cette intention. Cela signifie que la compétence sera fermée automatiquement après cette intention. Dans la plupart des cas, cela n’est ni nécessaire ni utile.
Voici un petit indice sur pourquoi AbstractRequestHandler attend une liste des identifiants d’application pris en charge (identifiants de compétence) : il est possible d’utiliser un gestionnaire pour plusieurs compétences.
Maintenant index.php devrait être créé et ressembler à ceci :
<?phpuse MaxBeckers\AmazonAlexa\Helper\ResponseHelper;
use MaxBeckers\AmazonAlexa\Request\Request;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\CancelRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\FallbackRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\HelpRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\NavigateHomeRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\StopRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\RequestHandlerRegistry;
use MaxBeckers\AmazonAlexa\Validation\RequestValidator;
use Maxbeckers\MyCoolTestskill\MyCustomFulltextIntentRequestHandler;
require '../vendor/autoload.php';
$requestBody = file_get_contents('php://input');
if ($requestBody) {
$alexaRequest = Request::fromAmazonRequest($requestBody, $_SERVER['HTTP_SIGNATURECERTCHAINURL'], $_SERVER['HTTP_SIGNATURE']);
if (!$alexaRequest) {
http_response_code(400);
exit();
}
// Request validation
$validator = new RequestValidator();
$validator->validate($alexaRequest);
// create all needed handlers
$mySkillId = ['amzn1.ask.skill.0000000-0000-0000-0000-00000000000']; // paste your skill id here
$responseHelper = new ResponseHelper();
$myCustomFulltextIntentRH = new MyCustomFulltextIntentRequestHandler($responseHelper, $mySkillId);
$cancelRH = new CancelRequestHandler($responseHelper, 'cancel text', $mySkillId);
$fallbackRH = new FallbackRequestHandler($responseHelper, 'fallback text', $mySkillId);
$navigateHomeRH = new NavigateHomeRequestHandler($responseHelper, 'navigate home text', $mySkillId);
$helpRH = new HelpRequestHandler($responseHelper, 'help text', $mySkillId);
$stopRH = new StopRequestHandler($responseHelper, 'stop text', $mySkillId);
// add handlers to registry
$requestHandlerRegistry = new RequestHandlerRegistry([
$myCustomFulltextIntentRH,
$cancelRH,
$fallbackRH,
$navigateHomeRH,
$helpRH,
$stopRH,
]);
// handle request
$requestHandler = $requestHandlerRegistry->getSupportingHandler($alexaRequest);
$response = $requestHandler->handleRequest($alexaRequest);
// render response
header('Content-Type: application/json');
echo json_encode($response);
} else {
http_response_code(400);
}
exit();
Ici, les gestionnaires des intentions par défaut sont nécessaires et les gestionnaires des intentions personnalisées – dans ce cas, seuls les MyCustomFulltestIntentRequestHandler — est ajouté au registre.
Le registre utilise le modèle de visiteur pour détecter les RequestHandler en utilisant le supportsRequest méthode. Avec le gestionnaire détecté, la demande est gérée à l’aide de la handleRequest méthode.
L’identifiant de la compétence peut être copié à partir de la liste des compétences.
Il est maintenant temps de tester la compétence. Pour cela, le code doit être déployé sur le point de terminaison et défini dans la configuration des compétences du backend Amazon.
L’interface graphique de test est un outil très puissant. Avec cet outil, il est possible de créer des requêtes comme le ferait une vraie Alexa. Lors de l’envoi d’une réponse invalide à partir de votre code, il affichera les erreurs sur votre écran Alexa. Ce sont des possibilités de votre compétence.
Lorsque tous les tests ont réussi, il est temps de distribuer la compétence.
Dans ce didacticiel, je vais ignorer le processus de distribution car il n’est pas directement lié à la création de compétences. Pendant le flux de distribution, il existe des exemples et des icônes définis pour la compétence, etc. Après le flux de distribution, la compétence sera examinée et vérifiée. Cela peut prendre quelques heures.
Votre compétence peut être refusée pendant le processus d’examen d’Amazon. Si cela se produit, Amazon expliquera pourquoi la compétence a été refusée. Corrigez les problèmes mentionnés, puis demandez à nouveau l’examen.
Lorsque votre Skill est publiée, vous pouvez la rechercher sur https://www.amazon.com/, et les utilisateurs d’Alexa peuvent installer votre Skill. Toutes nos félicitations!
Ce tutoriel ne montre que “Comment mettre en œuvre une compétence Amazon Alexa avec PHP” d’une manière très simple. Si vous souhaitez développer une nouvelle compétence, vous devez réfléchir au type de compétence que vous souhaitez développer, car une nouvelle compétence doit offrir une valeur ajoutée à votre groupe cible.
Pour cela, vous aurez besoin de plus d’emplacements, d’intentions et peut-être de la gestion de la session pour envoyer des informations d’une intention à l’autre à l’aide de la session, ou vous avez besoin de données utilisateur.