Telegraph API: что не пишут в интернете

[zHz00]

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

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

(читать дальше)

На самом деле у телеграфа проблема только одна: лапидарная документация. Но проблема эта глобальная. Она рассыпается на множество проблем поменьше. А те, в свою очередь, на малюсенькие проблемки ваще жесть. Да, документация не обновлялась с 2016 года.

Все проблемы я нумерую, чтобы получился FAQ.

1.
Q: Я обыскал весь сайт телеграфа, и даже под табуреткой смотрел, но не смог найти токенов для доступа! Где они?
A1: Если вы собираетесь работать с телеграфом только через АПИ, то вызовите функцию createAccount. От неё вы получите токен. Его следует использовать всегда, пока вы пользуетесь именно этим аккаунтом.
A2: Если вы создали аккаунт через бота @Telegraph, то залогиньтесь в браузере, а потом поищите токен в кукисах. Да, другого метода нет.

2.
Q: Что я только не совал в createPage, а он пишет CONTENT_FORMAT_INVALID или CONTENT_TEXT_REQUIRED. Что не так-то?
A: Формат входных данных -- Array of Node, написано в документации. Пример есть, но он не иллюстрирует суть. Ещё приведён кусок кода на ява-скрипте, который генерирует нужный формат. Но это немного не то, что ожидается от документации.

Есть примеры в интернете, но там везде приведён ОДИН нод. Или два, но вложенных. А где Array-то? Примеров, где действительно несколько нодов подряд -- нету. На самом деле всё было бы гораздо проще, если бы авторы документации написали, что формат -- JSON. Итак, что значит Array? Это список значений в квадратных скобках, разделённых запятыми, вот так:
["Value1","Value2","Value3"]
Согласно документации, каждый элемент массива может быть либо текстом, либо нодом. Вот тот пример, который искал я:
["Goodbye,",{"tag":"b","children":["cruel"]},"world"]
Любые чилдрены также являются array of node. Если не знаете, как записывается та или иная разметка, создайте пасту в браузере, а потом в инструментах разработчика поищите запрос, который браузер послал серверу. Там используется именно этот удивительный формат.

3.
Q: Я научился делать пасты в формате array of node, но периодически всё равно получаю сообщение про инвалидов, или нечто подобное. В чём может быть дело?
A: В отличие от интерпретатора Питона, Телеграф не сообщает о местах, которые ему не нравятся. Но вот какие соображения есть:
1. Парсер телеграфа очень чувствителен к тому, что вы ему даёте. Он, например, не терпит запятой после последнего элемента списка. Пустой список ему тоже непонятен. Пустой элемент списка (т.е. две запятые подряд) -- опять проблемы.
2. Надо экранировать бэкслешем: одинарные, двойные кавычки и... сам бэкслеш! Обратная косая черта в смайлике ¯\_(ツ)_/¯ мне чуть голову не выела. Я думал, что Телеграф иероглифы не понимает. Но с этим как раз всё оказалось отлично.

4.
Q: Картинки-то, картинки как грузить? Я уверен, что они грузятся на сервера телеграфа.
A1: Загрузка картинок ЕСТЬ, но она не является частью телеграф-апи. Загрузка осуществляется по адресу:

https://telegra.ph/upload

(заметили, что нет префикса "api." ?). Файл надо передать в пост-запросе в поле file: при помощи технологии, которая называется multipart/form-data. Токен НЕ нужен. В Питоне это делается так:

requests.post("https://telegra.ph/upload",files={"file":image_file})

Ответом на это будет МАССИВ (в терминах телеграфа). Например, такой:
[{"src":"\/file\/e80f65644eccf184d86c2.png"}]
Обращаю внимание, что ответы от телеграф-апи имеют совершенно иной формат, начинающийся с поля "ok", например. такой:
{"ok":false,"error":"CONTENT_FORMAT_INVALID"}
Видите, нет квадратных скобок?
A2: Хотя сервера телеграфа и поддерживают загрузку картинок, это загрузка "без правил". Никто не знает, сколько они там будут храниться, и в каком формате. Но телеграф поддерживает и хотлинкинг с других хостингов. Поэтому если вам другие хостинги по душе -- вставляйте картинки с них.

5.
Q: Я сделал пост с текстом и картинками, послал его, но картинки оказались в конце. Какого хуя?
A: Я не могу это объяснить, но если на самом верхнем уровне массива нод размещать"просто текст", как я показал выше в примерах с Value1 и Goodbye, то картинки и текст отображаются не в том порядке, что написано. При этом в хтмл-исходниках чистым по белому написано:

hello1<img src="...">hello2

И всё равно картинка в конце. Видимо, этому есть какая-то HTML-причина, о которой я не знаю. Чтобы такой проблемы не было, не размещайте текст "сам по себе". Всё должно быть обёрнуто див-ами. Да, документация пишет, что дивы не поддерживаются, однако сам телеграф, когда сохраняет свои страницы, дивы использует очень активно.

6.
Q: Как удалить картинку/пасту/аккаунт?
A: Никак. С картинками всё совсем тяжело, никакой информации о том, сколько она хранится, нету. Пасту нельзя удалить, однако её можно очистить и сохранить с одним, скажем, символом. Про аккаунт можно просто забыть и создать новый.

7.
Q: Отредактировать запись я могу, а урл изменить как?
A: Увы, опять никак. Урл генерируется по системе "транслитерация заголовка+месяц создания+день создания". Если имя уже есть, то в конец дописывается -1, -2 и т.д. Дописываемое число не ограничено (я доходил до 18).

8.
Q: Не совсем про АПИ. Я дома написал и опубликовал статью. Анонимно. Потом вторую -- на работе. Анонимно. Третью натыкал с телефона. А потом узнал, что можно создать аккаунт. Что мне теперь делать?
A: Редактирование уже созданных постов доступно только с того устройства, где их создали. И должны быть целы кукисы. Но!

Когда вы создаёте аккаунт через бота @Telegraph, то при попытке залогиниться в браузере вас спросят, хотите ли вы присоединить имеющиеся пасты к аккаунту или нет. Так можно залогиниться на всех устройствах, где вы творили, и собрать всех покемонов в одну кучу. После этого радактирование будет доступно на всех устройствах.

Проблемы, которые я не решил
1. Как определяется картинка и описание по методу OpenGraph? Судя по всему, именно эти поля используются в телеграме при предварительном просмотре поста. Их можно получить при помощи метода getPage. Но как их задать? Картинка, видимо, выдаётся первая по счёту. Описание составляется из первых фраз поста. Но во время экспериментов я видел и иное поведение.
2. Почему Instant View не всегда доступен? Ясно, что он будет виден только на телефоне, но и там не всё гладко. С одной пастой так долбился, инстант вью никак не появляется. А потом сгенерировал новую, и он появился. Пока что есть два соображения, и оба связаны с картинками.
а) Когда у меня в пастах были тестовые пнг размером 1 на 1 пиксель, я не видел инстант вью. (но при этом если картинок нет вовсе -- инстант вью есть!)
б) Когда картинки были не с хостинга телеграфа, а с постороннего -- инстант вью также не появился.

Ссылка на официальную документацию: telegra.ph/api
Единственная вразумительная статья на тему: habr.com/ru/post/587430/

Comments

[RetXiRT suiR@ttig@$]

А почему уёбок-то? +(

[zHz00]

RetXiRT suiR@ttig@$, это юмор такой.

[Гость]

Хоть я и не кодер, но мне было любопытно это читать. Хотя, должен признать, что сначала я думал - это что-то про новостные сайты. Ведь есть сайт Telegraph. Почему-то дальше по тексту меня вела надежда, что будет всё-таки про новости. Надежда, с первых строк очевидно необоснованная.

Omega

[Гость]

Ладно, если более откровенно, то должен признать, что читал я не все. Порог понимания высоковат. Но про пасты, инвалидов и особенно нерешённые проблемы я правда читал. Удивительно, насколько неудобная штуковина.

Omega

[Гость]

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

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

С другой стороны, если бы это был гей-сериал...

Кстати, вы слышали анекдот про Эйнштейна, Ньютона и Паскаля?

[zHz00]

Omega. Telagra.ph -- новостной сайт)) просто у него нет навигации))) Он предназначен для того, чтобы люди публиковали ссылки на него в телеграме.

Который анекдот, там где ньютон рисовал вокруг себя квадрат?

[Гость]

То есть, сначала интуиция меня не подвела, а потом я сам себя обманул. Надо верить интуиции.

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

[zHz00]

Вот вам тогда другой, более сложный.

Едут Гейзенберг, Шрёдингер и Ом в машине. Их останавливает полиция.

Полиция: Вы знаете, с какой скоростью вы ехали?
Гейзенберг: Нет, зато я знал, где я.
Полиция: Вы ехали 130!
Гейзенберг: Ну спасибо, теперь я не знаю, где нахожусь!

Полиции это кажется странным, и они просят открыть багажник.
Полиция: А вы знаете, что у вас в багажнике мёртвый кот?
Шрёдингр: Ну спасибо, теперь знаем!

Полиции кажется это странным и она решает арестовать всех троих. Ом оказывает сопротивление.

[Гость]

Я засмеялся на Оме, хотя казалось бы, это самый предсказуемый персонаж из всех участников) Про Гейзенберга напротив, было сложнее всего, но честно, я не гуглил принцип неопределенности!