alexa skill kit

Kit de compétences Alexa

Bibliothèque pour le développement sans effort de compétences Alexa avec AWS Lambda.

Installation	? Comment ça marche	? Usage	Référence API	? Comment contribuer	⚖️ Licence

Installation

Alexa Skill Kit est disponible en tant que module Node.js sur NPM. Pour l'installer, exécutez la commande suivante dans un projet Node.js existant :

npm install alexa-skill-kit --save

Comment ça marche

Usage

Alexa Skill Kit est une bibliothèque qui simplifie le développement d'Alexa Skills avec Node.js et AWS Lambda. Il ne nécessite aucun style de déploiement spécifique, il peut fonctionner avec des fonctions Lambda créées manuellement, un déploiement via Claudia.js, etc.

Puisque je recommande Claudia.js en raison de sa simplicité, tous les exemples suivants l'utiliseront. Vous pouvez l'obtenir auprès de NPM ici : npmjs.com/package/claudia.

Après avoir installé l'Alexa Skill Kit de NPM, exigez-le dans votre code :

 const alexaSkillKit = require ( 'alexa-skill-kit' )

ou avec la syntaxe import * :

 import alexaSkillKit from 'alexa-skill-kit'

* La syntaxe import n'est pas prise en charge dans Node.js, vous devez utiliser une bibliothèque supplémentaire comme Babel pour la faire fonctionner.

Après l'avoir demandé, vous devez simplement transmettre l'événement et le contexte de la fonction Lambda, à côté de event et function , vous devez transmettre une fonction de gestionnaire comme dernier paramètre.

Par exemple:

 const alexaSkillKit = require ( 'alexa-skill-kit' )

exports . handler = function ( event , context ) {
  alexaSkillKit ( event , context , parsedMessage => {
    // Do something
  } )
}

Comment répondre

Alexa Skill Kit simplifie la réponse aux demandes Alexa. Vous pouvez faire plusieurs choses :

| Répondre avec un simple texte | ? Répondre avec un objet | ? Réponses plus complexes | ⏳ Réponses asynchrones | | ----- | ----- | ----- | ----- | ----- |

Continuez à lire et tous seront expliqués ci-dessous.

Répondre par un simple texte

Si vous souhaitez qu'Alexa réponde avec un texte simple, il vous suffit de renvoyer le texte dans une fonction de gestionnaire. Alexa Skill Kit enveloppera le texte dans un objet valide.

Par exemple:

 const alexaSkillKit = require ( 'alexa-skill-kit' )

exports . handler = function ( event , context ) {
  alexaSkillKit ( event , context , parsedMessage => {
    return 'Hello'
  } )
}

Un exemple ci-dessus répondra à Alexa avec l'objet suivant :

{
  "version" : " 1.0 " ,
  "response" : {
    "shouldEndSession" : true ,
    "outputSpeech" : {
      "type" : " PlainText " ,
      "text" : " Hello "
    }
  }
}

Comme vous pouvez le voir, la session sera fermée par défaut. Pour garder la session ouverte ou pour répondre à une demande plus complexe, vous pouvez envoyer un objet à la place du texte.

Répondre avec un objet

Si vous souhaitez garder la session ouverte ou si vous souhaitez renvoyer quelque chose de plus qu'un simple discours de sortie, vous pouvez envoyer un objet et Alexa Skill Kit ne le modifiera pas.

Par exemple:

 const alexaSkillKit = require ( 'alexa-skill-kit' )

exports . handler = function ( event , context ) {
  alexaSkillKit ( event , context , parsedMessage => {
    return {
      version : '1.0' ,
      response : {
        shouldEndSession : false ,
        outputSpeech : {
          type : 'PlainText' ,
          text : 'Hello'
        } ,
        card : {
          type : 'Simple' ,
          title : 'Simple Card' ,
          content : 'An example for a simple card reply'
        }
      }
    }
  } )
}

Des réponses plus complexes

Construire des objets manuellement est difficile et ennuyeux. Je recommande d'utiliser le module Alexa Message Builder pour simplifier la création de réponses plus complexes.

Alexa Message Builder est disponible sur NPM et vous pouvez l'ajouter à votre projet avec la commande suivante :

npm install alexa-message-builder --save

Après cela, exigez-le simplement avec Alexa Skill Kit comme ceci :

 const alexaSkillKit = require ( 'alexa-skill-kit' )
const AlexaMessageBuilder = require ( 'alexa-message-builder' )

exports . handler = function ( event , context ) {
  alexaSkillKit ( event , context , parsedMessage => {
    return new AlexaMessageBuilder ( )
      . addText ( 'Hello' )
      . addSimpleCard ( 'Simple Card' , 'An example for a simple card reply' )
      . keepSession ( )
      . get ( )
  } )
}

L'exemple ci-dessus est le même que celui de la section « Répondre avec un objet ».

Pourquoi Alexa Message Builder ne fait pas partie d'Alexa Skill Kit ?

Eh bien, sans véritable raison, Alexa Message Builder a été développé avant Alexa Skill Kit, et ce sont des modules séparés au cas où quelqu'un aurait besoin de l'un d'entre eux sans l'autre.

Réponses asynchrones

Alexa Skill Kit utilise des promesses pour gérer les réponses asynchrones. Pour pouvoir répondre de manière asynchrone, renvoyez simplement la promesse et résolvez-la avec un texte ou un objet et Alexa Skill Kit appliquera les mêmes règles que ci-dessus.

Par exemple:

 const alexaSkillKit = require ( 'alexa-skill-kit' )

exports . handler = function ( event , context ) {
  alexaSkillKit ( event , context , parsedMessage => {
    return fetchSomethingFromTheServer ( )
      . then ( result => doSomethingWithTheResult ( result ) )
      . then ( processedResult => {
        return `Here's an info from the server: ${ processedResult } `
      } )
  } )
}

Alexa Skill Kit répondra avec le texte :

 `Here's an info from the server: ${ processedResult } ` 

Référence API

Alexa Skill Kit ( function ) reçoit les attributs suivants :

• Événement ( object , obligatoire) : un objet non modifié reçu d'Amazon Alexa. Si votre fonction Lambda reçoit un objet qui n'est pas une requête Amazon Alexa valide, elle ne l'analysera pas et votre fonction de gestionnaire ne sera jamais appelée.
• Contexte ( object , obligatoire) — un objet contextuel reçu sur AWS Lambda, il est recommandé de ne pas le modifier, mais Alexa Skill Kit utilisera uniquement les fonctions context.succeed et context.fail , vous pouvez donc transmettre un objet personnalisé qui contient ces deux fonctions à partir d’un objet contextuel d’origine.
• Gestionnaire ( function , obligatoire) : une fonction qui reçoit un événement analysé et renvoie une réponse qui sera transmise à Amazon Alexa.

La fonction de gestionnaire est une fonction qui reçoit un événement analysé et peut renvoyer une chaîne, un objet ou une promesse qui renverra une chaîne ou un objet une fois résolu.

Si vous ne souhaitez pas qu'Alexa réponde, renvoyez simplement null ou ne revenez pas du tout.

L'objet analysé est un objet qui contient les propriétés suivantes :

• type ( string ) - type de requête, il peut s'agir de 'LaunchRequest', 'IntentRequest', 'SessionEndedRequest' ou de l'une des requêtes 'AudioPlayer' ou 'PlaybackController'
• request ( object ) - objet de requête complet de la requête Alexa
• intent : ( object , peut être null ) - objet d'intention de la requête Alexa, si la requête ne contient pas d'intention, cette propriété sera null
• session : ( objet , peut être nul ) - objet de session de la requête Alexa, si la session n'existe pas dans la requête, cette propriété sera null
• sessionAttributes : ( object ) - un objet avec les attributs de session de la requête Alexa, s'ils n'existent pas, cette propriété sera un objet vide ( {} )
• user: ( object ) - objet utilisateur de la requête Alexa, Alexa Skill Kit essaiera de charger l'utilisateur à partir du contexte, puis à partir de la session et enfin, il définira un objet vide si les informations utilisateur ne sont pas trouvées
• originalRequest : ( objet ) - requête Alexa complète, telle que reçue d'AWS Lambda et telle que décrite dans une documentation officielle.

Contribuer

Structure des dossiers

Le corps principal du code se trouve dans le répertoire lib.

Les tests se trouvent dans le répertoire spec et doivent suivre la structure des fichiers sources correspondants. Tous les noms de fichiers de test exécutables doivent se terminer par -spec , ils seront donc automatiquement récupérés par npm test . Tous les fichiers de projet supplémentaires, classes d'assistance, etc. qui ne doivent pas être directement exécutés par le programme d'exécution du test ne doivent pas se terminer par -spec . Vous pouvez utiliser le répertoire spec/helpers pour stocker les helpers Jasmine, qui seront chargés avant l'exécution de tout test.

Exécution de tests

Nous utilisons Jasmine pour les tests unitaires et d'intégration. À moins qu'il n'y ait une raison très impérieuse d'utiliser quelque chose de différent, continuez à utiliser Jasmine pour les tests. Les tests existants se trouvent dans le dossier spec. Voici quelques raccourcis de commandes utiles :

Exécutez tous les tests :

npm test

Exécutez uniquement quelques tests :

npm test -- filter=prefix

Obtenez des rapports hiérarchiques détaillés sur les noms de tests :

npm test -- full

Nous utilisons ESLint pour la cohérence de la syntaxe et les règles de linting sont incluses dans ce référentiel. L'exécution npm test vérifiera également les règles de peluchage. Veuillez vous assurer que votre code ne contient aucune erreur de peluchage avant de soumettre une pull request.

Licence

MIT - Voir LICENCE