Public : [r_my_fb3_notes] Получение пользователем своих заметок/закладок на книгу в формате fb3

Created by Кристина Курашова, last modified by Сергей Перов on Apr 19, 2021

Метод используется для получения списка закладок/заметок для книги.

См. также:

[w_replace_my_fb3_notes] Перезапись выделений/цитат; 

[w_set_bookmark_lock] Запросить блокировку выделения/цитаты.

ID функции

r_my_fb3_notes

Кто может вызывать

Авторизованный пользователь
Авторизованное приложение

Принимаемые параметры

art* – ID книги, закладки от которой нас интересуют
group – ID группы, закладки из которой нас интересуют. Если не передан – сервер вернёт все закладки. Имеются следующие «базовые» группы (классы выделения):

0 – текущая позиция в тексте (в этом классе закладка всегда одна);
1 – закладка;
2 – важная закладка;
3 – стандартная заметка;
4 – важная заметка;
5 – выделение;
6 – важное выделение;
7 – задано приложением I;
8 – задано приложением II;
9 – прочее;
100 – сообщение об ошибке/опечатке. Ожидается, что атрибут selection_text при этом будет содержать откорректированный пользователем текст, а в атрибут note – замечания;
101 – принятое сообщение об ошибке/опечатке;
102 – отвергнутое сообщение об ошибке/опечатке;
110 – сообщение о нарушении, недопустимый контент;
111 – принятое сообщение о нарушении;
112 – отвергнутое сообщение о нарушении;
150 – фрагмент, на который надо обратить внимание автору (предполагает непустой атрибут note);
152 – фрагмент, обсуждение которого с автором завершено.

Возвращаемые значения

my_notes* – массив, содержащий список заметок/закладок данной книги:

  • id* – ID заметки;
  • revision* – номер ревизии книги, для которой была сохранена заметка
  • group* – группа (см. параметр group в запросе выше);
  • last_update* – время последней модификации записи;
  • percent* – позиция (процент) начала заметки/выделения в книге (например 5.565);
  • xpath_start* – адрес начала выделения, подробнее про возможные форматы ниже в разделе «Форматы адресов выделений»;
  • xpath_end – адрес конца выделения (если отсутствует, выделение соответствует «точке»);
  • class – Расширение атрибута group. Если приложению не хватает 9-и предопределенных групп, можно «надстраивать» расширенную классификацию;
  • title – заголовок заметки, заданный пользователем (plain-text);
  • note – заметка пользователя, строка html, набор <p>, внутри допускаются теги strong/em/sub/sup/code/strike;
  • selection_text – текст выделения, по формату идентичен note, такое же подмножество html, как note.
  • epub - «1», если закладка из книги, зарелиженной в epub-формате. В ином случае данное отсутсвует.

Если закладки/заметки для книги отсутствуют, то массив my_notes будет пустым.

Форматы адресов выделений

FB3 XPath

Данный формат используется, если параметр epub не передан.

Любой FB3 XPath начинается с «/1», который с технической точки зрения не учитывается (однако, является обязательным). Далее следует номер секции, соответствующей позиции. После этого идёт путь к целевому узлу, состоящий из абсолютных индексов узлов.

В конце, после точки, указывается смещение в символах с начала целевого узла.

Пример.

Примером такого формата является «/1/2/16.5», что соответствует пятому символу в 16-м абзаце второй секции.

EPUBCFI

В случае, если параметр epub="1", то в поле xpath_start будет содержаться запись в формате EPUBCFI.

Примечание: спецификация EPUBCFI предполагает достаточно много дополнительных атрибутов и возможностей, которые мы на данный момент осознано игнорируем. Здесь описан формат в том виде, в котором с ним предполагается работать именно в рамках Catalit.

Путь до узла в EPUBCFI состоит из чисел, разделённых символом «/». Причём, элементы дерева нумеруются чётным числами начиная с 2 (2 — для первого узла, 4 — для второго, 6 — для третьего и т. д.), в то время как текстовые узлы нумеруются нечётными числами, начиная с 1 (1 — для первого текстовая узла, 3 — для второго, 5 — для третьего и т. д.).

Таким образом, например путь «/12/4/7» будет соответствовать четвёртому текстовому узлу внутри второго элемента внутри шестого элемента.

В самом формате сначала указывается путь до узла нужной секции в Package Document (предполагается путь до узла <itemref> внутри <spine>). Далее следует знак «!», после которого уже указывается путь до узла заметки в нужной секции относительно корня. После пути возможно указание смещения в количестве символов, которое записывается  после знака «:».

Пример.

Примером такого формата является «/6/4!/4/10/3:10», что соответсвует главе, находящейся во втором элементе внутри третьего элемента в Package Document, внутри которого мы выбираем второй элемент → пятый элемент → второй текстовый узел, и далее смещаем символ на 10 (стоит отметить, что смещение опционально).

Также, в отличие от FB3 XPath, EPUBCFI имеет возможность сразу описать диапазон. Записывается это в формате P,S,E, где P — корень, а S и E — начало и конец пути соотвественно относительно корня. Тогда начальный EPUBCFI будет PS, а конечный — PE.

Пример.

Примером диапазона будет строка «/6/4!/4/10,/2/1:1,/3:4», которая по сути просто собирается в два EPUBCFI — начальный («/6/4!/4/10/2/1:1») и конечный («/6/4!/4/10/3:4»).

Возможные ошибки

error_code

error_message

Описание

101061

invalid format art ID

Некорректный формат данных в параметре art. Допустимы только целые положительные числа от 1000 до 999999999999.

101062

Несуществующая книга

Книга, заметки к которой запрошены, не существует в каталоге ЛитРес

Пример запроса на сервер

{
   "app": "1",
   "time": "2014-11-07T16:21:02+03:00",
   "sha": "b79d8e9993d20da6abe78838d3c7fbf640a4c52956569bef3c685d3453316b5c",
   "sid": "7bad5f2fb752ee957a4ab74aaac7711g",
   "requests": [
           {
                 "func": "r_my_fb3_notes",
                 "id": "my_notes",
                 "param": {
                   "art": "568640"
                 }
           }
   ]
}

Пример ответа сервера

{
   "success": true,
   "time": "2014-11-07T16:21:02+03:00",
   "my_notes" : {
      "success" : true,
      "my_notes": [
      {
        "id": "65830123-26b8-4b07-8098-c18229e5026e",
        "group": "0",
        "last_update": "2014-11-07T16:21:02+03:00",
        "xpath_start": "/1/2/16.5"
      },
      {
        "id": "65830123-26b8-4b07-8098-c18229e5026f",
        "group": "1",
        "last_update": "2014-11-07T16:21:15+03:00",
        "xpath_start": "/1/2/15.5",
        "xpath_end": "/1/2/16.35",
        "title": "Вот я тут выделил че-то",
		"selection_text": "<p>Книга выдающегося советского ученого Л.&nbsp;С.&#160;Выготского «Психология искусства» вышла первым изданием в 1965&#160;г., вторым – в 1968&#160;г. и&#160;завоевала всеобщее признание. В ней автор резюмирует свои работы 1915–1922 годов и вместе с тем готовит те <strong>новые</strong> психологические идеи, которые составили главный вклад Выготского в науку. «Психология искусства» является одной из фундаментальных работ, характеризующих развитие советской теории и искусства.</p><p>Книга рассчитана на специалистов – эстетиков, психологов, искусствоведов, а также на широкий круг читателей.</p>"
        "note": "<p>Это место особенно удачное!</p>",
		"epub": "1"

      }
    ]
  }
}