dialogs

package module
v0.0.0-...-6f58fe9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2018 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package dialogs - это простой пакет для взаимодействия с API Яндекс.Диалогов и работы с Навыками голосового ассистента Алисы.

Данный пакет полностью реализует основные механизмы платформы на основе официальной документации, а также содержит несколько вспомогательных инструментов для облегчения работы с данными.

Текущая версия протокола: 1.0

Example (FastStart) 
package main

import (
	"log"
	"strings"

	"gitlab.com/toby3d/dialogs"
)

var (
	questions dialogs.Questions
	answers   dialogs.Answers

	answer dialogs.Answer
)

func main() {
	log.Println("Стартуем!..")
	questions, answers = dialogs.New("127.0.0.1:2368", "/alice", "", "")

	for question := range questions {
		switch {
		case strings.EqualFold(question.Request.Command, "привет"):
			// Это команда приветствия. Надо ответить взаимностью!

			// Готовим ответ на реплику и приветствуем пользователя.
			answer = dialogs.NewAnswer(question, "Привет!")

			// Корректно озвучиваем реплику
			answer.Response.TTS = "прив+ет!"

			// Результат отправляем в канал
			answers <- answer
		case question.Request.Command != "":
			// Это какая-то команда, которую мы не знаем. Нужно извиниться.
			answer = dialogs.NewAnswer(question, "Простите, я не поняла.")
			answer.Response.TTS = "Прост+ите, я не понял+а."
			answers <- answer
		default:
			continue // Это что-то совсем иное - ничего не делаем.
		}
	}
}

Index

Examples

Constants

View Source 
const (
	// TypeSimpleUtterance является идентификатором события голосового ввода
	TypeSimpleUtterance = "SimpleUtterance"

	// TypeButtonPressed является идентификатором события нажатия на кнопку
	TypeButtonPressed = "ButtonPressed"
)

Variables

This section is empty.

Functions

func New 

func New(addr, path, certFile, keyFile string) (Questions, Answers)

New создаёт простой роутер для прослушивания входящих данных по вебхуку и возвращает два канала: для чтения запросов и отправки ответов соответственно.

Example 
package main

import (
	"gitlab.com/toby3d/dialogs"
)

var (
	questions dialogs.Questions
	answers   dialogs.Answers
)

func main() {
	// New принимает аргументы в следующем порядке:
	// * Локальный адрес и порт.
	// * Роут по которому нужно слушать входящий трафик; желательно использовать
	//   уникальный и секретный путь, по которому можно однозначно
	//   идентифицировать трафик как запрос от Яндекса.
	// * Файл сертификата (если необходим).
	// * Файл ключа сертификата (если необходим).
	//
	// В случае ошибки возникнет паника. В случае успеха будет создан роутер по
	// указанному адресу:порту/пути который будет слушать входящий трафик.
	//
	// В ответ будут возвращены два канала: для чтения запросов и отправки
	// ответов соответственно.
	questions, answers = dialogs.New("127.0.0.1:2368", "/alice", "", "")
}

Types

type Answer 

type Answer struct {
	// Версия протокола.
	Version string `json:"version"`

	// Данные о сессии.
	Session Session `json:"session"`

	// Данные для ответа пользователю.
	Response Response `json:"response"`
}

Answer представляет собой ответ пользователю.

func NewAnswer 

func NewAnswer(question Question, text string) Answer

NewAnswer создаёт основу Answer для ответа, на основе входящего Question.

Example 
package main

import (
	"gitlab.com/toby3d/dialogs"
)

var (
	answers dialogs.Answers

	answer   dialogs.Answer
	question = dialogs.Question{
		Meta: dialogs.Meta{
			ClientID: "Developer Console",
			Locale:   "ru-RU",
			TimeZone: "UTC",
		},
		Request: dialogs.Request{
			Command:           "привет",
			OriginalUtterance: "привет",
			Type:              dialogs.TypeSimpleUtterance,
		},
		Session: dialogs.Session{
			MessageID: 42,
			New:       false,
			SessionID: "1ab234cd-56e7890f-gh1j23k-45l6",
			SkillID:   "ab1c2d34-5e67-8f90-g12h-3456jkl78901",
			UserID:    "1A2BC3456789D0E12F345GHJ67890K1LMN23OP4567QR8901234567ST89UV0W12",
		},
		Version: "1.0",
	}

	buttons []dialogs.Button
)

func main() {
	// Привязываем новый ответ к идентификаторам входящей реплики
	answer = dialogs.NewAnswer(question, "Прощай, жестокий мир!")

	// Можно дополнить реплику дополнительными возможностями вроде кнопок,
	// озвучки и/или параметром, обозначающим конец разговора и выхода из Навыка.
	answer.Response.TTS = "Прощ+ай, жест+окий м+ир!"
	answer.Response.Buttons = buttons
	answer.Response.EndSession = true

	// Оформленный ответ нужно отправить не позднее 1,5 секунд после получения
	// реплики пользователя.
	answers <- answer
}

type Answers 

type Answers chan Answer

Answers является вебхук-каналом исходящих ответов к пользователям.

type Button 

type Button struct {
	// Текст кнопки.
	Title string `json:"title"`

	// Произвольный JSON, который Яндекс.Диалоги должны отправить
	// обработчику, если данная кнопка будет нажата.
	Payload Payload `json:"payload,omitempty"`

	// URL, который должна открывать кнопка.
	URL string `json:"url"`

	// Признак того, что кнопку нужно убрать после следующего запроса
	// пользователя. Допустимые значения:
	// * false — кнопка должна оставаться активной (значение по умолчанию);
	// * true — кнопку нужно скрывать после нажатия.
	Hide bool `json:"hide"`
}

Button представляет собой произвольную кнопку в диалоге.

func NewButton 

func NewButton(title string) Button

NewButton создаёт основу для Button.

Example 
package main

import (
	"gitlab.com/toby3d/dialogs"
)

var textButton, urlButton, dataButton dialogs.Button

func main() {
	textButton = dialogs.NewButton("я просто кнопка")

	dataButton = dialogs.NewButton("я кнопка с данными")
	var payload dialogs.Payload
	// Произвольные данные должны быть в формате JSON
	payload = struct {
		Count int    `json:"count"`
		Word  string `json:"word"`
	}{
		Count: 42,
		Word:  "Алиса",
	}
	dataButton.Payload = payload

	urlButton = dialogs.NewButton("я ссылка")
	urlButton.URL = "https://toby3d.gitlab.io"
}

func NewButtons 

func NewButtons(buttons ...Button) []Button

NewButtons создаёт новый массив Button.

Example 
package main

import (
	"gitlab.com/toby3d/dialogs"
)

var (
	answer dialogs.Answer

	textButton, urlButton, dataButton dialogs.Button
)

func main() {
	answer.Response.Buttons = dialogs.NewButtons(textButton, dataButton, urlButton)
}

type Markup 

type Markup struct {
	// Признак реплики, которая содержит криминальный подтекст (самоубийство,
	// разжигание ненависти, угрозы). Вы можете настроить навык на
	// определенную реакцию для таких случаев — например, отвечать "Не
	// понимаю, о чем вы. Пожалуйста, переформулируйте вопрос."
	//
	// Возможно только значение true. Если признак не применим, это свойство
	// не включается в ответ.
	DangerousContext bool `json:"dangerous_context,omitempty"`
}

Markup содержит формальные характеристики реплики, которые удалось выделить Яндекс.Диалогам. Отсутствует, если ни одно из вложенных свойств не применимо.

type Meta 

type Meta struct {
	// Язык в POSIX-формате.
	Locale string `json:"locale"`

	// Название часового пояса, включая алиасы.
	TimeZone string `json:"timezone"`

	// Идентификатор устройства и приложения, в котором идет разговор.
	ClientID string `json:"client_id"`
}

Meta содержит информацию об устройстве, с помощью которого пользователь разговаривает с Алисой.

func (Meta) Language 

func (meta Meta) Language() language.Tag

Language декодирует поле Locale в language.Tag.

func (Meta) TimeLocation 

func (meta Meta) TimeLocation() (*time.Location, error)

TimeLocation декодирует поле TimeZone в *time.Location.

type Payload 

type Payload interface{}

Payload представляет собой произвольные JSON данные, идущие c кнопкой.

type Question 

type Question struct {
	// Информация об устройстве, с помощью которого пользователь
	// разговаривает с Алисой.
	Meta Meta `json:"meta"`

	// Данные, полученные от пользователя.
	Request Request `json:"request"`

	// Данные о сессии.
	Session Session `json:"session"`

	// Версия протокола.
	Version string `json:"version"`
}

Question содержит информацию о входящем запросе пользователя.

type Questions 

type Questions <-chan Question

Questions является вебхук-каналом входящих запросов от пользователя.

type Request 

type Request struct {
	// Тип ввода:
	// * SimpleUtterance — голосовой ввод;
	// * ButtonPressed — нажатие кнопки.
	Type string `json:"type"`

	// Формальные характеристики реплики, которые удалось выделить
	// Яндекс.Диалогам. Отсутствует, если ни одно из вложенных свойств не
	// применимо.
	Markup Markup `json:"markup,omitempty"`

	// Текст пользовательского запроса без активационных фраз Алисы и
	// конкретного навыка.
	Command string `json:"command"`

	// Полный текст пользовательского запроса.
	OriginalUtterance string `json:"original_utterance"`

	// JSON, полученный с нажатой кнопкой от обработчика навыка (в ответе на
	// предыдущий запрос).
	Payload Payload `json:"payload,omitempty"`
}

Request содержит данные, полученные от пользователя.

func (Request) IsButtonPressed 

func (req Request) IsButtonPressed() bool

IsButtonPressed проверяет принадлежность запроса к событию нажатия на кнопку.

func (Request) IsSimpleUtterance 

func (req Request) IsSimpleUtterance() bool

IsSimpleUtterance проверяет принадлежность запроса к событию голосового ввода.

type Response 

type Response struct {
	// Текст, который следует показать пользователю.
	Text string `json:"text"`

	// Ответ в формате TTS (text-to-speech).
	TTS string `json:"tts"`

	// Кнопки, которые следует показать пользователю.
	Buttons []Button `json:"buttons"`

	// Признак конца разговора (получая этот флаг в ответе, Алиса
	// автоматически завершает работу навыка в приложении).
	EndSession bool `json:"end_session"`
}

Response содержит данные для ответа пользователю.

type Session 

type Session struct {
	// Признак новой сессии. Возможные значения:
	// * true — пользователь начал новый разговор с навыком;
	// * false — запрос отправлен в рамках уже начатого разговора.
	New bool `json:"new"`

	// Уникальный идентификатор сессии, 64 байта.
	SessionID string `json:"session_id"`

	// Идентификатор сообщения в рамках сессии. Инкрементируется с каждым
	// следующим запросом.
	MessageID int64 `json:"message_id"`

	// Идентификатор вызываемого навыка.
	SkillID string `json:"skill_id"`

	// Обфусцированный идентификатор пользователя.
	UserID string `json:"user_id"`
}

Session содержит данные о сессии.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.