Спецификация операций запросов ErisPulse
Tip
Когда нужно читать эту статью: когда вашему адаптеру нужно обрабатывать запросы от друзей/приглашения в группы (преобразование событий запросов, реализация accept/reject, сохранение контекста запросов с гетерогенными эндпоинтами), или когда модули используют event.approve() / event.reject() для одобрения запросов. Если не нужно, то можно пропустить.
В этом документе определены стандартизированные спецификации операций запросов в адаптере ErisPulse, включая требования к полям запроса, использование DSL для запроса и требования к реализации адаптера.
1. Обзор
Событие запроса (type: "request") — это специальный тип события, определенный в OneBot12, представляющий запрос, требующий принятия решения ботом (например, запрос на добавление в друзья, приглашение в группу и т.д.).
В отличие от событий сообщений, запросы требуют двустороннего взаимодействия:
- Прием: адаптер преобразует платформенный оригинальный запрос в стандартное событие запроса
- Ответ: модуль выполняет операции через DSL для запроса или
Event.approve()/Event.reject().
Событие платформенного запроса
│
▼
Converter.convert() ← Реализация адаптера (прямое преобразование)
│
▼
Стандартное событие запроса (с request_id)
│
├─→ Обработчик модуля @request.on_friend_request()
│ │
│ ├─→ event.approve() ← Согласие с запросом
│ └─→ event.reject() ← Отказ в запросе
│ │
│ ▼
│ adapter.Request(request_id).accept()
│ │
│ ▼
│ BaseAdapter.Request.accept() ← Переопределение адаптером
│ │
│ ▼
│ Вызов API платформы
│
└─→ Или напрямую через операции адаптера
await adapter.Request("req_id").accept()
2. Требования к полям запроса
2.1 Стандартные поля
Событие запроса, помимо обязательных полей OneBot12, должно содержать следующие поля:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
request_id |
string | Рекомендуется | Идентификатор запроса, используется для согласия/отказа |
user_id |
string | Да | Идентификатор отправителя запроса |
user_nickname |
string | Нет | Никнейм отправителя запроса |
comment |
string | Нет | Комментарий к запросу |
2.2 Поле request_id
request_id является ключевым идентификатором для запроса:
- Назначение: идентификация запроса, используемого для операций через DSL для запроса
- Правила генерации:
- В первую очередь использовать оригинальный идентификатор платформы (например,
flagиз OneBot11,chat_invite_linkиз Telegram и т.д.) - Если платформа не предоставляет оригинальный идентификатор, адаптер должен сгенерировать уникальный идентификатор (рекомендуемый формат:
{platform}_{timestamp}_{user_id})
- В первую очередь использовать оригинальный идентификатор платформы (например,
- Уникальность: в рамках одной платформы должен быть уникален
- Поведение при отсутствии: если
request_idотсутствует,event.approve()/event.reject()выбросятValueError
2.3 Пример события запроса
{
"id": "evt_123456",
"time": 1752241225,
"type": "request",
"detail_type": "friend",
"platform": "onebot11",
"self": {
"platform": "onebot11",
"user_id": "bot_123"
},
"user_id": "user_456",
"user_nickname": "YingXinche",
"comment": "Пожалуйста, добавьте в друзья",
"request_id": "flag_abc123",
"onebot11_raw": {...},
"onebot11_raw_type": "request"
}
3. DSL для запроса
3.1 Цепочечные вызовы
Request предоставляет интерфейс цепочечных вызовов, аналогичный Send:
# Базовое использование
await adapter.Request("req_id").accept()
await adapter.Request("req_id").reject()
# Указание аккаунта бота
await adapter.Request("req_id").Using("bot1").accept()
# Добавление комментария (через kwargs)
await adapter.Request("req_id").accept(comment="Добро пожаловать")
await adapter.Request("req_id").reject(comment="Временно не добавляю")
# Комбинированные вызовы
await adapter.Request("req_id").Using("bot1").accept(comment="Добро пожаловать")
3.2 Список методов
| Метод | Описание | Возвращаемое значение |
|---|---|---|
Using(account_id) |
Указывает аккаунт бота для выполнения операции | RequestDSL (поддерживает цепочечные вызовы) |
accept(**kwargs) |
Согласие с запросом | asyncio.Task (возвращает стандартный ответ после await) |
reject(**kwargs) |
Отказ в запросе | asyncio.Task (возвращает стандартный ответ после await) |
3.3 Формат возвращаемых значений
Операции возвращают стандартный формат ответа API:
Успех:
{
"status": "ok",
"retcode": 0,
"data": null,
"message_id": "",
"message": ""
}
Ошибка:
{
"status": "failed",
"retcode": 34001,
"data": null,
"message_id": "",
"message": "Запрос просрочен или не существует"
}
Не реализовано (адаптер не переопределил _do_accept/_do_reject):
{
"status": "failed",
"retcode": 10002,
"data": null,
"message_id": "",
"message": "Платформа MyAdapter не реализовала операцию запроса (accept)"
}
4. Удобные методы Event
Класс Event предоставляет удобные методы, подходящие для использования в обработчиках событий запроса:
from ErisPulse.Core.Event import request
@request.on_friend_request()
async def handle_friend_request(event):
# Проверка идентификатора запроса
request_id = event.get_request_id()
if not request_id:
print("Предупреждение: событие запроса не содержит request_id")
return
# Согласие с запросом
result = await event.approve()
# Или отказ в запросе
# result = await event.reject(comment="Временно не добавляю в друзья")
# Проверка результата
if result.get("status") == "ok":
print("Операция выполнена успешно")
else:
print(f"Операция не удалась: {result.get('message')}")
4.1 Список методов Event
| Метод | Описание | Возвращаемое значение |
|---|---|---|
get_request_id() |
Получает идентификатор запроса | str |
approve(comment=None) |
Согласие с текущим событием запроса | Стандартный формат ответа |
reject(comment=None) |
Отказ в текущем событии запроса | Стандартный формат ответа |
5. Требования к реализации адаптера
5.1 Требования к конвертеру
Конвертер адаптера при преобразовании событий запроса обязан корректно устанавливать поле request_id:
def convert_request_event(self, raw_event: dict) -> dict:
"""Преобразование нативного события запроса платформы"""
return {
"id": self._generate_event_id(raw_event),
"time": int(time.time()),
"type": "request",
"detail_type": self._map_request_type(raw_event), # "friend" или "group"
"platform": self._platform_name,
"self": {
"platform": self._platform_name,
"user_id": str(self._bot_id),
},
"user_id": str(raw_event.get("user_id", "")),
"user_nickname": raw_event.get("nickname", ""),
"comment": raw_event.get("message", ""),
"request_id": self._extract_request_id(raw_event), # ← ключевое поле
f"{self._platform_name}_raw": raw_event,
f"{self._platform_name}_raw_type": raw_event.get("type", ""),
}
def _extract_request_id(self, raw_event: dict) -> str:
"""
Извлечение ID запроса из нативного события платформы
Приоритетно используется нативный идентификатор запроса платформы,
при его отсутствии генерируется уникальный ID
"""
# Приоритетно используется нативный ID платформы
if flag := raw_event.get("flag"):
return str(flag)
if request_key := raw_event.get("request_key"):
return str(request_key)
# Запасной вариант: генерация уникального ID
import hashlib
raw = f"{self._platform_name}_{raw_event.get('user_id')}_{raw_event.get('timestamp')}"
return hashlib.md5(raw.encode()).hexdigest()
5.2 Реализация внутреннего класса Request
accept() / reject() базового класса — это публичные точки входа: встроенный шлюз авторизации scope (scope.actions.<owner>.request, при отключении сразу возвращает ответ с отказом 34601) и обёртка задачи. Адаптер не должен переопределять публичные точки входа — переопределение обойдёт шлюз авторизации. Адаптер переопределяет _do_accept / _do_reject (асинхронные методы, напрямую возвращающие стандартный dict ответа).
Напоминание о мультиаккаунтности: внутри
_do_accept/_do_rejectадаптер сам вызываетcall_api, аккаунт не внедряется автоматически — аккаунт получается черезself.request_context.get("account_id")(явное указаниеUsing()> автоматическая привязка по цепочке событий, тот же принцип, что иsend_contextу Send) и передаётся вcall_apiкак параметрaccount_id, иначе при мультиаккаунтном развёртывании операция попадёт на аккаунт по умолчанию.
from ErisPulse.Core import BaseAdapter, RequestDSL
class MyAdapter(BaseAdapter):
class Request(RequestDSL):
"""Реализация операций запроса MyPlatform"""
async def _do_accept(self, **kwargs) -> dict:
"""
Одобрить запрос
:param kwargs: расширенные параметры, например comment="примечание"
:return: dict стандартного формата ответа
"""
try:
result = await self._adapter.call_api(
endpoint="/set_request",
request_id=self._request_id,
account_id=self.request_context.get("account_id"),
approve=True,
**kwargs,
)
return {
"status": "ok" if result.get("code") == 0 else "failed",
"retcode": result.get("code", 0),
"data": None,
"message_id": "",
"message": result.get("message", ""),
}
except Exception as e:
return {
"status": "failed",
"retcode": 34001,
"data": None,
"message_id": "",
"message": f"Ошибка операции запроса: {e}",
}
async def _do_reject(self, **kwargs) -> dict:
"""Отклонить запрос (изоморфно _do_accept: approve=False)"""
5.3 Сохранение контекста типа запроса (обязательно для адаптеров с гетерогенными эндпоинтами)
5.3.1 Пробел в контракте
DSL Request — это дескриптор без состояния: вызывающая сторона владеет только request_id (§3), тип запроса не входит в параметры вызова. При этом у многих платформ эндпоинты одобрения/отклонения гетерогенны — на примере семейства OneBot11:
| Тип запроса | Эндпоинт |
|---|---|
| Добавление в друзья | set_friend_add_request(flag, approve) |
| Заявка в группу / Приглашение в группу | set_group_add_request(flag, sub_type, approve), sub_type ∈ {"add", "invite"} |
Вызывающая сторона знает только request_id, но для выбора эндпоинта нужен тип. Этот контекст может восполнить только адаптер: события запроса и так принимаются и преобразуются адаптером (информация о типе уже есть в руках в момент преобразования), а тип запроса, соответствующий request_id, не меняется. Если адаптер не сохранит его самостоятельно, остаётся только угадывать эндпоинт или полагаться на нестандартные параметры от вызывающей стороны — типичная форма сбоя: приглашение в группу попадает в эндпоинт для друзей, flag разбирается протокольной стороной как user_id, и возникает ошибка.
5.3.2 Требования спецификации
Для адаптеров платформ с гетерогенными эндпоинтами (одобрение/отклонение требует маршрутизации по типу запроса) реализация accept / reject должна удовлетворять следующему:
- Сохранение на стороне события: в точке входа получения адаптером события запроса записывать
request_id → {тип запроса, sub_type, group_id, аккаунт}в кэш экземпляра (единые поля см. §5.3.3) и попутно очищать устаревшие записи - Маршрутизация на стороне операции: порядок выбора эндпоинта внутри
_do_accept/_do_reject: явные параметры kwargs > кэш > откат к эндпоинту по умолчанию с записью WARNING — при неизвестном типе обязательно логировать (наблюдаемость), молча выбирать эндпоинт нельзя - Зарезервированные имена kwargs: явно переопределяющие параметры именуются единообразно
request_type/sub_type/group_id(без подчёркивания в качестве префикса, одинаковые имена и значения во всех адаптерах); не использовать приватные условные имена вроде_request_type(стандартный вызывающий их не передаёт) - Чтение аккаунта и проверка принадлежности: аккаунт операции получается единообразно через свойство базового класса
self.request_context.get("account_id")(явное указаниеUsing()> автоматическая привязка по цепочке событий, тот же принцип, что иsend_contextу Send); аккаунт прибытия события из сохранённой записи служит запасным вариантом при отсутствии цепочки событий (например, синтезированные события опроса, восстановление после перезапуска). Если аккаунт не удаётся разрешить в конкретный экземпляр аккаунта, обязателен быстрый отказ (возврат 34005), молча откатываться к аккаунту по умолчанию нельзя — откат направит операцию в ошибочное соединение (flag не существует в сессии аккаунта по умолчанию, платформа сообщит invalid, при мультиаккаунтности проявляется как «оперировать может только первый аккаунт») - Персистентность по умолчанию: носителем сохранения по умолчанию является единое хранилище фреймворка (
self.sdk.storage) — полный снимок одним ключом — запросы относятся к низкочастным событиям типа одобрений, write-through выполняется сразу при прибытии события (след в хранилище всегда составляет 1 ключ); при запуске однократная загрузка в память, во время работы путь чтения без накладных расходов; при недоступности хранилища — деградация до режима «только память» (WARNING), поток событий не блокируется - Очистка после обработки: после успешной отправки операции удалить запись
request_idи синхронно выполнить write-through снимка
Для платформ с единым эндпоинтом запросов (например, унифицированный /set_request) сохранение не требуется, достаточно прозрачной передачи. Данный раздел задаёт требования к реализации адаптера, контракт DSL Request при этом не затрагивается.
5.3.3 Единые поля записи (независимо от носителя)
Записи контекста сохраняются в следующей единой форме полей. Форма полей — это контракт интероперабельности: dict в памяти, значение KV, строка ORM — все сохраняются в одной и той же форме, при последующей межадаптерной агрегации или миграции форма остаётся согласованной; носитель хранения выбирается свободно, семантика полей не меняется в зависимости от носителя.
| Поле | Тип | Обязательное | Семантика и источник |
|---|---|---|---|
request_type |
str |
Да | Тип запроса, берётся из detail_type события ("friend" / "group") |
sub_type |
str | None |
Обязательно для групповых запросов | Подтип группового запроса "add" / "invite", берётся из нативного события платформы (sub_type семейства OB11) |
group_id |
str | None |
Обязательно для групповых запросов | ID целевой группы, берётся из нативного события платформы |
account |
str | None |
Обязательно при мультиаккаунтности | Аккаунт прибытия события, берётся из self.user_id события |
ts |
float |
Да | Unix-метка времени прибытия события (в секундах), база для определения TTL |
Правила согласованности записей:
- Взаимно однозначное соответствие: одному
request_idсоответствует не более одной записи; повторные события с тем жеrequest_idперезаписывают её (идемпотентность) - Удаление после обработки: запись удаляется сразу после успешной отправки операции
- TTL: отсчёт от
ts, рекомендуемый порядок — 1 час (покрывает срок действия запроса на стороне платформы); истёкшая запись считается несохранённой, путь — откат к эндпоинту по умолчанию + WARNING - Имя ключа (при KV-персистентности):
{ключ конфигурации адаптера}:request_ctx:{request_id}— во избежание конфликтов между адаптерами
5.3.4 Референсная реализация (снимок одним ключом в едином хранилище, по умолчанию)
Носителем сохранения по умолчанию является единое хранилище фреймворка (self.sdk.storage): события запросов — низкочастные события типа одобрений (запросы в друзья/группы, не поток сообщений), write-through при прибытии события не создаёт нагрузки на запись. Форма хранения — полный снимок одним ключом: весь словарь контекста записывается одним ключом за один раз (след в хранилище всегда составляет 1 ключ, автоматически сокращается по мере обработки), без разделения на ключи по каждому flag. После перезапуска при старте выполняется однократная загрузка в память, во время работы путь чтения без накладных расходов.
import time
from ErisPulse.Core import BaseAdapter, RequestDSL
class MyAdapter(BaseAdapter):
"""Платформа с гетерогенными эндпоинтами запросов (раздельные эндпоинты для запросов в друзья и в группы)"""
_REQ_CTX_TTL = 86400 # Время хранения в секундах (покрывает срок действия flag на стороне платформы, не теряется при перезапуске)
_REQ_CTX_MAX = 512 # Верхний предел количества записей
def __init__(self, sdk=None):
super().__init__(sdk)
self._request_ctx: dict[str, dict] = {} # request_id → контекст запроса (состояние в памяти)
self._ctx_key = f"{self._get_config_key()}:request_ctx" # полный снимок одним ключом
async def start(self):
# Загрузка при старте (одобрение доступно и после перезапуска); при недоступности хранилища трактуется как холодный старт
try:
loaded = self.sdk.storage.get(self._ctx_key, {}) or {}
now = time.time()
self._request_ctx = {k: v for k, v in loaded.items()
if now - v.get("ts", 0) <= self._REQ_CTX_TTL}
except Exception as e:
self.logger.warning(f"Не удалось загрузить контекст запросов (трактуется как холодный старт): {e}")
self._request_ctx = {}
def _persist_ctx(self) -> None:
"""Write-through полного снимка одним ключом (при недоступности хранилища — деградация до режима «только память», поток событий не блокируется)"""
try:
self.sdk.storage.set(self._ctx_key, self._request_ctx)
except Exception as e:
self.logger.warning(f"Не удалось выполнить write-through контекста запросов (деградация до режима «только память»): {e}")
def remember_request(self, request_id: str, *, request_type: str,
sub_type: str | None = None, group_id: str | None = None,
account: str | None = None) -> None:
"""Сохранение контекста запроса на стороне события (вызывается в точке входа получения адаптером события запроса)"""
now = time.time()
expired = [k for k, c in self._request_ctx.items() if now - c["ts"] > self._REQ_CTX_TTL]
for k in expired:
self._request_ctx.pop(k)
while len(self._request_ctx) >= self._REQ_CTX_MAX:
self._request_ctx.pop(min(self._request_ctx, key=lambda k: self._request_ctx[k]["ts"]))
self._request_ctx[request_id] = {
"request_type": request_type, # "friend" / "group"
"sub_type": sub_type, # подтип группового запроса: "add" / "invite"
"group_id": group_id,
"account": account, # аккаунт прибытия события (self.user_id события / имя аккаунта-заместителя)
"ts": now,
}
self._persist_ctx()
class Request(RequestDSL):
"""Маршрутизация эндпоинтов: явные параметры kwargs > кэш > откат к эндпоинту по умолчанию + WARNING"""
def _route(self, **kwargs) -> dict:
ctx = {k: kwargs[k] for k in ("request_type", "sub_type", "group_id") if kwargs.get(k)}
cached = self._adapter._request_ctx.get(self._request_id, {})
if not ctx.get("request_type"):
ctx.update({k: v for k, v in cached.items()
if k in ("request_type", "sub_type", "group_id") and v})
ctx.setdefault("account", cached.get("account"))
if not ctx.get("request_type"):
self._adapter.logger.warning(f"Тип запроса {self._request_id} неизвестен, выполняется откат к эндпоинту для друзей")
ctx["request_type"] = "friend"
return ctx
def _resolve_or_fail(self, account):
"""
Проверка принадлежности аккаунта при одобрении: при неудаче разрешения — быстрый отказ (34005),
без отката к аккаунту по умолчанию.
Откат к аккаунту по умолчанию направит операцию в ошибочное соединение
(flag не существует в сессии этого аккаунта, платформа сообщит invalid,
что проявляется как «мистический» сбой «оперировать может только первый аккаунт»).
"""
if not account:
return None, None # при отсутствии какой-либо информации об аккаунте сохраняется семантика аккаунта по умолчанию
name, inst = self._adapter._resolve_account(account)
hit = str(account) == str(name) or str(account) == str(getattr(inst, "bot_id", "") or "")
if not hit:
self._adapter.logger.warning(
f"Аккаунт {account} запроса {self._request_id} не удаётся разрешить, откат к аккаунту по умолчанию отклонён")
return None, "34005"
return (name, inst), None
async def _do_accept(self, **kwargs) -> dict:
"""Одобрить запрос; маршрутизацию типа в kwargs можно явно переопределить через request_type / sub_type / group_id"""
return await self._do_action(approve=True, **kwargs)
async def _do_reject(self, **kwargs) -> dict:
"""Отклонить запрос (изоморфно _do_accept: approve=False)"""
return await self._do_action(approve=False, **kwargs)
async def _do_action(self, approve: bool, **kwargs) -> dict:
ctx = self._route(**kwargs)
account = self.request_context.get("account_id") or ctx.get("account")
resolved, fail = self._resolve_or_fail(account)
if fail:
return {
"status": "failed", "retcode": 34005, "data": None,
"message_id": "", "message": f"Не удаётся разрешить аккаунт запроса {account} в экземпляр аккаунта",
}
try:
if ctx["request_type"] == "group":
result = await self._adapter.call_api(
endpoint="/set_group_add_request",
flag=self._request_id,
sub_type=ctx.get("sub_type") or "add",
approve=approve,
account_id=account,
)
else:
result = await self._adapter.call_api(
endpoint="/set_friend_add_request",
flag=self._request_id,
approve=approve,
account_id=account,
)
response = {
"status": "ok" if result.get("code") == 0 else "failed",
"retcode": result.get("code", 0),
"data": None,
"message_id": "",
"message": result.get("message", ""),
}
except Exception as e:
response = {
"status": "failed", "retcode": 34001, "data": None,
"message_id": "", "message": f"Ошибка операции запроса: {e}",
}
if response["status"] == "ok":
self._adapter._request_ctx.pop(self._request_id, None) # очистка после обработки
self._adapter._persist_ctx()
return response
5.3.5 Границы и деградация
Семантика деградации: при недоступности единого хранилища (fast-fail в период охлаждения после ошибки соединения) write-through деградирует до режима «только память» (WARNING для наблюдаемости), события распределяются как обычно; после перезапуска потерянные записи идут по пути «откат при неизвестном типе + WARNING».
Эквивалентный носитель: встроенная ORM (таблица с первичным ключом request_id, см. Слой моделей данных) семантически эквивалентна, адаптер может выбрать её по необходимости; без дополнительных файлов или новых зависимостей.
Границы мультиэкземплярности: данная спецификация не охватывает координацию мультипроцессных экземпляров — ErisPulse использует модель «один процесс, много ботов» (мультиаккаунтность в одном процессе, запросы и их принадлежащий аккаунт естественно находятся на одной стороне), единое хранилище удовлетворяет семантике перезапуска; совместное использование между экземплярами (распределение аккаунтов по процессам) — при необходимости отдельный проект.
5.4 Платформа не поддерживает операции запросов
Если платформа сама не поддерживает операции запросов в друзья/приглашений в группы (например, некоторые платформы автоматически обрабатывают запросы), адаптер может:
- Не переопределять внутренний класс
Request: использовать реализацию базового класса по умолчанию, при вызовеaccept()/reject()возвращаетсяretcode=10002 - Пропускать
request_idпри преобразовании: не генерироватьrequest_id, чтобыevent.approve()выбрасывалValueError - Записывать в лог: в
_do_accept/_do_rejectзаписывать предупреждение и возвращать соответствующий код ошибки
5.5 Итог: Send и Request работают параллельно
У адаптера есть два параллельных внутренних класса DSL, каждый выполняет свою роль:
BaseAdapter
├── Send(SendDSL) ← отправка сообщений
│ ├── Raw_ob12() ← обязательна к реализации
│ ├── Text() ← рекомендуется к реализации
│ └── Image() ← реализуется по необходимости
│
└── Request(RequestDSL) ← операции запросов
├── accept() ← публичная точка входа (шлюз scope + обёртка задачи, не переопределять)
├── reject() ← публичная точка входа (аналогично)
├── _do_accept() ← переопределяется по необходимости
└── _do_reject() ← переопределяется по необходимости
5.6 Замечания по __init__ адаптера
При переопределении __init__ внутреннего класса Request необходимо пробрасывать параметры и вызывать super().__init__(), подробнее см. Введение в разработку адаптеров — замечания по __init__ (для Request аналогично, параметры: adapter, request_id, account_id).
6. Чек-лист реализации адаптера
Базовые требования
- Если переопределён
__init__, вызванsuper().__init__()(гарантирует инициализацию фабрик Send / Request)
Преобразование событий запросов
- Событие запроса содержит поле
request_id(настоятельно рекомендуется) -
detail_typeкорректно отображается в"friend"или"group" - Исходные данные платформы сохраняются в поле
{platform}_raw - Правила генерации
request_idзадокументированы
Операции с запросами
- Внутренний класс
Requestреализован (если платформа поддерживает операции с запросами) -
_do_accept()/_do_reject()переопределены (не переопределяйте публичные методыaccept()/reject()— это обходит шлюз авторизации scope) - Операции возвращают стандартный формат ответа API
- Неподдерживаемые операции возвращают
retcode=10002 - Сетевые ошибки возвращают
retcode=33xxx(в соответствии со стандартом ответов API)
Сохранение контекста типа запроса (платформы с гетерогенными эндпоинтами, см. §5.3)
- На входе событий запросов сохранён контекст
request_id → {тип запроса, sub_type, group_id, аккаунт} - Поля записей соответствуют единой таблице полей §5.3.3 (включая метку времени
ts;request_idстрого соответствует один к одному, запись удаляется после обработки) - Порядок маршрутизации эндпоинтов
accept/reject: явные kwargs > кэш > запасной эндпоинт по умолчанию + WARNING - Параметры переопределения типа используют зарезервированные имена
request_type/sub_type/group_id(без приватных имён вроде_request_type) - Кэш имеет TTL и ограничение по ёмкости; после успешной отправки операции соответствующая запись удаляется
- Мультиаккаунт: аккаунт операции считывается через
self.request_context.get("account_id")(Using()> резервный вариант на основе цепочки событий); сохранённый аккаунт используется как запасной при отсутствии цепочки событий - При ошибке разрешения аккаунта одобрения — быстрый отказ (34005), без отката к аккаунту по умолчанию
- По умолчанию — единое хранилище одноключевых снимков: загрузка при запуске, сквозная запись при поступлении/обработке событий, при недоступности хранилища — деградация до работы только в памяти
7. Расширение кодов ошибок
Рекомендуемые коды ошибок для уровня реализации адаптера, относящиеся к операциям с запросами (в соответствии со стандартом ответов API §3.2,
настраиваемые младшие три цифры в сегменте ошибок платформы 34xxx):
| Код ошибки | Название ошибки | Описание |
|---|---|---|
| 34001 | Request Not Found | Запрос не существует или срок его действия истёк |
| 34002 | Request Already Handled | Запрос уже был обработан |
| 34003 | Request Not Supported | Платформа не поддерживает операции с запросами данного типа |
| 34004 | Permission Denied | У бота нет прав на обработку данного запроса (возвращается платформой) |
| 34005 | Request Account Unresolved | Не удаётся сопоставить аккаунт, к которому относится запрос, с экземпляром аккаунта (fail-fast, без отката к аккаунту по умолчанию) |
Граница с кодами фреймворка: указанные выше
340xx— это сбои обработки запросов, возвращаемые платформой/адаптером; когда фреймворк ErisPulse отключает request-действие (action) некоторого модуля черезscope.actions, он до вызова адаптера сразу возвращает34601(Action Denied, см. стандарт ответов API §5.3); они не заменяют друг друга: сначала запрос проходит через шлюз фреймворка34601, а уже затем попадает на уровень ошибок платформы340xx.
8. Связанные документы
Документы для сопоставления при реализации операций запроса:
- Стандарт преобразования событий - Полный стандарт преобразования событий (включая требования к полю
request_id) - Стандарт ответов API - Стандарт формата ответов API адаптера (возвращаемые значения и коды ошибок операций)
- Хранилище бэкендов - Если нужно сохранять контекст запроса между перезапусками, используется единое хранилище KV
Другие DSL в одном адаптере:
- Спецификация методов отправки - Стандарт именования и параметров методов Send
- Стандарт типов сессий - Определения и сопоставления типов сессий