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

{{правила вики}}{{Не для новичков}}
[[Категория:Руководства]]
На [[Scratch]] можно делать [[Боты|ботов]] с помощью различных языков программирования. Это руководство поможет Вам запрограммировать своего бота с помощью [https://ru.wikipedia.org/wiki/JavaScript JavaScript] и фреймворком [https://ru.wikipedia.org/wiki/Node.js Node.js].
Если Вы не знаете JavaScript, вот некоторые ресурсы, которые Вам могут помочь в его изучении:
* [https://learn.javascript.ru/ Современный учебник JavaScript];
* [https://developer.mozilla.org/ru/docs/Learn/JavaScript/First_steps MDN web docs].
{{Важно|Пожалуйста, не используйте ботов, чтобы нарушать [https://scratch.mit.edu/community_guidelines правила сообщества] и/или [https://scratch.mit.edu/terms_of_use условия использования Scratch] (например, спам-рассылка или [[Массрепорт|масс-репорт]])! Вас могут забанить не только по аккаунту, но и по IP-адресу.}}
= Подготовка =
== Установка Node.js ==
Для начала Вам нужно установить Node.js на свой компьютер.

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

Если у Вас Windows 7 или 8: установите [https://nodejs.org/download/release/v13.14.0/node-v13.14.0-x64.msi Node.js v13.14.0 (64-бит)] или [https://nodejs.org/download/release/v13.14.0/node-v13.14.0-x86.msi Node.js v13.14.0 (32-бит)], в зависимости от разрядности Вашей системы. Это последняя версия, которая поддерживает Windows 7/8.

[[Файл:Chocolatey.PNG|мини|справа|Скриншот]]
При установке не забудьте отнять галочку у «Automatically install the necessary tools.» Это установит Python и Visual Studio Build Tools для C/C++, и это нам пока что не надо.
== Настройка проекта ==
После установки Node.js, Вы теперь готовы к созданию проекта для бота! Создайте папку в любом удобном Вам месте и откройте командную строку оттуда. Это можно сделать, написав «cmd» (без кавычек) в адресной строке проводника.

Затем напишите:
 npm init -y
Это автоматически настроит проект. Если у Вас что-то пошло не так, то напишите:
 npm init
Вас спросят некоторые вопросы для настройки проекта.
== Установка scratch3-api ==
[https://github.com/ErrorGamer2000/scratch3-api scratch3-api] — модуль для Node.js, с помощью которого можно удобно использовать [[Скретч API|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 — [https://developer.mozilla.org/ru/docs/Web/JavaScript/Guide/Working_with_Objects объект] с ключами:
* 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 г.<ref>[[Скретч API#site-api_.28.D0.A3.D1.81.D1.82.D0.B0.D1.80.D0.B5.D0.BB.29|site-api - устаревший интерфейс, который стал официально устаревшим 25 октября 2015, как объявил член Команды Скретч, thisandagain.]]</ref>, однако до сих пор работающий и доступный. Его 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);
* с помощью [http://npm.io/phin 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|ScratchClient (библиотека для Python)]].
<references/>