Se utilizziamo Node.js o Python per lo sviluppo di skill Alexa abbiamo la possibilità di scegliere la modalità Alexa-hosted che permette di nascondere la complessità della creazione e gestione delle lambda function su AWS. Per questo motivo nei miei corsi utilizzo questa modalità. In questo modo possiamo concentrarci solo sullo sviluppo delle funzionalità della skill.

Per accedere a tutte le potenzialità offerte da AWS per lo sviluppo professionale di skill Alexa è però consigliabile effettuare il deploy della skill direttamente su una lambda function anziché utilizzare il modello hosted. In tal caso il codice è comunque ospitato su una AWS lambda ma non ne abbiamo il controllo diretto. È possibile creare manualmente la risorsa su AWS ed utilizzare l’editor web disponibile nella console di AWS delle lambda function ma non è il metodo che mi sento di consigliare. È preferibile avere il codice e tutti i moduli necessari sul proprio computer ed effettuare il deploy su cloud quando necessario. In questo modo è anche possibile effettuare il versioning per esempio con un repository git.

Il Serverless Framework ci viene in aiuto grazie ad un completo e robusto sistema di deploy che permette, grazie a CloudFormation, di effettuare il deploy non solo delle lambda function ma anche di tutte le risorse necessarie come per esempio autorizzazioni IAM e tabelle DynamoDB.

In questo articolo è dato per scontato che sul computer sia già installata l’ultima versione di Node.js con il relativo sistema di package management npm.

Installazione di serverless framework

Installiamo serverless a livello globale:

sudo npm install -g serverless

Per verificare che l’installazione sia avvenuta con successo si può usare il comando sls –version per ottenere la versione di componenti serverless installati.

Consiglio di installare a livello globale anche due plugin di serverless che utilizzeremo con tutte le skill:

sudo npm install -g serverless-bundle

sudo npm install -g serverless-alexa-skills

Passaggio da Alexa hosted a serverless

Per illustrare il funzionamento del deploy con il Serverless Framework convertiamo la skill Caratteristiche dei segni zodiacali che utilizzo come esempio nei miei corsi da Alexa hosted a codice in locale con deploy con serverless.

Io utilizzo la seguente struttura all’interno della cartella con il codice d cui fare il deploy su AWS lambda:

Il file serverless.yml contiene tutte le informazioni necessarie per effettuare il deploy come i permessi IAM, i database DynamoDB e le funzioni lambda da creare con il relativo codice da caricare.

Il file package.json è il file standard di NodeJS con l’elenco dei moduli node da caricare e della configurazione.

Creare la struttura locale

Crea la struttura di cartella che ho illustrato prima. In questa schermata ci sono i file presenti nell’ambiente Alexa hosted relativa all skill che illustro nel Corso base di sviluppo skill Alexa.

Non siamo obbligati a mantenere la stessa struttura e possiamo organizzare meglio la struttura in modo da prepararci allo sviluppo di skill più complesse con un numero maggiore di file sorgente. Per esempio possiamo inserire il file database.json nella cartella assets, il file util.js nella cartella common ed il file index.js in handlers. Ovviamente bisognerà cambiare il percorso nei riferimenti a database.json e util.js in index.js. Copia anche il contenuto di packege.json nel file locale.

Costruzione file serverless.yml

Vediamo ora la struttura del file serverless.yml, cuore del sistema di deploy con serverless framework.

service:
  name: zodiac-signs-skill

plugins:
  - serverless-bundle
  - serverless-alexa-skills

provider:
  name: aws
  runtime: nodejs14.x
  profile: default
  memorySize: 256
  stage: ${opt:stage, 'dev'}
  region: eu-west-1

custom:
  alexa:
    vendorId: <il tuo ID fornitore>
    skills:
      - id: <id della skill>
        manifest:
          publishingInformation:
            locales:
              it-IT:
                name: Caratteristiche dei segni zodiacali

          apis:
            custom:
              endpoint:
                uri: 'arn:aws:lambda:eu-west-1:{AWS::AccountId}:${self:service.name}-${opt:stage}'
              interfaces: []
              protocolVersion: '3'
          manifestVersion: '1.0'

functions:
  index:
    handler: src/handlers/index.handler
    events:
      - alexaSkill: <id della skill>

I plugin sono elementi aggiuntivi di serverless framework che, in questo caso, consentano la gestione di insiemi(bundle) e consentono la definizione di skill Alexa.

Per ottenere alcuni identificatori necessari nella configurazione devi andare sulla Console di sviluppo di Alexa con il tuo account su: https://developer.amazon.com/alexa/console/ask . Questi gli elementi che sono necessari e dove li puoi recuperare:

• vendorId: si trova nella Console di sviluppo di Alexa selezionando il menu Impostazioni nella barra dei menu della pagina.
• id skill: si trova nella Console di sviluppo di Alexa selezionando il menu Skill nella barra dei menu della pagina. E’ la prima pagina che viene visualizzata quando ti colleghi alla console di sviluppo. Scegli la skill che ti interessa e seleziona Copia ID skill

Installazione moduli Node.js

Si esegue npm per installare i moduli Node.js definiti in package.json

npm install

Se durante lo sviluppo risulta necessario aggiungere moduli node consiglio di utilizzare il comando:

nom install <nome modulo> --save

In questo modo il modulo viene aggiunto in modo automatico alle dipendenze nel file package.json.

Amazon AWS

Per utilizzare i servizio di Amazon AWS come per esempio le funzioni lambda è necessario creare un account. Si può utilizzare la stessa email già utilizzata per Alexa Console ma si tratta di un account separato.

Puoi trovare i dettagli di tutta la procedura qui: https://www.serverless.com/framework/docs/providers/aws/guide/credentials.

Tra i vari modi utilizzabili per configurare le credenziali di accesso as AWS dal proprio computer, io preferisco l’utilizzo dei profili di aws-cli. aws-cli è il comando da terminale che permette la configurazione dei servizi AWS. In questo modo è possibile utilizzare più profile nel caso in cui per esempio si seguano più clienti con diversi account AWS.

Installazione di AWS CLI

Qui si trova la documentazione sull’installazione di AWS CLI: https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html.

Segui la procedura di installazione per il tuo sistema operativo, è anche possibile utilizzare un ambiente Docker per un maggiore isolamento se è necessario.

Dopo l’installazione per verificare che l’ambiente sia stato installato correttamente utilizzare il comando in un terminale:

aws --version

Si ottiene un risultato simile a questo:

aws-cli/2.2.42 Python/3.8.8 Darwin/20.6.0 exe/x86_64 prompt/off

Configurazioni chiavi di accesso

Daremo un accesso amministrativo all’ambiente serverless che abbiamo sul nostro computer. Nel caso questo costituisca un problema è possibile restringere i permessi delle chiavi AWS IAM in modo da fornire solo le autorizzazioni strettamente necessarie.

Per fare questo si devono seguire questi passi:

1. Fare il login sulla console di gestione AWS https://aws.amazon.com e andare sulla pagina Identity & Access Management (IAM)
2. Selezionare Users e quindi Add user. Inserire un nome in modo da collegare questo utente al suo scopo usando per esempio serverless-admin. Abilitare Programmatic access. Selezioneare Next: Permissions. Selezionare Attach existing policies directly. Selezionare AdministratorAccess e quindi Next: Tags e poi Next:Review. A questo punto si può selezionare Create user.
3. Visualizzare e copiare Access key ID e Secret access key in modo da poterle usare successivamente.

Attivare la configurazione di un profilo:

aws configure

Si dovranno inserire le seguenti informazioni:

• AWS Access Key ID. E’ la chiave ottenuta nella configurazione IAM.
• AWS Secret Access Key. E’ la chiave segreta ottenuta nella configurazione IAM.
• Default region name. Si tratta della regione in cui saranno inserite le risorse su AWS. Solitamente utilizzo eu-west-1 che corrisponde all’Irlanda. In passato ho avuto problemi nell’implementazione delle skill Alexa utilizzando altri data center europei quindi di solito utilizzo quello in Irlanda.
• Default output format. Si può evitare di indicarlo direttamente con ENTER

Il profilo viene salvato in ~/.aws/credentials. E’ possibile creare più profili selezionando quello desiderato nell’apposita chiave del file serverless.yml.

Se si vuole dare un nome al profilo che viene creato si può utilizzare il comando:

aws --profile <nome profilo> configure

Deploy

Abbiamo completato tutti i passi di configurazione necessarie e possiamo procedere con il primo deploy con il comando:

sls deploy --verbose --stage dev 

Il primo deploy richiede un tempo leggermente superiore per essere completato. Al termine dell’operazione si può verificare nella Alexa console che l’endpoint è stato modificato in modo automatico nella versione in sviluppo della skill. In questo modo viene indirizzata la lambda function di cui è stato fatto il deploy su AWS. Se si va nella sezione Code si otterrà un messaggio che segnala che quel codice non è più eseguito perché è stato modificato l’endpoint.

Nel caso in cui siano configurate più lambda function, dopo il primo deploy è anche possibile specificare la singola funzione:

sls deploy function -f index --verbose --stage dev

Man mano che si avanti con lo sviluppo si lancia periodicamente il comando di deploy in modo da allineare il codice presente su server.