Как использовать API Скретча с помощью Node.js

Эта статья или раздел может иметь содержание, не соответствующее стандартам Скретч Вики. Пожалуйста, улучшите её в соответствии с правилами и рекомендациями по редактированию.

Этот раздел или статья не предназначена для новичка! Она содержит сложную информацию.

На Scratch можно делать ботов с помощью различных языков программирования. Это руководство поможет Вам запрограммировать своего бота с помощью JavaScript и фреймворком Node.js. Если Вы не знаете JavaScript, вот некоторые ресурсы, которые Вам могут помочь в его изучении:

• Современный учебник JavaScript;
• MDN web docs.

Внимание! Пожалуйста, не используйте ботов, чтобы нарушать правила сообщества и/или условия использования Scratch (например, спам-рассылка или масс-репорт)! Вас могут забанить не только по аккаунту, но и по IP-адресу.

Подготовка

Установка Node.js

Для начала Вам нужно установить Node.js на свой компьютер.

Если у Вас Windows 8.1 и позднее: зайдите на страницу загрузки Node.js и установите версию LTS, т. к. в последней могут быть баги.

Если у Вас Windows 7 или 8: установите Node.js v13.14.0 (64-бит) или Node.js v13.14.0 (32-бит), в зависимости от разрядности Вашей системы. Это последняя версия, которая поддерживает Windows 7/8.

Скриншот

При установке не забудьте отнять галочку у «Automatically install the necessary tools.» Это установит Python и Visual Studio Build Tools для C/C++, и это нам пока что не надо.

Настройка проекта

После установки Node.js, Вы теперь готовы к созданию проекта для бота! Создайте папку в любом удобном Вам месте и откройте командную строку оттуда. Это можно сделать, написав «cmd» (без кавычек) в адресной строке проводника.

Затем напишите:

npm init -y

Это автоматически настроит проект. Если у Вас что-то пошло не так, то напишите:

npm init

Вас спросят некоторые вопросы для настройки проекта.

Установка scratch3-api

scratch3-api — модуль для Node.js, с помощью которого можно удобно использовать API Scratch'а. На данный момент к сожалению обновление до TypeScript его поломало, но есть версия без этого обновления — new-scratch3-api.

Чтобы установить данный модуль, в командной строке в Вашем проекте напишите:

npm i new-scratch3-api

Теперь давайте приступим к программированию нашего бота! Вот самая основа:

const Scratch = require('new-scratch3-api'); // Импортирует scratch3-api в наш скрипт.
 
async function main() {
	let session = await Scratch.UserSession.create('ЭпичныйНикАккаунтаЗдесь', 'ЭпичныйПарольЗдесь123'); // Создаёт «пользовательскую сессию» — в других словах, входит в аккаунт и сохраняет данные аккаунта в переменную session.
	// Сделать что-то...
}

main()

Этот скрипт просто входит в аккаунт.

Запустить скрипт

Для запуска скрипта напишите в командной строке это:

node имяСкрипта

Например, если у Вас файл с скриптом называется script.js, то Вам надо написать:

node script.js

Можно также:

node script

Уроки

Для официальной документации зайдите на GH репозиторию scratch3-api (англ.): https://github.com/ErrorGamer2000/scratch3-api

Как отправить комментарий

С помощью этой функции можно отправить комментарий:

await session.comment(options)

options — объект с ключами:

• project, user или studio в зависимости от куда Вы хотите отправить комментарий. user должен быть никнеймом, а project и studio — id.
• parent — необязателен. «Родитель» комментария, то есть id комментария, на который отвечают.
• replyto — необязателен. Никнейм того, на которого отвечаешь. Можно не писать, но уведомления в сообщениях не будет.
• content — текст комментария.

Пример объекта:

{
 	user: 'aPPDATA_PRODAKSHNS',
	content: 'Привет из scratch3-api!'
}

Пример использования:

await session.comment({
 	project: 517816449,
 	content: 'Крутой проект!'
});

Как получить список своих проектов

В этом поможет эта функция:

await session.projects.getUserProjects(count);

Она возвращает count последних проектов. Пример использования:

let projects = await session.projects.getUserProjects(42);

Как получить статус серверов Scratch

await Scratch.Rest.getHealth();

Эта функция возвращает «здоровье» серверов Scratch. Пример использования:

const status = await Scratch.Rest.getHealth();

Как получить комментарии у профиля

Получить комментарии в удобном формате по типу JSON нельзя. API Scratch'а даёт доступ к комментариям только через site-api, который даёт HTML код комментариев, но он считается устаревшим начиная с 2015 г., однако до сих пор работающий и доступный. Его URL:

https://scratch.mit.edu/site-api/

Чтобы получить комментарии у профиля, нужно сделать GET запрос сюда:

https://scratch.mit.edu/site-api/comments/user/ник/

Вот пример, как пропарсить HTML, получить информацию о комментарии и добавить его в массив:

// npm i @sapphire/fetch node-html-parser
const { fetch, FetchResultTypes } = require('@sapphire/fetch');
const username = 'griffpatch'; // Замените на ник профиля, у которого Вы хотите получить комменты
var HTMLParser = require('node-html-parser'); //Импортируем HTML парсер для удобного взаимодействия с HTML

(async () => {
  const resp = await fetch(`https://scratch.mit.edu/site-api/comments/user/${username}/`, FetchResultTypes.Text);
  var body = HTMLParser.parse(resp);
  let comments = [];
  body.querySelectorAll('.comment').forEach(element => { // Для каждого элемента комментария
    comments = comments.concat({ //Добавляем новый элемент в массиве
      author: element.getElementById('comment-user').getAttribute('data-comment-user'), //Получаем элемент с ником создателя и получаем атрибут с ником
      content: element.querySelector('div.content').text.trim(), // Получаем элемент с текстом («контентом») комментария и получаем его текст
      date: new Date(Date.parse(element.querySelector('.time').getAttribute('title'))) //Довольно запутанно, но это получает элемент с датой и получает аргумент title, где находится дата в формате ISO 8601 и парсит его в объект Date
    })
  });
  console.log(comments)
})()

Этот же код заработает и с проектами/студиями, нужно просто поменять URL на:

https://scratch.mit.edu/site-api/comments/gallery/id/ (для студий)
https://scratch.mit.edu/site-api/comments/project/id/ (для проектов)

Как получить ремиксы у проекта?

В данном модуле к сожалению нет такой функции, но надо сделать HTTP GET запрос на данный URL:

https://scratch.mit.edu/projects/id/remixtree/bare/

Замените «id» на id проекта. Вот код для создания HTTP запроса:

• с помощью @sapphire/fetch:

const resp = await fetch('https://scratch.mit.edu/projects/104/remixtree/bare/', FetchResultTypes.JSON);

• с помощью phin:

const resp = await p({
	url: 'https://scratch.mit.edu/projects/104/remixtree/bare/',
	parse: 'json'
})

Примеры

Комментировать кол-во сообщений у griffpatch на своём профиле

В scratch3-api нету функции просмотра кол-во сообщений, поэтому придётся делать HTTP запрос на API Scratch.

const Scratch = require('new-scratch3-api');
const { fetch, FetchResultTypes } = require('@sapphire/fetch'); //Модуль для HTTP запросов (npm i @sapphire/fetch)
 
async function main() {
	let session = await Scratch.UserSession.create('ЭпичныйНикАккаунтаЗдесь', 'ЭпичныйПарольЗдесь123');
	const resp = await fetch('https://api.scratch.mit.edu/users/griffpatch/messages/count', FetchResultTypes.JSON); // Посылает запрос на API Scratch для получения кол-во сообщений и парсит его JSON
	await session.comment({
		user: 'ЭпичныйНикАккаунтаЗдесь',
		content: `Количество сообщений у @griffpatch — ${resp.count}`
	})
}

main()

Получить информацию о пользователе

const Scratch = require('new-scratch3-api');

async function main() {
	let user = Scratch.Rest.Users.get("aPPDATA_PRODAKSHNS");
	console.log(`Информация о aPPDATA_PRODAKSHNS: ${user}`);
}
// Здесь нет сессии, т. к. она необязательна для Rest API.

main()

Задать облачной переменной значение 5

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

const Scratch = require('new-scratch3-api');

async function main() {
	let session = await Scratch.UserSession.create('ЭпичныйНикАккаунтаЗдесь', 'ЭпичныйПарольЗдесь123');
	let cloud = await session.cloudSession(idПроектаЗдесь); // Создаёт «облачную сессию» — подключается к проекту.
	cloud.set('☁ var', 5); // Задаёт облачной переменной «var» значение 5. Название переменной нужно писать с эмодзи облака
}

main()

См. также

• Скретч API;
• ScratchClient (библиотека для Python).