Сохранение транскриптов в MongoDB с помощью веб-крючка Node.js

Викрам Васвани, консультант разработчиков

Этот учебник был первоначально опубликован на сайте https://docs.rev.ai/resources/tutorials/save-transcripts-mongodb-webhooks/ 12 июля 2022 года.

Содержание

Введение
Предположения
Шаг 1: Установите необходимые пакеты
Шаг 2: Создайте обработчик веб-крючка
Шаг 3: Протестируйте веб-крючок
Следующие шаги

Введение

Webhooks обеспечивают простой и эффективный способ обработки событий, которые происходят асинхронно за пределами приложения. Обычно они устанавливаются в качестве конечных точек URL, которые вызываются приложениями верхнего уровня при определенных событиях. Они принимают входящие HTTP-запросы и, в свою очередь, запускают специфические для приложения процессы, такие как генерация уведомления или обновление записи состояния.

Асинхронный API Rev AI для преобразования речи в текст использует веб-крючки для уведомления приложений о завершении задания транскрипции. После получения такого уведомления приложению обычно необходимо получить расшифровку и «что-то» с ней сделать. Это «что-то» может включать сохранение расшифровки в базе данных, предоставление пользователю возможности редактировать и исправлять ее или обработку другим способом.

В этом руководстве показано, как реализовать веб-крючок в приложении Node.js для одного из таких случаев использования. В нем вы найдете информацию (и код), необходимую для создания веб-крючка, который по завершении задания сможет запросить полную стенограмму у Rev AI и сохранить ее во внешней базе данных MongoDB для дальнейшей обработки.

Предположения

В данном руководстве предполагается, что:

У вас есть учетная запись Rev AI и токен доступа. Если нет, зарегистрируйте бесплатную учетную запись и сгенерируйте маркер доступа.
У вас есть правильно настроенная среда разработки Node.js с Node.js v16.x или v17.x. Если нет, скачайте и установите Node.js для вашей операционной системы.
Вы немного знакомы с фреймворком Express. Если нет, ознакомьтесь с основами на примере этого приложения.
У вас есть права на запись в базу данных MongoDB. Если нет, загрузите и установите MongoDB для вашей операционной системы и настройте контроль доступа, или разверните MongoDB в облаке и настройте базу данных, пользователя и роль с правами на запись.
Ваш веб-крючок будет доступен по общедоступному URL. Если нет, или если вы предпочитаете разрабатывать и тестировать локально, скачайте и установите ngrok, чтобы создать временный публичный URL для вашего webhook.
У вас есть аудиофайл для расшифровки. Если нет, используйте этот пример аудиофайла от Rev AI.

Шаг 1: Установите необходимые пакеты

В этом руководстве будут использоваться:

Rev AI Node SDK для отправки запросов на транскрибацию в Rev AI Asynchronous Speech-to-Text API;
Драйвер MongoDB Node.js для сохранения данных в MongoDB;
Express Web framework и промежуточное ПО body-parser для получения и анализа запросов webhook.

Начните с установки необходимых пакетов:

npm i revai-node-sdk mongodb express body-parser

Войдите в полноэкранный режим Выйти из полноэкранного режима

Шаг 2: Создайте обработчик веб-крючка

URL webhook указывается как часть параметров задания, передаваемых Rev AI API. По завершении задания Rev AI API отправит HTTP POST запрос, содержащий JSON-кодированную информацию о выполненном задании, на URL webhook. Вот пример одного из таких POST-запросов:

{
  job: {
    id: 'Qctu6UgJvTjZ',
    created_on: '2022-04-08T15:01:35.999Z',
    completed_on: '2022-04-08T15:02:05.403Z',
    name: 'FTC_Sample_1.mp3',
    callback_url: 'https://a177-49-36-111-113.ngrok.io/hook',
    media_url: 'https://www.rev.ai/FTC_Sample_1.mp3',
    status: 'transcribed',
    duration_seconds: 107,
    type: 'async',
    language: 'en'
  }
}

Войти в полноэкранный режим Выйти из полноэкранного режима

Следующий пример демонстрирует, как реализовать обработчик webhook, который получает и анализирует HTTP POST-сообщение от Rev AI API, а затем делает последующий запрос к API для получения полной расшифровки. Затем обработчик сохраняет полученные данные в коллекции базы данных MongoDB в виде документа JSON.

Чтобы использовать этот пример, вы должны заменить <MONGODB_CONNECTION_URI> на URI подключения к вашей базе данных MongoDB, а место <REVAI_ACCESS_TOKEN> на токен доступа вашей учетной записи Rev AI.

const { RevAiApiClient } = require('revai-node-sdk');
const { MongoClient } = require('mongodb');
const bodyParser = require('body-parser');
const express = require('express');

// MongoDB connection string
const mongodbUri = '<MONGODB_CONNECTION_URI>';

// Rev AI access token
const revAiToken = '<REVAI_ACCESS_TOKEN>';

// create Express application
const app = express();
app.use(bodyParser.json());

// create Mongo client
const mongo = new MongoClient(mongodbUri);
mongo.connect();
const db = mongo.db('mydb');
const transcripts = db.collection('transcripts')

// create Rev AI API client
const revAiClient = new RevAiApiClient(revAiToken);

// handle requests to webhook endpoint
app.post('/hook', async req => {
  const job = req.body.job;
  console.log(`Received status for job id ${job.id}: ${job.status}`);

  if (job.status === 'transcribed') {
    // request transcript
    const transcript = await revAiClient.getTranscriptObject(job.id);
    console.log(`Received transcript for job id ${job.id}`);

    // create MongoDB document
    const doc = {
      job_id: job.id,
      created_on: job.created_on,
      language: job.language,
      status: job.status,
      transcript
    }

    // save document to MongoDB
    try {
      const result = await collection.insertOne(doc);
      console.log(`Saved transcript with document id: ${result.insertedId}`);
    } catch (e) {
      console.error(e);
    }
  }
});

//  start application on port 3000
app.listen(3000, () => {
  console.log('Webhook listening');
})

Вход в полноэкранный режим Выйдите из полноэкранного режима

Сохраните этот листинг кода как index.js и рассмотрите его подробнее:

Этот листинг кода начинается с импорта необходимых пакетов и учетных данных и создания клиента MongoDB и клиента Rev AI API.
Он пытается подключиться к службе базы данных MongoDB с помощью метода connect() клиента MongoDB и выбирает базу данных и коллекцию для использования.
Он запускает приложение Express на порту 3000 и ожидает входящих POST-запросов к URL-маршруту /hook.
Когда приложение получает POST-запрос по адресу /hook, оно анализирует тело входящего JSON-сообщения и проверяет задание id и status.
Если status является transcribed, он использует метод getTranscriptObject() клиента API для получения полной расшифровки в виде документа JSON.
Он подготавливает документ MongoDB для хранения транскрипта. Этот документ также включает другие параметры задания, такие как дата и время, язык и статус.
Затем он использует метод insertOne() для вставки подготовленного документа в коллекцию и выводит уникальный идентификатор документа MongoDB на консоль.
Ошибки, если таковые имеются, в процессе подключения к MongoDB и вставки данных, отправляются в консоль.

Шаг 3: Протестируйте веб-крючок

Чтобы увидеть веб-крючок в действии, сначала убедитесь, что вы заменили заполнители, как описано в предыдущем шаге, а затем запустите приложение с помощью команды ниже.

node index.js

Войти в полноэкранный режим Выйти из полноэкранного режима

Далее отправьте аудиофайл на расшифровку в Rev AI и включите в запрос параметр callback_url. Этот параметр указывает URL веб-крючка, который API Rev AI должен вызвать по завершении задания.

Вот пример отправки аудиофайла с помощью веб-крючка с использованием curl.

curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" 
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" 
     -H "Content-Type: application/json" 
     -d '{"media_url":"<URL>","callback_url":"http://<WEBHOOK-HOST>/hook"}'

Вход в полноэкранный режим Выход из полноэкранного режима

Если вы предпочитаете отправлять аудиофайл с помощью Rev AI Node SDK, используйте этот скрипт:

const { RevAiApiClient } = require('revai-node-sdk');

const revAiToken = '<REVAI_ACCESS_TOKEN>';
const webhookUrl = 'http://<WEBHOOK-HOST>/hook';
const fileUrl = '<URL>';

// define job options
const jobOptions = {
  callback_url: webhookUrl,
};

// create Rev AI API client
const revAiClient = new RevAiApiClient(revAiToken);

// submit job
job = await revAiClient.submitJobUrl(fileUrl, jobOptions);

Войти в полноэкранный режим Выйти из полноэкранного режима

В обоих случаях замените место <REVAI_ACCESS_TOKEN> на ваш токен доступа к Rev AI, а место <URL> на прямой URL вашего аудиофайла. Кроме того, замените заполнитель <WEBHOOK-HOST> следующим образом:

Если вы разрабатываете и тестируете в публичном облаке, ваше приложение Express обычно будет доступно на публичном домене или IP-адресе. В этом случае замените заполнитель <WEBHOOK-HOST> на правильное доменное имя или IP-адрес, включая номер порта 3000, если требуется.
Если вы разрабатываете и тестируете локально, ваше приложение Express не будет доступно публично, поэтому вы должны настроить публичный URL переадресации с помощью такого инструмента, как ngrok. Получите этот URL с помощью команды ngrok http 3000 и замените место <WEBHOOK-HOST> на временный URL пересылки, созданный ngrok.

Как только задание будет обработано, Rev AI API отправит POST-запрос на URL webhook. Затем веб-крючок запросит полную расшифровку и сохранит ее в базе данных MongoDB в виде документа JSON, как объяснялось в предыдущем разделе.

Вот пример вывода, создаваемого обработчиком веб-крючка:

Webhook listening
Received status for job id Qctu6UgJvTjZ: transcribed
Received transcript for job id Qctu6UgJvTjZ
Saved transcript with document id: 62504e6fcc32c9387208c875

Войти в полноэкранный режим Выход из полноэкранного режима

Вы можете получить стенограмму для просмотра или дальнейшей обработки, подключившись к базе данных MongoDB и получив документ по его уникальному идентификатору. Ниже показан пример выполнения этого действия с помощью mongosh:

test> use mydb
mydb> db.transcripts.find( { '_id':ObjectId('62504e6fcc32c9387208c875') } )

[
  {
    _id: ObjectId("62504e6fcc32c9387208c875"),
    job_id: 'Qctu6UgJvTjZ',
    created_on: '2022-04-08T15:01:35.999Z',
    language: 'en',
    status: 'transcribed',
    transcript: {
      monologues: [
        {
          speaker: 0,
          elements: [
            {
              type: 'text',
              value: 'Hi',
              ts: 0.26,
              end_ts: 0.48,
              confidence: 0.99
            },
            { type: 'punct', value: ',' },
            {
              ...
            }
          ]
        }
      ]
    }
  }
]

Вход в полноэкранный режим Выход из полноэкранного режима

Если веб-крючок работает не так, как ожидалось, вы можете протестировать и проверить ответ веб-крючка.

Следующие шаги

Подробнее об использовании веб-крючков для асинхронной обработки можно узнать по следующим ссылкам:

Документация: Асинхронная отправка заданий Speech-To-Text API и веб-крючки
Учебное пособие: Начало работы с веб-крючками Rev AI API
Учебное пособие: Использование Webhooks для запуска уведомлений о заданиях по электронной почте с помощью Node.js, SendGrid и Express
Документация: Использование ngrok
Документация: MongoDB
Документация: Драйвер MongoDB Node.js