Источники данных

01Что такое источник данных

Источник данных: это веб-адрес, который вы сохраняете один раз. Когда зритель запускает команду, которая на него ссылается, бот обращается к этому адресу, извлекает одно значение из ответа и произносит его в чате. Погода, игровая статистика, длина очереди на вашем собственном сервере: если это отвечает по https и возвращает JSON или текст, команда может это прочитать.

За этой строкой стоит обычная пользовательская команда. Её ответ, как он введён в редакторе:

Сейчас в Монреале {urlfetch:weather}°C.

Токен называет источник, а не значение. Место, откуда бот берёт значение, сохранено в самом источнике в виде пути: адреса внутри ответа. Ответ это здание, current это этаж, temperature_2m это дверь. Запишите всё с точками, и получится current.temperature_2m. Третий раздел делает эти клики за вас, и аналогия на этом заканчивает свою работу.

02Добавьте источник из редактора команд

Всё происходит в разделе Команды, в редакторе, который открывается рядом со списком ваших команд.

1. Поставьте курсор там, где будет значение

   Откройте команду, нажмите в Ответ и оставьте курсор на том месте предложения, где должно стоять значение.

2. Откройте палитру

   Под ответом, рядом с метками {user} и {args}, есть плашка Источник данных.

3. Создайте новый

   + Новый источник данных открывает окно Добавить источник данных: «Укажите веб-API, получите один реальный ответ, затем нажмите на значение, которое хотите показать в чате.»

4. Назовите его и вставьте адрес

   Отображаемое имя нужно для вас. Оно автоматически превращается в Имя источника данных, то есть слово, которое попадает в токен: «Строчные буквы, цифры и подчёркивания. Используется внутри {urlfetch:name}.» Затем Веб-адрес: https, до 512 символов.

5. Получите один реальный ответ

   Получить пример вызывает ваш API по-настоящему, примерно раз в 10 секунд. Если ответ приходит в виде, который окно не умеет читать, нажмите или вставьте ответ вручную и вставьте ответ сами.

6. Нажмите на значение, затем добавьте источник

   Ответ превращается в дерево под подсказкой «Нажмите на значение, которое хотите показать в чате.» Нажмите temperature_2m, и окно покажет Показывается current.temperature_2m. Добавить источник сохраняет всё, а строка в палитре вставляет {urlfetch:weather} на место курсора.

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

03Выбор значения

Вот то же дерево, что и в панели управления, с теми же правилами. Кликабельны только значения; ветка вроде current содержит другие вещи, поэтому не может завершать путь. Измените ответ слева, и дерево следует за ним. Это самый быстрый способ порепетировать со своим API до сохранения чего-либо.

04API, которым нужен ключ

Некоторым API нужен ключ, прежде чем они ответят. Добавьте его один раз в Настройках, в панели Ключи API: метку до 32 символов, чтобы потом его узнавать, и сам секрет, до 512 символов, затем Добавить ключ. В подсказке на самой панели всё сказано предельно ясно: «Ключи API, которые ваши источники данных отправляют с каждым запросом. Пользователи с общим доступом могут использовать их, но никогда не увидят их значения.»

Секрет шифруется до записи и больше никогда не показывается. Вам остаются метка и последние 4 символа, чтобы отличить два ключа, когда вы меняете один из них. Когда у источника данных есть ключ, бот отправляет его в заголовке Authorization: Bearer при каждом запросе, а сам адрес остаётся чистым.

В окне «Добавить источник данных» выберите ключ в поле Ключ API. «Ключ не требуется» подходит для большинства публичных API. Если сохранённых ключей пока нет, поле говорит «Ключей API пока нет. Добавьте ключ в Настройках, затем выберите его здесь.», а ссылка Открыть ключи API ведёт в Настройки.

05Лимиты и задержки

Цифры ниже действуют в эксплуатации. Кэш вы заметите первым: ответ, который бот уже получил, повторно используется 30 секунд, поэтому команда, запущенная 40 раз за минуту, всё равно обращается к вашему API только дважды.

06Что показывает чат при сбое

Команда никогда не замолкает из-за источника данных. Остаток фразы всё равно уходит, а значение остаётся пустым, если только вы не написали запасной вариант после вертикальной черты: {urlfetch:weather|недоступно} выведет «недоступно», когда получение не удалось. Источник, который приостановлен, отсутствует или не может выдать значение, работает так же: чат и таймеры показывают значение |default токена. Без |default чат выводит токен как есть, как его ввели, поэтому голый {urlfetch:weather} в чате означает «проверьте этот источник данных».

Если что-то пошло не так

07Чего источник не сделает

• Адрес фиксируется при сохранении. {args} и {user} внутри веб-адреса остаются без изменений, поэтому зритель не может направить запрос на ваш API.
• Запросы выполняются методом GET, а заголовки задавать не вам. Единственный, который добавляет бот, это Authorization: Bearer, и только если у источника есть ключ.
• Токены раскрываются в ответах пользовательских команд, после проверок прав, эфира и кулдауна, а также в сообщениях таймеров, при каждом срабатывании. Сообщение таймера может ссылаться не более чем на 3 разных источника данных. Счётчики не трогают токен.
• Повторно воспроизведённое сообщение чата никогда не запрашивает данные дважды. Если бот перечитывает старое событие, чат получает пустое место (или ваш запасной вариант), а не второй вызов вашего API.
• Частные и локальные адреса отсекаются с обоих концов: при сохранении и снова во время запроса.