Developing a skill for Alice and a website with authorization

In this scenario, you will develop a skill for Alice and deploy a web app for creating, reading and editing to-do lists with Alice's help, as well as for sharing the lists with other users on the website.

Yandex Cloud Services

• Yandex Cloud Functions
• Yandex API Gateway
• Yandex Managed Service for YDB
• Yandex Object Storage
• Yandex Key Management Service

Tools

• Yandex Cloud command line tool
• go-swagger
• api-spec-converter
• jq
• Terraform
• AWS command line tool
• Node.js
• go

Prerequisites

We assume that you already have Yandex Cloud account with created cloud and folder.

Initialization

Create Object Storage bucket

Follow documentation to create bucket with any name. Bucket name will be used in project configuration.

Configure aws cli following instructions.

Create API Gateway

Create API Gateway with any name and default specification. Id of created gateway will be used in project configuration.

Create Yandex Database

Find out how to create Yandex Database in serverless mode. DB schema will be applied later. Database name and endpoint will be used in project configuration.

Create Yandex OAuth application

Go to Yandex OAuth service and create new application. You can use any name you like. You should check "WEB service platfrom" and provide at least two callback URIs:

• <apigateway technical domain>/yandex-oauth
• https://social.yandex.net/broker/redirect

Use technical domain registered for API Gateway you created earlier.

You should check login:avatar permission so that your serverless site can use Yandex user's avatar image.

Configuring project

Common variables

Create variables.json file in project root with values filled with values for your project. You can use variables-template.json as template for this step

• folder-id - your Yandex Cloud folder id
• domain - your site's domain (e.g. API Gateway's technical domain)
• oauth-client-id - ID of your registered Yandex OAuth application
• database - Yandex Database name
• database-endpoint - Yandex Database endpoint
• yc-profile - Yandex Cloud command line tool profile name
• secure-config-path - path to JSON config with secrets
• storage-bucket - Yandex Object Storage bucket name
• gateway-id - id of your API Gateway

Secret variables

Create secure-config.json file anywhere on your machine (don't forget to refer to it's destination from variables.json). Use secure-config-template.json as template for your file

• session_keys - generated secret keys used in session management Keys can be generated:
  • hash - base64-encoded 64-bytes random value
  • block - base64-encoded 32-bytes random value
• oauth_secret - secret (password) of Yandex OAuth application you created

Deploying

Apply DB schema

Run ./upload_ydb_schema.sh.

Deploy functions

Functions can be deployed using terraform. After terraform initialized, you can deploy your application with

terraform apply -var-file ./variables.json -var yc-token=<OAuth token>

Where OAuth token - OAuth token for your cloud.

Upload static

Go to frontend directory and build static files with

npm run build

Run ./upload_static.sh at project root to upload static files to Object Storage.

Update API Gateway

Run ./update_gateway.sh to update gateway specification.

Note that at this point your functions should already be deployed with terraform since gateway update script uses terraform's output values to link gateway specification with your function

Creating Alice skill

Alice skill can be registered in Yandex Dialogs console You can choose arbitrary values for your skill's settings, but theses are required:

Backend

You should choose "Function in Yandex Cloud" backend and use todolist-alice function that were deployed earlier with terraform.

Storage

You should check "Storage" checkbox so that your skill will be able to store dialog state.

Account linking

This settings section describes how Yandex Alice should authenticate on your site. In our example you should use Yandex OAuth settings.

• Application identity - id of your Yandex OAuth application
• Application secret - secret (password) of your Yandex OAuth application
• Authorization url - https://oauth.yandex.ru/authorize
• URL for token receive - https://oauth.yandex.ru/token
• URL for token refresh - https://oauth.yandex.ru/token

Intents

Use intent definitions provided in intents folder of this project to configure Alice skill intents.

Intent file name must be used as intent ID (e.g. for ./intents/cancel.txt configure intent cancel in dialogs settings). Intent file content provides intent grammar - paste it as is into corresponding settings field.

Development

Source of truth for OpenAPI 3.0 specification is placed in ./gateway/openapi-template.yaml, all other OpenAPI and Swagger files are generated from this one. If you want to change an API - you should change only openapi-template.yaml file and then generate the rest with

./generate_code.sh