Практическое руководство

В этом руководстве я хочу показать вам один из способов создания навыка Amazon Alexa Skill с помощью PHP. Это будет очень простой пример навыка, но он поможет понять, как работает реализация нового навыка.

Конфигурация Amazon Skill

Начнем с Skill на сайте Amazon. Позже станет ясно, почему это правильный путь. Во-первых, нам нужна учетная запись разработчика Amazon по адресу https://developer.amazon.com/. С учетной записью разработчика мы можем начать с учебника по адресу https://developer.amazon.com/alexa/console/ask. На этой странице начните с нового навыка, нажав кнопку Создать навык.

Сначала выберите название навыка и выберите язык.

Следующим шагом будет добавление информации о хостинге. Здесь мы выбираем категорию. В нашем случае мы хотим создать «Пользовательский навык» и предоставить ему собственный PHP-сервер.

Затем выберите шаблон Skill. Здесь на выбор шаблон «Начать с нуля».

Теперь просмотрите и создайте Навык. Создание навыка может занять несколько секунд.

Основы навыка готовы. Теперь пришло время развивать Навык. Браузер теперь открыл представление сборки навыка. Здесь можно настроить все, что нужно для Навыка.

Чтобы вернуться на эту страницу из списка навыков, используйте кнопку редактирования.

Следующим шагом является настройка серверной части, откуда запросы должны отправляться в приложение PHP (необходимо реализовать).

Теперь наступает та часть, где вам нужно решить, как должен работать ваш навык. Для этого вы должны определить свои слоты (или использовать уже определенные слоты, такие как ввод чисел, ввод даты и т. д.) и свои намерения. Намерения — это ваши логические комбинации входной речи. Чтобы было понятнее, посмотрите следующий пример:

В этом уроке я создам Навык, отвечающий на текст, произнесенный пользователем. Так что, в конце концов, у меня будет один слот, покрывающий весь ввод пользователя, и один интент для обработки этого слота.

Другим примером может быть наличие двух слотов:

  1. Ввод числа (имя: число)
  2. Любое слово (имя: слово)

Затем мы определяем Intent со следующим образцом высказывания:
Повторите слово {word} {number} раз.

Это намерение будет реализовывать повторение данного слова несколько раз.
Повторите слово foo три раза. =› фу фу фу

После этого мы даем Навыку имя вызова. Как пользователю вызвать Alexa, чтобы открыть Skill?

Важно сохранить модель, чтобы не потерять данные. Всегда сохраняйте модель, потому что ее можно построить и проверить на наличие ошибок и предупреждений.

Следующим шагом является создание слота, чтобы вы могли использовать его на следующем этапе намерения. Это необходимо делать только в том случае, если указанные слоты Amazon не подходят для данного варианта использования.

Теперь создайте новое намерение и используйте созданный слот. Для этого добавьте слот (и, возможно, другие слоты, которые вам нужны) в намерение и напишите несколько примеров высказываний. Сколько образцов высказываний вам нужно, зависит от варианта использования.

Когда слоты и намерения настроены, полезно взглянуть на редактор JSON. Этот редактор является действительно полезным инструментом. Вы можете просмотреть полную конфигурацию и отредактировать или импортировать ее.

Некоторые ошибки сборки могут быть видны только в редакторе JSON, а не в пользовательском интерфейсе. В случае ошибок сборки всегда полезно посмотреть на JSON.

Навык кодирования с помощью PHP

Настройка части Amazon завершена. Начнем с части PHP.

Для этого я создаю новый проект с composer init . Я рекомендую использовать composer, но, конечно, это не обязательно.

В этом уроке я показал реализацию Skill с библиотекой https://github.com/maxbeckers/amazon-alexa-php. Чтобы добавить эту библиотеку поставщику, используйте composer require maxbeckers/amazon-alexa-php .

В этом руководстве есть только одно пользовательское намерение; все остальные — намерения Amazon, для которых в библиотеке есть обработчики. Все намерения, которые может использовать Skill, определены в JSON. Там вы увидите AMAZON.CancelIntent , AMAZON.HelpIntent , AMAZON.StopIntent , AMAZON.NavigateHomeIntent , AMAZON.FallbackIntent и созданный вами MyCustomFulltextIntent .

Цели намерений Amazon говорят сами за себя. Для самостоятельно созданного намерения я реализую следующее MyCustomFulltextIntentRequestHandler:

<?php

namespace Maxbeckers\MyCoolTestskill;

use MaxBeckers\AmazonAlexa\Helper\ResponseHelper;
use MaxBeckers\AmazonAlexa\Request\Request;
use MaxBeckers\AmazonAlexa\Request\Request\Standard\IntentRequest;
use MaxBeckers\AmazonAlexa\RequestHandler\AbstractRequestHandler;
use MaxBeckers\AmazonAlexa\Response\Response;

class MyCustomFulltextIntentRequestHandler extends AbstractRequestHandler
{
    /**
     * @var ResponseHelper
     */
    private $responseHelper;

    public function __construct(ResponseHelper $responseHelper, array $supportedApplicationIds)
    {
        $this->responseHelper = $responseHelper;
        $this->supportedApplicationIds = $supportedApplicationIds;
    }

    public function supportsRequest(Request $request): bool
    {
        return $request->request instanceof IntentRequest && 'MyCustomFulltextIntent' === $request->request->intent->name;
    }

    public function handleRequest(Request $request): Response
    {
        $input = $request->request->intent->slots[0]->value;

        return $this->responseHelper->respond($input, true);
    }
}

В методе supportsRequest важно проверить намерение. Это можно сделать, проверив имя намерения 'MyCustomFulltextIntent' === $request->request->intent->name.

Метод handleRequest предназначен для логики намерения. В данном случае это очень просто, потому что у намерения есть один слот (во всех случаях). Таким образом, нет необходимости проверять, установлен ли слот, и проверять правильность имени слота. После этого используется ввод $input, и на него напрямую реагируют. ResponseHelper облегчает жизнь.

Наконец, добавляется флаг endSession для завершения сеанса после этого намерения. Это означает, что навык будет автоматически закрыт после этого намерения. В большинстве случаев это не нужно или полезно.

Вот краткий намек на то, почему AbstractRequestHandler ожидает список поддерживаемых идентификаторов приложений (идентификаторов навыков): можно использовать один обработчик для более чем одного навыка.

Теперь index.php должен быть создан и выглядеть так:

<?php

use MaxBeckers\AmazonAlexa\Helper\ResponseHelper;
use MaxBeckers\AmazonAlexa\Request\Request;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\CancelRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\FallbackRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\HelpRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\NavigateHomeRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\Basic\StopRequestHandler;
use MaxBeckers\AmazonAlexa\RequestHandler\RequestHandlerRegistry;
use MaxBeckers\AmazonAlexa\Validation\RequestValidator;
use Maxbeckers\MyCoolTestskill\MyCustomFulltextIntentRequestHandler;

require '../vendor/autoload.php';

$requestBody = file_get_contents('php://input');
if ($requestBody) {
    $alexaRequest = Request::fromAmazonRequest($requestBody, $_SERVER['HTTP_SIGNATURECERTCHAINURL'], $_SERVER['HTTP_SIGNATURE']);

    if (!$alexaRequest) {
        http_response_code(400);
        exit();
    }

    // Request validation
    $validator = new RequestValidator();
    $validator->validate($alexaRequest);

    // create all needed handlers
    $mySkillId = ['amzn1.ask.skill.0000000-0000-0000-0000-00000000000']; // paste your skill id here
    $responseHelper = new ResponseHelper();
    $myCustomFulltextIntentRH = new MyCustomFulltextIntentRequestHandler($responseHelper, $mySkillId);
    $cancelRH = new CancelRequestHandler($responseHelper, 'cancel text', $mySkillId);
    $fallbackRH = new FallbackRequestHandler($responseHelper, 'fallback text', $mySkillId);
    $navigateHomeRH = new NavigateHomeRequestHandler($responseHelper, 'navigate home text', $mySkillId);
    $helpRH = new HelpRequestHandler($responseHelper, 'help text', $mySkillId);
    $stopRH = new StopRequestHandler($responseHelper, 'stop text', $mySkillId);

    // add handlers to registry
    $requestHandlerRegistry = new RequestHandlerRegistry([
        $myCustomFulltextIntentRH,
        $cancelRH,
        $fallbackRH,
        $navigateHomeRH,
        $helpRH,
        $stopRH,
    ]);

    // handle request
    $requestHandler = $requestHandlerRegistry->getSupportingHandler($alexaRequest);
    $response = $requestHandler->handleRequest($alexaRequest);

    // render response
    header('Content-Type: application/json');
    echo json_encode($response);
} else {
    http_response_code(400);
}

exit();

Здесь нужны обработчики интентов по умолчанию, а обработчики кастомных интентов — в данном случае только MyCustomFulltestIntentRequestHandler — добавляются в реестр.

Реестр использует шаблон посетителя для обнаружения необходимого RequestHandler с помощью метода supportsRequest. С обнаруженным обработчиком запрос обрабатывается с использованием метода handleRequest.

Идентификатор навыка можно скопировать из списка навыков.

Тестирование и публикация

Теперь пришло время проверить Навык. Для этого код необходимо развернуть на конечной точке и определить в конфигурации Amazon Backend Skill.

Графический интерфейс тестирования — очень мощный инструмент. С помощью этого инструмента можно создавать запросы, как это делала бы настоящая Alexa. При отправке недопустимого ответа из вашего кода он покажет ошибки на вашем дисплее Alexa. Это возможности вашего Навыка.

Когда все тесты прошли успешно, пришло время раздать Навык.

В этом уроке я пропущу процесс распространения, потому что он не имеет прямого отношения к созданию навыка. В процессе распространения для Навыка определяются примеры и значки и т. д. После процесса распространения Навык будет рассмотрен и проверен. Это может занять несколько часов.

Ваш навык может быть отклонен в процессе проверки Amazon. Если это произойдет, Amazon расскажет, почему навык был отклонен. Исправьте указанные проблемы, а затем снова запросите проверку.

Когда ваш навык будет опубликован, вы сможете найти его на https://www.amazon.com/, и пользователи Alexa смогут установить ваш навык. Поздравляем!

Заключение

В этом руководстве очень просто показано «Как реализовать Amazon Alexa Skill с PHP». Если вы хотите развить новый Навык, вам следует подумать, какой Навык вы хотите развить, потому что новый Навык должен предлагать дополнительную ценность для вашей целевой группы.

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