Event-driven, Serverless Architectures with AWS Lambda, SQS, DynamoDB, and API Gateway

Posted by Gary A. Stafford in AWS, Bash Scripting, Cloud, DevOps, JavaScript, Python, Software Development on October 4, 2019

Introduction

In this post, we will explore modern application development using an event-driven, serverless architecture on AWS. To demonstrate this architecture, we will integrate several fully-managed services, all part of the AWS Serverless Computing platform, including Lambda, API Gateway, SQS, S3, and DynamoDB. The result will be an application composed of small, easily deployable, loosely coupled, independently scalable, serverless components.

What is ‘Event-Driven’?

According to Otavio Ferreira, Manager, Amazon SNS, and James Hood, Senior Software Development Engineer, in their AWS Compute Blog, Enriching Event-Driven Architectures with AWS Event Fork Pipelines, “Many customers are choosing to build event-driven applications in which subscriber services automatically perform work in response to events triggered by publisher services. This architectural pattern can make services more reusable, interoperable, and scalable.” This description of an event-driven architecture perfectly captures the essence of the following post. All interactions between application components in this post will be as a direct result of triggering an event.

What is ‘Serverless’?

Mistakingly, many of us think of serverless as just functions (aka Function-as-a-Service or FaaS). When it comes to functions on AWS, Lambda is just one of many fully-managed services that make up the AWS Serverless Computing platform. So, what is ‘serverless’? According to AWS, “Serverless applications don’t require provisioning, maintaining, and administering servers for backend components such as compute, databases, storage, stream processing, message queueing, and more.”

As a Developer, one of my favorite features of serverless is the cost, or lack thereof. With serverless on AWS, you pay for consistent throughput or execution duration rather than by server unit, and, at least on AWS, you don’t pay for idle resources. This is not always true of ‘serverless’ offerings on other leading Cloud platforms. Remember, if you’re paying for it but not using it, it’s not serverless.

If you’re paying for it but not using it, it’s not serverless.

Demonstration

To demonstrate an event-driven, serverless architecture, we will build, package, and deploy an application capable of extracting messages from CSV files placed in S3, transforming those messages, queueing them to SQS, and finally, writing the messages to DynamoDB, using Lambda functions throughout. We will also expose a RESTful API, via API Gateway, to perform CRUD-like operations on those messages in DynamoDB.

AWS Technologies

In this demonstration, we will use several AWS serverless services, including the following.

Each Lambda will use function-specific execution roles, part of AWS Identity and Access Management (IAM). We will log the event details and monitor services using Amazon CloudWatch.

To codify, build, package, deploy, and manage the Lambda functions and other AWS resources in a fully automated fashion, we will also use the following AWS services:

Architecture

The high-level architecture for the platform provisioned and deployed in this post is illustrated in the diagram below. There are two separate workflows. In the first workflow (top), data is extracted from CSV files placed in S3, transformed, queued to SQS, and written to DynamoDB, using Python-based Lambda functions throughout. In the second workflow (bottom), data is manipulated in DynamoDB through interactions with a RESTful API, exposed via an API Gateway, and backed by Node.js-based Lambda functions.

Using the vast array of current AWS services, there are several ways we could extract, transform, and load data from static files into DynamoDB. The demonstration’s event-driven, serverless architecture represents just one possible approach.

Source Code

All source code for this post is available on GitHub in a single public repository, serverless-sqs-dynamo-demo. To clone the GitHub repository, execute the following command.

git clone --branch master --single-branch --depth 1 --no-tags \
  https://github.com/garystafford/serverless-sqs-dynamo-demo.git

The project files relevant to this demonstration are organized as follows.

.
├── README.md
├── lambda_apigtw_to_dynamodb
│   ├── app.js
│   ├── events
│   ├── node_modules
│   ├── package.json
│   └── tests
├── lambda_s3_to_sqs
│   ├── __init__.py
│   ├── app.py
│   ├── requirements.txt
│   └── tests
├── lambda_sqs_to_dynamodb
│   ├── __init__.py
│   ├── app.py
│   ├── requirements.txt
│   └── tests
├── requirements.txt
├── template.yaml
└── sample_data
    ├── data.csv
    ├── data_bad_msg.csv
    └── data_good_msg.csv

Some source code samples in this post are GitHub Gists, which may not display correctly on all social media browsers, such as LinkedIn.

Prerequisites

The demonstration assumes you already have an AWS account. You will need the latest copy of the AWS CLI, SAM CLI, and Python 3 installed on your development machine.

Additionally, you will need two existing S3 buckets. One bucket will be used to store the packaged project files for deployment. The second bucket is where we will place CSV data files, which, in turn, will trigger events that invoke multiple Lambda functions.

Deploying the Project

Before diving into the code, we will deploy the project to AWS. Conveniently, the entire project’s resources are codified in an AWS SAM template. We are using the AWS Serverless Application Model (SAM). AWS SAM is a model used to define serverless applications on AWS. According to the official SAM GitHub project documentation, AWS SAM is based on AWS CloudFormation. A serverless application is defined in a CloudFormation template and deployed as a CloudFormation stack.

Template Parameter

CloudFormation will create and uniquely name the SQS queues and the DynamoDB table. However, to avoid circular references, a common issue when creating resources associated with S3 event notifications, it is easier to use a pre-existing bucket. To start, you will need to change the SAM template’s DataBucketName parameter’s default value to your own S3 bucket name. Again, this bucket is where we will eventually push the CSV data files. Alternately, override the default values using the sam build command, next.

Parameters:
  DataBucketName:
    Type: String
    Description: S3 bucket where CSV files are processed
    Default: your-data-bucket-name

SAM CLI Commands

With the DataBucketName parameter set, proceed to validate, build, package, and deploy the project using the SAM CLI and the commands below. In addition to the sam validate command, I also like to use the aws cloudformation validate-template command to validate templates and catch any potential, additional errors.

Note the S3_BUCKET_BUILD variable, below, refers to the name of the S3 bucket SAM will use package and deploy the project from, as opposed to the S3 bucket, which the CSV data files will be placed into (gist).

	# variables
	S3_BUILD_BUCKET=your_build_bucket_name
	STACK_NAME=your_cloudformation_stack_name

	# validate
	sam validate –template template.yaml

	aws cloudformation validate-template \
	–template-body file://template.yaml

	# build
	sam build –template template.yaml

	# package
	sam package \
	–output-template-file packaged.yaml \
	–s3-bucket $S3_BUILD_BUCKET

	# deploy
	sam deploy –template-file packaged.yaml \
	–stack-name $STACK_NAME \
	–capabilities CAPABILITY_IAM \
	–debug

view raw

build-package-deploy.sh

hosted with ❤ by GitHub

After validating the template, SAM will build and package each individual Lambda function and its associated dependencies. Below, we see each individual Lambda function being packaged with a copy of its dependencies.

Once packaged, SAM will deploy the project and create the AWS resources as a CloudFormation stack.

Once the stack creation is complete, use the CloudFormation management console to review the AWS resources created by SAM. There are approximately 14 resources defined in the SAM template, which result in 33 individual resources deployed as part of the CloudFormation stack.

Note the stack’s output values. You will need these values to interact with the deployed platform, later in the demonstration.

Test the Deployed Application

Once the CloudFormation stack has deployed without error, copying a CSV file to the S3 bucket is the quickest way to confirm everything is working. The project includes test data files with 20 rows of test message data. Below is a sample of the CSV file, which is included in the project. The data was collected from IoT devices that measured response time from wired versus wireless devices on a LAN network; the message details are immaterial to this demonstration (gist).

timestamp	location	source	local_dest	local_avg	remote_dest	remote_avg
1559040909.3853335	location-03	wireless	router-1	4.39	device-1	9.09
1559040919.5273902	location-03	wireless	router-1	0.49	device-1	16.75
1559040929.6446512	location-03	wireless	router-1	0.56	device-1	8.31
1559040939.7712135	location-03	wireless	router-1	1.64	device-1	9.4
1559040949.891723	location-03	wireless	router-1	1.18	device-1	9.07
1559040960.011338	location-03	wireless	router-1	0.42	device-1	8.4
1559040970.1319716	location-03	wireless	router-1	1.73	device-1	8.66
1559040980.2533505	location-03	wireless	router-1	0.67	device-1	8.61
1559040990.3816211	location-03	wireless	router-1	1.27	device-1	10.87
1559041000.5105414	location-03	wireless	router-1	1.63	device-1	10.08

view raw

message_data.csv

hosted with ❤ by GitHub

Run the following commands to copy the test data file to your S3 bucket.

S3_DATA_BUCKET=your_data_bucket_name
aws s3 cp sample_data/data.csv s3://$S3_DATA_BUCKET

Visit the DynamoDB management console. You should observe a new DynamoDB table.

Within the new DynamoDB table, you should observe twenty items, corresponding to each of the twenty rows in the CSV file, uploaded to S3.

Drill into an individual item within the table and review its attributes. They should match the rows in the CSV file.

Both the Python- and Node.js-based Lambda functions have their default logging levels set to debug. The debug-level output from each Lambda function is streamed to individual Amazon CloudWatch Log Groups. We can use the CloudWatch logs to troubleshoot any issues with the deployed application. Below we see an example of CloudWatch log entries for the request and response payloads generated from GetMessageFunction Lambda function, which is querying DynamoDB for a single Item.

Event-Driven Patterns

There are three distinct and discrete event-driven dataflows within the demonstration’s architecture

S3 Event Source for Lambda (S3 to SQS)
SQS Event Source for Lambda (SQS to DynamoDB)
API Gateway Event Source for Lambda (API Gateway to DynamoDB)

Let’s examine each event-driven dataflow and the Lambda code associated with that part of the architecture.

S3 Event Source for Lambda

Whenever a file is copied into the target S3 bucket, an S3 Event Notification triggers an asynchronous invocation of a Lambda. According to AWS, when you invoke a function asynchronously, the Lambda sends the event to the SQS queue. A separate process reads events from the queue and executes your Lambda function.

The Lambda’s function handler, written in Python, reads the CSV file, whose filename is contained in the event. The Lambda extracts the rows in the CSV file, transforms the data, and pushes each message to the SQS queue (gist).

	def lambda_handler(event, context):
	bucket = event['Records'][0]['s3']['bucket']['name']
	key = urllib.parse.unquote_plus(
	event['Records'][0]['s3']['object']['key'],
	encoding='utf-8'
	)
	messages = read_csv_file(bucket, key)
	process_messages(messages)

view raw

app.py

hosted with ❤ by GitHub

Below is an example of a message body, part an SQS message, extracted from a single row of the CSV file, and sent by the Lambda to the SQS queue. The timestamp has been converted to separate date and time fields by the Lambda. The DynamoDB table is part of the SQS message body. The key/value pairs in the Item JSON object reflect the schema of the DynamoDB table (gist).

	{
	"TableName": "your-dynamodb-table-name",
	"Item": {
	"date": {
	"S": "2001-01-01"
	},
	"time": {
	"S": "09:01:05"
	},
	"location": {
	"S": "location-03"
	},
	"source": {
	"S": "wireless"
	},
	"local_dest": {
	"S": "router-1"
	},
	"local_avg": {
	"N": "5.55"
	},
	"remote_dest": {
	"S": "device-1"
	},
	"remote_avg": {
	"N": "10.10"
	}
	}
	}

view raw

sqs_message.json

hosted with ❤ by GitHub

SQS Event Source for Lambda

According to AWS, SQS offers two types of message queues, Standard and FIFO (First-In-First-Out). An SQS FIFO queue is designed to guarantee that messages are processed exactly once, in the exact order that they are sent. A Standard SQS queue offers maximum throughput, best-effort ordering, and at-least-once delivery.

Examining the SQS management console, you should observe that the CloudFormation stack creates two SQS Standard queues—a primary queue and a Dead Letter Queue (DLQ). According to AWS, Amazon SQS supports dead-letter queues, which other queues (source queues) can target for messages that cannot be processed (consumed) successfully.

Examining the SQS Lambda Triggers tab, you should observe the Lambda, which will be triggered by the SQS events.

When a message is pushed into the SQS queue by the previous process, an SQS event is fired, which synchronously triggers an invocation of the Lambda using the SQS Event Source for Lambda functionality. When a function is invoked synchronously, Lambda runs the function and waits for a response.

In the demonstration, the Lambda’s function handler, also written in Python, pulls the message off of the SQS queue and writes the message (DynamoDB put) to the DynamoDB table. Although writing is the primary use case in this demonstration, an event could also trigger a get, scan, update, or delete command to be executed on the DynamoDB table (gist).

	def lambda_handler(event, context):
	operations = {
	'DELETE': lambda dynamo, x: dynamo.delete_item(**x),
	'POST': lambda dynamo, x: dynamo.put_item(**x),
	'PUT': lambda dynamo, x: dynamo.update_item(**x),
	'GET': lambda dynamo, x: dynamo.get_item(**x),
	'GET_ALL': lambda dynamo, x: dynamo.scan(**x),
	}

	for record in event['Records']:
	payload = loads(record['body'], parse_float=str)
	operation = record['messageAttributes']['Method']['stringValue']
	if operation in operations:
	try:
	operations[operation](dynamo_client, payload)
	except Exception as e:
	logger.error(e)
	else:
	logger.error('Unsupported method \'{}\''.format(operation))

view raw

app.py

hosted with ❤ by GitHub

API Gateway Event Source for Lambda

Examining the API Gateway management console, you should observe that CloudFormation created a new Edge-optimized API. The API contains several resources and their associated HTTP methods.

Each API resource is associated with a deployed Lambda function. Switching to the Lambda console, you should observe a total of seven new Lambda functions. There are five Lambda functions related to the API, in addition to the Lambda called by the S3 event notifications and the Lambda called by the SQS event notifications.

Examining one of the Lambda functions associated with the API Gateway, we should observe that the API Gateway trigger for the Lambda (lower left and bottom).

When an end-user makes an HTTP(S) request via the RESTful API exposed by the API Gateway, an event is fired, which synchronously invokes a Lambda using the API Gateway Event Source for Lambda functionality. The event contains details about the HTTP request that is received. The event triggers any one of five different Lambda functions, depending on the HTTP request method.

The Lambda code, written in Node.js, contains five function handlers. Each handler corresponds to an HTTP method, including GET (DynamoDB get) POST (put), PUT (update), DELETE (delete), and SCAN (scan). Below is an example of the getMessage handler function. The function accepts two inputs. First, a path parameter, the date, which is the primary partition key for the DynamoDB table. Second, a query parameter, the time, which is the primary sort key for the DynamoDB table. Both the primary partition key and sort key must be passed to DynamoDB to retrieve the requested record (gist).

	exports.getMessage = async (event, context) => {
	if (tableName == null) {
	tableName = process.env.TABLE_NAME;
	}
	params = {
	TableName: tableName,
	Key: {
	"date": event.pathParameters.date,
	"time": event.queryStringParameters.time
	}
	};
	console.debug(params.Key);

	return await new Promise((resolve, reject) => {
	docClient.get(params, (error, data) => {
	if (error) {
	console.error(`getMessage ERROR=${error.stack}`);
	resolve({
	statusCode: 400,
	error: `Could not get messages: ${error.stack}`
	});
	} else {
	console.info(`getMessage data=${JSON.stringify(data)}`);
	resolve({
	statusCode: 200,
	body: JSON.stringify(data)
	});
	}
	});
	});
	};

view raw

app.js

hosted with ❤ by GitHub

Test the API

To test the Lambda functions, called by our API, we can use the sam local invoke command, part of the SAM CLI. Using this command, we can test the local Lambda functions, without them being deployed to AWS. The command allows us to trigger events, which the Lambda functions will handle. This is useful as we continue to develop, test, and re-deploy the Lambda functions to our Development, Staging, and Production environments.

The local Node.js-based, API-related Lambda functions, just like their deployed copies, will execute commands against the actual DynamoDB on AWS. The Github project contains a set of five sample events, corresponding to the five Lambda functions, which in turn are associated with five different HTTP methods and API resources. For example, the event_getMessage.json event is associated with the GET HTTP method and calls the /message/{date}?time={time} resource endpoint, to return a single item. This event, shown below, triggers the GetMessageFunction Lambda (gist).

	{
	"body": "",
	"resource": "/",
	"path": "/message",
	"httpMethod": "GET",
	"isBase64Encoded": false,
	"queryStringParameters": {
	"time": "06:45:43"
	},
	"pathParameters": {
	"date": "2000-01-01"
	},
	"stageVariables": {}
	}

view raw

event_getMessage.json

hosted with ❤ by GitHub

We can trigger all the events from using the CLI. The local Lambda expects the DynamoDB table name to exist as an environment variable. Make sure you set it locally, first, before executing the sam local invoke commands (gist).

	# variables (required by local lambda functions)
	TABLE_NAME=your-dynamodb-table-name

	# local testing (All CRUD functions)
	sam local invoke PostMessageFunction \
	–event lambda_apigtw_to_dynamodb/events/event_postMessage.json
	sam local invoke GetMessageFunction \
	–event lambda_apigtw_to_dynamodb/events/event_getMessage.json
	sam local invoke GetMessagesFunction \
	–event lambda_apigtw_to_dynamodb/events/event_getMessages.json
	sam local invoke PutMessageFunction \
	–event lambda_apigtw_to_dynamodb/events/event_putMessage.json
	sam local invoke DeleteMessageFunction \
	–event lambda_apigtw_to_dynamodb/events/event_deleteMessage.json

view raw

sam-local-invoke.sh

hosted with ❤ by GitHub

If the events were successfully handled by the local Lambda functions, in the terminal, you should see the same HTTP response status codes you would expect from calling the RESTful resources via the API Gateway. Below, for example, we see the POST event being handled by the PostMessageFunction Lambda, adding a record to the DynamoDB table, and returning a successful status of 201 Created.

Testing the Deployed API

To test the actual deployed API, we can call one of the API’s resources using an HTTP client, such as Postman. To locate the URL used to invoke the API resource, look at the ‘Prod’ Stage for the new API. This can be found in the Stages tab of the API Gateway console. For example, note the Invoke URL for the POST HTTP method of the /message resource, shown below.

Below, we see an example of using Postman to make an HTTP GET request the /message/{date}?time={time} resource. We pass the required query and path parameters for date and for time. The request should receive a single item in response from DynamoDB, via the API Gateway and the associated Lambda. Here, the request was successful, and the Lambda function returns a 200 OK status.

Similarly, below, we see an example of calling the same /message endpoint using the HTTP POST method. In the body of the POST request, we pass the DynamoDB table name and the Item object. Again, the POST is successful, and the Lambda function returns a 201 Created status.

Cleaning Up

To complete the demonstration and remove the AWS resources, run the following commands. It is necessary to delete all objects from the S3 data bucket, first, before deleting the CloudFormation stack. Else, the stack deletion will fail.

S3_DATA_BUCKET=your_data_bucket_name
STACK_NAME=your_stack_name

aws s3 rm s3://$S3_DATA_BUCKET/data.csv # and any other objects

aws cloudformation delete-stack \
  --stack-name $STACK_NAME

Conclusion

In this post, we explored a simple example of building a modern application using an event-driven serverless architecture on AWS. We used several services, all part of the AWS Serverless Computing platform, including Lambda, API Gateway, SQS, S3, and DynamoDB. In addition to these, AWS has additional serverless services, which could enhance this demonstration, in particular, Amazon Kinesis, AWS Step Functions, Amazon SNS, and AWS AppSync.

In a future post, we will look at how to further test the individual components within this demonstration’s application stack, and how to automate its deployment using DevOps and CI/CD principals on AWS.

All opinions expressed in this post are my own and not necessarily the views of my current or past employers or their clients.

API Gateway, AWS, DynamoDB, event-driven, Lambda, Python, SAM, Serverless, Serverless Application Model, SQS

2 Comments

Building Asynchronous, Serverless Alexa Skills with AWS Lambda, DynamoDB, S3, and Node.js

Posted by Gary A. Stafford in AWS, Cloud, JavaScript, Serverless, Software Development on July 24, 2018

Introduction

In the following post, we will use the new version 2 of the Alexa Skills Kit, AWS Lambda, Amazon DynamoDB, Amazon S3, and the latest LTS version Node.js, to create an Alexa Custom Skill. According to Amazon, a custom skill allows you to define the requests the skill can handle (intents) and the words users say to invoke those requests (utterances).

If you want to compare the development of an Alexa Custom Skill with those of Google and Azure, in addition to this post, please read my previous two posts in this series, Building and Integrating LUIS-enabled Chatbots with Slack, using Azure Bot Service, Bot Builder SDK, and Cosmos DB and Building Serverless Actions for Google Assistant with Google Cloud Functions, Cloud Datastore, and Cloud Storage. All three of the article’s demonstrations are written in Node.js, all three leverage their cloud platform’s machine learning-based Natural Language Understanding services, and all three take advantage of NoSQL database and storage services available on their respective cloud platforms.

AWS Technologies

The final high-level architecture of our Alexa Custom Skill will look as follows.

Here is a brief overview of the key AWS technologies we will incorporate into our Skill’s architecture.

Alexa Skills Kit

According to Amazon, the Alexa Skills Kit (ASK) is a collection of self-service APIs, tools, documentation, and code samples that makes it possible to add skills to Alexa. The Alexa Skills Kit supports building different types of skills. Currently, Alexa skill types include Custom, Smart Home, Video, Flash Briefing, and List Skills. Each skill type makes use of a different Alexa Skill API.

AWS Serverless Platform

To create a custom skill for Alexa, you currently have the choice of using an AWS Lambda function or a web service. The AWS Lambda is part of an ecosystem of Cloud services and Developer tools, Amazon refers to as the AWS Serverless Platform. The platform’s services are designed to support the development and hosting of highly-performant, enterprise-grade serverless applications.

In this post, we will leverage three of the AWS Serverless Platform’s services, including Amazon DynamoDB, Amazon Simple Storage Service (Amazon S3), and AWS Lambda.

Node.js

AWS Lamba supports multiple programming languages, including Node.js (JavaScript), Python, Java (Java 8 compatible), and C# (.NET Core) and Go. All are excellent choices for writing modern serverless functions. For this post, we will use Node.js. According to Node.js Foundation, Node.js is an asynchronous event-driven JavaScript runtime built on Chrome’s V8 JavaScript engine.

In April 2018, AWS Lamba announced support for the Node.js 8.10 runtime, which is the current Long Term Support (LTS) version of Node.js. Node 8, also known as Project Carbon, was the first LTS version of Node to support async/await with Promises. Async/await is the new way of handling asynchronous operations in Node.js. We will make use of async/await and Promises with the custom skill.

Demonstration

To demonstrate Alexa Custom Skills we will build an informational skill that responds to the user with interesting facts about Azure¹, Microsoft’s Cloud computing platform (Alexa talking about Azure, ironic, I know). This is not an official Microsoft skill; it is only used for this demonstration and has not been published.

Source Code

All open-source code for this post can be found on GitHub. Code samples in this post are displayed as GitHub Gists, which may not display correctly on some mobile and social media browsers. Links to gists are also provided.

Important, this post and the associated source code were updated from v1.0 to v2.0 on 13 August 2018. You should clone the GitHub project again, to correspond with this revised post, if you originally cloned the project before 14 August 2018. Code changes were significant.

Objectives

This objective of the fact-based skill will be to demonstrate the following.

Build, deploy, and test an Alexa Custom Skill using AWS Lambda and Node.js;
Use DynamoDB to store and retrieve Alexa voice responses;
Maintain a count of user’s questions in DynamoDB using atomic counters;
Use Amazon S3 to store and retrieve images, used in Display Cards;
Log Alexa Skill activities using Amazon CloudWatch Logs;

Steps to Build

Building the Azure fact skill will involve the following steps.

Design the Alexa skill’s voice interaction model;
Design the skill’s Display Cards for Alexa-enabled products, to enhance the voice experience;
Create the skill’s DynamoDB table and import the responses the skill will return;
Create an S3 bucket and upload the images used for the Display Cards;
Write the Alexa Skill, which involves mapping the user’s spoken input to the intents your cloud-based service can handle;
Write the Lambda function, which involves responding to the user’s utterances, by building and returning appropriate voice and display card responses, from DynamoDB and S3;
Extend the default ASK-generated AWS IAM Role, to allow the Lambda to update DynamoDB;
Deploy the skill;
Test the skill;

Let’s explore each step in detail.

Voice Interaction Model

First, we must design the fact skill’s voice interaction model. We need to consider the way we want the user to interact with the skill. What is the user’s conversational journey? How do they invoke your skill? How will the user provide intent?

This skill will require two intent slot values, the fact the user is interested in (i.e. ‘global infrastructure’) and the user’s first name (i.e. ‘Susan’). We will train the skill to allow Alexa to query the user for each slot value, but also allow the user to provide either or both values in the initial intent invocation. We will also allow the user to request a random fact.

Shown below in the Alexa Skills Kit Development Console Test tab are three examples of interactions the skill is trained to understand and handle:

The first example on the left invokes the skill with no intent (‘Alexa, load Azure Tech Facts). The user is led through a series of three questions to obtain the full intent.
The center example is similar, however, the initial invocation contains a partial intent (‘Alexa, ask Azure Tech Facts for a fact about certifications’). Alexa must still ask for the user’s name.
Lastly, the example on the right is a so-called ‘one-shot’ invocation (‘Alexa, ask Azure Tech Facts about Azure’s platforms for Gary’). The user’s invocation of the skill contains a complete intent, allowing Alexa to respond immediately with a fact about Azure platforms.

In all cases, our skill has the ability to continue to provide the user with additional facts if they chose, or they may cancel at any time.

We also need to design how Alexa will respond. What is the persona will Alexa assume through her words, phrases, and use of Speech Synthesis Markup Language (SSML).

User Interaction Previews

Here are a few examples of interactions with the final Alexa skill using an iPhone 8 and the Alexa App. They are intended to show the rich conversational capabilities of custom skills more so the than the display, which is pretty poor on the Alexa App as compared to the Echo Show or even Echo Spot.

Example 1: Indirect Invocation

The first example shows a basic interaction with our Alexa skill. It demonstrates an indirect invocation, a user utterance without initial intent. It also illustrates several variations of user utterances (YouTube).

Example 2: Direct Invocation

The second example of an interaction our skill demonstrates a direct invocation, in which the initial user utterance contains intent. It also demonstrates the user following up with additional requests (YouTube).

Example 3: Direct Invocation, Help, Problem

Lastly, another direct invocation demonstrates the use of the Help Intent. You also see an example of when Alexa does not understand the user’s utterance. The user is able to repeat their request, more clearly (YouTube).

Visual Interaction Model

Many Alexa-enabled devices are capable of both vocal and visual responses. Designing for a multimodal user experience is important. The instructional skill will provide vocal responses, as well as Display Cards optimized for the Amazon Echo Show. The skill contains a basic design for the Display Card shown during the initial invocation, where there is no intent uttered by the user.

The fact skill also contains a Display Card, designed to present the final Alexa response to the user’s intent. The content of the vocal and visual response is returned from DynamoDB via the Lambda function. The random Azure icons, available from Microsoft, are hosted in an S3 bucket. Each fact response is unique, as well as the icon associated with the fact.

The Display Cards will also work on other Alexa-enabled screen-based products. Shown below is the same card on an iPhone 8 using the Amazon Alexa app. This is the same app shown in the videos, above.

DynamoDB

Next, we create the DynamoDB table used to store the facts the Alexa skill will respond with when invoked by the user. DynamoDB is Amazon’s non-relational database that delivers reliable performance at any scale. DynamoDB consists of three basic components: tables, items, and attributes.

There are numerous ways to create a DynamoDB table. For simplicity, I created the AzureFacts DynamoDB table using the AWS CLI (gist). You could also choose CloudFormation, or create the table using any of nine or more programming languages with an AWS SDK.

	aws dynamodb create-table \
	--table-name AzureFacts \
	--attribute-definitions \
	AttributeName=Fact,AttributeType=S \
	--key-schema AttributeName=Fact,KeyType=HASH \
	--provisioned-throughput ReadCapacityUnits=3,WriteCapacityUnits=3

view raw dynamodb-create-table.sh hosted with ❤ by GitHub

The AzureFacts table’s schema has four key/value pair attributes per item: Fact, Response, Image, and Hits. The Fact attribute, a string, contains the name of the fact the user is seeking. The Fact attribute also serves as the table’s unique partition key. The Response attribute, a string, contains the conversational response Alexa will return. The Image attribute, a string, contains the name of the image in the S3 bucket displayed by Alexa. Lastly, the Hits attribute, a number, stores the number of user requests for a particular fact.

Importing Table Items

After the DynamoDB table is created, the pre-defined facts are imported into the empty table using AWS CLI (gist). The JSON-formatted data file, AzureFacts.json, is included with the source code on GitHub.

	aws dynamodb batch-write-item \
	--request-items file://data/AzureFacts.json

view raw azure-facts-import.sh hosted with ❤ by GitHub

The resulting table should appear as follows in the AWS Management Console.

Note the imported items shown below. The Hits counts reflect the number of times each fact has been requested.

Shown below is a detailed view of a single item that was imported into the DynamoDB table.

Amazon S3 Image Bucket

Next, we create the Amazon S3 bucket, which will house the images, actually Azure icons as PNGs, returned by Alexa with each fact. Again, I used the AWS CLI for simplicity (gist).

	aws s3api create-bucket \
	--bucket <my_bucket_name> \
	--region us-east-1

view raw s3api-create-bucket.sh hosted with ❤ by GitHub

The images can be uploaded manually to the bucket through a web browser, or programmatically, using the AWS CLI or SDKs. You will need to ensure the images are made public so they can be displayed by Alexa.

Alexa Skill

Next, we create the actual Alexa custom skill. I have used version 2 of the Alexa Skills Kit (ASK) Software Development Kit (SDK) for Node.js and the new ASK Command Line Interface (ASK CLI) to create the skill. The ASK SDK v2 for Node.js was recently released in April 2018. If you have previously written Alexa skills using version 1 of the Node.js SDK, the creation of a new project and the format of the Lambda Node.js code is somewhat different. I strongly suggest reviewing the example skills provided by Amazon on GitHub.

With version 1, I would have likely used the Alexa Skills Kit Development Console to develop and deploy the skill, and separate IDE, like JetBrains WebStorm, to write the Lambda. The JSON-format skill would live in the Alexa Skills Kit Development Console, and my Lambda in source control. I would have used AWS Serverless Application Model (AWS SAM) or Claudia.js to handle the deployment of Lambda functions.

With version 2 of ASK, you can easily create and manage the Alexa skill’s JSON-formatted code, as well as the Lambda, all from the command-line and a single IDE or text editor. All components that comprise the skill can be kept together in source control. I now only use the Alexa Skills Kit Development Console to preview my deployed skill and for testing. I am not going to go into detail about creating a new project using the ASK CLI, I suggest reviewing Amazon’s instructional guides.

Below, I have initiated a new AWS profile for the Alexa skill using the ask init command.

There are three main parts to the new skill project created by the ASK CLI: the skill’s manifest (skill.json), model(s) (en-US.json), and API endpoint, the Lambda (index.js). The skill’s manifest, skill.json, contains information (metadata) about the skill. This is the same information you find in the Distribution tab of the Alexa Skills Kit Development Console. The manifest includes publishing information, example phrases to invoke the skill, the skill’s category, distribution locales, privacy information, and the location of the skill’s API endpoint, the Lambda. An end-user would most commonly see this information in Amazon Alexa app when adding skills to their Alexa-enabled devices.

Next, the skill’s model, en-US.json, is located the models sub-directory. This file defines the skill’s custom interaction model, it contains the skill’s interaction model written in JSON, which includes the invocation name, intents, standard and custom slots, sample utterances, slot values, and synonyms of those values. This is the same information you would find in the Build tab of the Alexa Skills Kit Development Console. Amazon has an excellent guide to creating your custom skill’s interaction model.

Intents and Intent Slots

The skill’s custom interaction model contains the AzureFactsIntent intent, along with the boilerplate Cancel, Help and Stop intents. The AzureFactsIntent intent contains two intent slots, myName and myQuestion. The myName intent slot is a standard AMAZON.US_FIRST_NAME slot type. According to Amazon, this slot type understands thousands of popular first names commonly used by speakers in the United States. Shown below, I have included a short list of sample utterances in the intent model, which helps improve voice recognition for Alexa (gist).

	{
	"name": "AzureFactsIntent",
	"slots": [{
	"name": "myName",
	"type": "AMAZON.US_FIRST_NAME",
	"samples": [
	"{myName}",
	"my name is {myName}",
	"my name's {myName}",
	"name is {myName}",
	"the name is {myName}",
	"name's {myName}",
	"they call me {myName}"
	]
	}]
	}

view raw myNameIntent.json hosted with ❤ by GitHub

Custom Slot Types and Entities

The myQuestion intent slot is a custom slot type. According to Amazon, a custom slot type defines a list of representative values for the slot. The myQuestion slot contains all the available facts the custom instructional skill understands and can retrieve from DynamoDB. Like myName, the user can provide the fact intent in various ways (gist).

	{
	"name": "myQuestion",
	"type": "list_of_facts",
	"samples": [
	"{myQuestion}",
	"give me a fact about {myQuestion}",
	"give me a {myQuestion} fact",
	"how many {myQuestion} does Azure have",
	"I'd like to hear about {myQuestion}",
	"I'd like to hear more about {myQuestion}",
	"tell me about {myQuestion}",
	"tell me about Azure's {myQuestion}",
	"tell me about Azure {myQuestion}",
	"tell me a {myQuestion} fact",
	"tell me another {myQuestion} fact",
	"when was Azure {myQuestion}"
	]
	}

view raw myQuestionIntentSlot.json hosted with ❤ by GitHub

This slot also contains synonyms for each fact. Collectively, the slot value, it’s synonyms, and the optional ID are collectively referred to as an Entity. According to Amazon, entity resolution improves the way Alexa matches possible slot values in a user’s utterance with the slots defined in the skill’s interaction model.

An example of an entity in the myQuestion custom slot type is ‘competition’. A user can ask Alexa to tell them about Azure’s competition. The slot value ‘competition’ returns a fact about Azure’s leading competitors, as reported on the G2 Crowd website’s Microsoft Azure Alternatives & Competitors page. However, the user might also substitute the words ‘competitor’ or ‘competitors’ for ‘competition’. Using synonyms, if the user utters any of these three words in their intent, they will receive the same response from Alexa (gist).

	"types": [{
	"name": "list_of_facts",
	"values": [{
	"name": {
	"value": "competition",
	"synonyms": [
	"competitors",
	"competitor"
	]
	}
	},
	{
	"name": {
	"value": "certifications",
	"synonyms": [
	"certification",
	"certification exam",
	"certification exams"
	]
	}
	}
	]
	}]

view raw list-of-facts.json hosted with ❤ by GitHub

Lambda

Initializing a skill with the ASK CLI also creates the default API endpoint, a Lambda (index.js). The serverless Lambda function is written in Node.js 8.10. As mentioned in the Introduction, AWS recently announced support for the Node.js 8.10 runtime, in April. This is the first LTS version of Node to support async/await with Promises. Node’s async/await is the new way of handling asynchronous operations in Node.js.

The layout of the custom skill’s Lambda’s code closely follows the custom Alexa Fact Skill example. I suggest closely reviewing this example. The Lambda has four main sections: constants, setup code, intent handlers, and helper functions.

In addition to the boilerplate Help, Stop, Error, and Session intent handlers, there are the LaunchRequestHandler and the AzureFactsIntent handlers. According to Amazon, a LaunchRequestHandler fires when the Lambda receives a LaunchRequest from Alexa, in which the user invokes the skill with the invocation name, but does not provide any command mapping to an intent.

The AzureFactsIntent aligns with the custom intent we defined in the skill’s model (en-US.json), of the same name. This handler handles an IntentRequest from Alexa. This handler and the buildFactResponse function the handler calls are what translate a request for a fact from the user into a request to DynamoDB for a response.

The AzureFactsIntent handler checks the IntentRequest for both the myName and myQuestion slot values. If the values are unfulfilled, the AzureFactsIntent handler delegates responsibility back to Alexa, using a Dialog delegate directive (addDelegateDirective). Alexa then requests the slot values from the user in a conversational interaction. Alexa then calls the AzureFactsIntent handler again (gist).

	const request = handlerInput.requestEnvelope.request;
	let currentIntent = request.intent;

	if (myNameValue === undefined) {
	myNameValue = slotValue(request.intent.slots.myName);
	}

	if (!myNameValue) {
	return handlerInput.responseBuilder
	.addDelegateDirective(currentIntent)
	.getResponse();
	}

	let myQuestionValue = slotValue(request.intent.slots.myQuestion);

	if (!myQuestionValue) {
	return handlerInput.responseBuilder
	.addDelegateDirective(currentIntent)
	.getResponse();
	}

view raw addDelegateDirective.js hosted with ❤ by GitHub

Once both slot values are received by the AzureFactsIntent handler, it calls the buildFactResponse function, passing in the myName and myQuestion slot values. In turn, the buildFactResponse function calls AWS.DynamoDB.DocumentClient.update. The DynamoDB update returns a callback. In turn, the buildFactResponse function returns a Promise, a standard built-in object type, part of the JavaScript ES2015 spec (gist).

	function buildFactResponse(myName, myQuestion) {
	return new Promise((resolve, reject) => {
	if (myQuestion !== undefined) {
	let params = {};
	params.TableName = "AzureFacts";
	params.Key = {"Fact": myQuestion};
	params.UpdateExpression = "set Hits = Hits + :val";
	params.ExpressionAttributeValues = {":val": 1};
	params.ReturnValues = "ALL_NEW";

	docClient.update(params, function (err, data) {
	if (err) {
	console.log("GetItem threw an error:", JSON.stringify(err, null, 2));
	reject(err);
	} else {
	console.log("GetItem succeeded:", JSON.stringify(data, null, 2));
	resolve(data);
	}
	});
	}
	});
	}

view raw buildFactResponse.js hosted with ❤ by GitHub

What is unique about the DynamoDB update call in this case, is it actually performs two functions. First, it implements an Atomic Counter. According to AWS, an atomic counter is a numeric DynamoDB attribute that is incremented, unconditionally, without interfering with other write requests. The update increments the numeric Hits attribute of the requested fact by exactly one. Secondly, the update returns the DynamoDB item. We can increment the count and get the response in a single call.

The buildFactResponse function’s Promise returns the DynamoDB item, a JSON object, from the callback. An example of a JSON response payload is shown below. (gist).

	"Attributes": {
	"Hits": 4,
	"Fact": "global",
	"Image": "image-02.png",
	"Response": "according to Microsoft, with 54 Azure regions, Azure has more global regions than any other cloud provider. Azure is currently available in 140 countries."
	}

view raw dynamodb-update-callback.json hosted with ❤ by GitHub

The AzureFactsIntent handler uses the async/await methods to perform the call to the buildFactResponse function. Note line 7 of the AzureFactsIntent handler below, where the async method is applied directly to the handler. Note line 33 where the await method is used with the call to the buildFactResponse function (gist).

	const AzureFactsIntent = {
	canHandle(handlerInput) {
	const request = handlerInput.requestEnvelope.request;
	return request.type === "IntentRequest"
	&& request.intent.name === "AzureFactsIntent";
	},
	async handle(handlerInput) {
	const request = handlerInput.requestEnvelope.request;
	let currentIntent = request.intent;

	if (myNameValue === undefined) {
	myNameValue = slotValue(request.intent.slots.myName);
	}

	if (!myNameValue) {
	return handlerInput.responseBuilder
	.addDelegateDirective(currentIntent)
	.getResponse();
	}

	let myQuestionValue = slotValue(request.intent.slots.myQuestion);

	if (!myQuestionValue) {
	return handlerInput.responseBuilder
	.addDelegateDirective(currentIntent)
	.getResponse();
	}

	if (myQuestionValue.toString().trim() === 'random') {
	myQuestionValue = selectRandomFact();
	}

	let fact = await buildFactResponse(myNameValue, myQuestionValue);
	myNameValue = Object.is(myNameValue, undefined) ? undefined : capitalizeFirstLetter(myNameValue);
	let factToSpeak = `${myNameValue}, ${fact.Attributes.Response}`;
	cardContent = factToSpeak;

	// optional: logged to CloudWatch Logs
	console.log(`myName: ${myNameValue}`);
	console.log(`myQuestion: ${myQuestionValue}`);
	console.log(`factToSpeak: ${factToSpeak}`);

	return handlerInput
	.responseBuilder
	.speak(factToSpeak)
	.reprompt("You can request another fact")
	.withStandardCard(CARD_TITLE, cardContent,
	IMAGES.smallImageUrl, `${BUCKET_URL}\/${fact.Attributes.Image}`)
	.getResponse();
	}
	};

view raw AzureFactsIntent.js hosted with ❤ by GitHub

The AzureFactsIntent handler awaits the Promise from the buildFactResponse function. In an async function, you can await for any Promise or catch its rejection cause. If the update callback and the ensuing Promise were both returned successfully, the AzureFactsIntent handler returns both a vocal and visual response to Alexa.

AWS IAM Role

By default, an AWS IAM Role was created by ASK when the project was initialized, the ask-lambda-alexa-skill-azure-facts role. This role is automatically associated with the AWS Managed Policy, AWSLambdaBasicExecutionRole. This managed policy simply allows the skill’s Lambda function to create Amazon CloudWatch Events (gist).

	{
	"Version": "2012-10-17",
	"Statement": [
	{
	"Effect": "Allow",
	"Action": [
	"logs:CreateLogGroup",
	"logs:CreateLogStream",
	"logs:PutLogEvents"
	],
	"Resource": "*"
	}
	]
	}

view raw AWSLambdaBasicExecutionRole.json hosted with ❤ by GitHub

For the skill’s Lambda to read and write to DynamoDB, we must extend the default role’s permissions, by adding an additional policy. I have created a new AzureFacts_Alexa_Skill IAM Policy, which allows the associated role to get and update items from the AzureFacts DynamoDB table, and that is it. The role only has access to two of forty possible DynamoDB actions, and only for the AzureFacts table, and nothing else. Following the principle of Least Privilege is a cornerstone of AWS Security (gist).

	{
	"Version": "2012-10-17",
	"Statement": [
	{
	"Sid": "VisualEditor0",
	"Effect": "Allow",
	"Action": [
	"dynamodb:GetItem",
	"dynamodb:UpdateItem"
	],
	"Resource": "arn:aws:dynamodb:us-east-1:931066906971:table/AzureFacts"
	}
	]
	}

view raw AzureFacts_Alexa_Skill.json hosted with ❤ by GitHub

Below, we see the new IAM Policy in the AWS Management Console.

Below, we see the policy being applied to the skill’s IAM Role, along with the original AWS managed policy.

Deploying the Skill

Version 2 of the ASK CLI makes deploying the Alexa custom skill very easy. Using the ASK CLI’s deploy command, we can validate and deploy the skill (manifest), model, and Lambda, all at once, as shown below. This makes DevOps automation of skill deployments with tools like Jenkins or AWS CodeDeploy straight-forward.

You can verify the skill has been deployed, from the Alexa Skills Kit Development Console. You should observe the skill’s model (intents, slots, entities, and endpoints) in the Build tab. You should observe the skill’s publishing details in the Distribution tab. Note deploying the skill does not submit the skill to Amazon’s for review and publishing, you must still submit the skill separately.

From the AWS Lambda Management Console, you should observe the skill’s Lambda was deployed. You should observe only the skill can trigger the Lambda. Lastly, you should observe that the correct IAM Role was applied to the Lambda, giving the Lambda access to Amazon CloudWatch Logs and Amazon DynamoDB.

Testing the Skill

The ASK CLI comes with the simulate command. According to Amazon, the simulate command simulates an invocation of the skill with text-based input. Again, the ASK CLI makes DevOps test automation with tools like Jenkins or AWS CodeDeploy pretty easy (gist).

	ask simulate \
	--text "Load Azure Tech Facts" \
	--locale "en-US" \
	--skill-id "<your_skill_id>" \
	--profile "default"

view raw ask-simulate.sh hosted with ❤ by GitHub

Below, are the results of simulating the invocation. The simulate command returns the expected verbal response, including any SSML, and the visual responses (the Display Card). You could easily write an automation script to run a battery of these tests on every code commit, and prior to deployment.

I also like to manually test my skills from the Alexa Skills Kit Development Console Test tab. You may invoke the skill using your voice or by typing the skill invocation.

The Alexa Skills Kit Development Console Test tab both shows and speaks Alexa’s response. The console also displays the request and response body (JSON input/output), as well as the Display Card for an Echo Show and Echo Spot.

Lastly, the Alexa Skills Kit Development Console Test tab displays the Device Log. The log captures Alexa Directives and Events. I have found the Device Log to be very helpful in troubleshooting problems with deployed skills.

CloudWatch Logs

By default the custom skill outputs events to CloudWatch Logs. I have added the DynamoDB callback payload, as well as the slot values of myName and myQuestion to the logs, for each successful Alexa response. CloudWatch logs, like the Device Logs above, are very helpful in troubleshooting problems with deployed skills.

Conclusion

In this brief post, we have seen how to use the new ASK SDK/CLI version 2, services from the AWS Serverless Platform, and the LTS version of Node.js, to create an Alexa Custom Skill. Using the AWS Serverless Platform, we could easily extend the example to take advantage of additional serverless services, such as the use of Amazon SNS and SQS for notifications and messaging and Amazon Kinesis for analytics.

In a future post, we will extend this example, adding the capability to securely add and update our DynamoDB table’s items. We will use addition AWS services, including Amazon Cognito to authorize access to our API. We will also use AWS API Gateway to integrate with our Lambdas, producing a completely serverless API.

¹Azure is a trademark of Microsoft

All opinions expressed in this post are my own and not necessarily the views of my current or past employers or their clients.

Alexa, Alexa Skill, Amazon, ASK, AWS, Custom Skill, DynamoDB, Lambda, Node, Node.js, S3, Serverless, Virtual Assistant

7 Comments

Programmatic Ponderings

Posts Tagged DynamoDB

Event-driven, Serverless Architectures with AWS Lambda, SQS, DynamoDB, and API Gateway

Introduction

What is ‘Event-Driven’?

What is ‘Serverless’?

Demonstration

AWS Technologies

Architecture

Source Code

Prerequisites

Deploying the Project

Template Parameter

SAM CLI Commands

Test the Deployed Application

Event-Driven Patterns

S3 Event Source for Lambda

SQS Event Source for Lambda

API Gateway Event Source for Lambda

Test the API

Testing the Deployed API

Cleaning Up

Conclusion

Building Asynchronous, Serverless Alexa Skills with AWS Lambda, DynamoDB, S3, and Node.js

Introduction

AWS Technologies

Alexa Skills Kit

AWS Serverless Platform

Node.js

Demonstration

Source Code

Objectives

Steps to Build

Voice Interaction Model

User Interaction Previews

Example 1: Indirect Invocation

Example 2: Direct Invocation

Example 3: Direct Invocation, Help, Problem

Visual Interaction Model

DynamoDB

Importing Table Items

Amazon S3 Image Bucket

Alexa Skill

Intents and Intent Slots

Custom Slot Types and Entities

Lambda

AWS IAM Role

Deploying the Skill

Testing the Skill

CloudWatch Logs

Conclusion

Gary Stafford

Recent Posts

Top Posts & Pages

Tag Cloud

Tweets