Справочник по API NextPDF Connect
Эта страница — справочник по символам сервера NextPDF Connect (nextpdf/server). Здесь перечислены все инструменты с зарегистрированными именами и классами реализации, а также описана gRPC-служба NextPDFConnect, включая методы RPC и сообщения запросов и ответов. Страница также определяет общий для всех транспортов контракт аутентификации, ошибок и ограничений частоты запросов.
Сервер предоставляет единый реестр инструментов через три транспорта: Model Context Protocol (MCP) поверх стандартного ввода-вывода, REST API и gRPC. Подробности протокола для каждого транспорта вынесены на отдельные страницы: см. Транспорт MCP, Транспорт REST и Транспорт gRPC. Эта страница перечисляет символы, передаваемые этими транспортами.
Имена инструментов, классы и уровни риска берутся из реализаций инструментов в src/Tools/. Количество инструментов, доступных в конкретном развёртывании, определяется во время выполнения; см. Каталог инструментов. На странице Запуск и обнаружение описано, как определяются уровни.
Доступность транспортов
Заголовок раздела «Доступность транспортов»Инструмент доступен через каждый транспорт, запущенный в развёртывании. Транспорты работают как независимые процессы; запуск одного транспорта не запускает остальные.
| Транспорт | Точка входа | Формат протокола | Аутентификация |
|---|---|---|---|
| MCP | bin/nextpdf-mcp | JSON-RPC 2.0 поверх stdio | Граница процесса операционной системы (без ключа API) |
| REST | bin/nextpdf-server | HTTP, OpenAPI 3.1 | Ключ API типа Bearer в заголовке запроса Authorization |
| gRPC | bin/nextpdf-grpc | Protocol Buffers, пакет nextpdf.connect.v1 | Токен типа Bearer в поле метаданных вызова authorization |
Через MCP вы вызываете инструмент с помощью tools/call и зарегистрированного имени. Через REST и gRPC те же возможности движка доступны через интерфейсы отрисовки, операций и возможностей; см. таблицу маршрутов на странице Транспорт REST и таблицу RPC на странице Транспорт gRPC.
Аутентификация и уровень риска
Заголовок раздела «Аутентификация и уровень риска»Аутентификация по ключу API
Заголовок раздела «Аутентификация по ключу API»Транспорты REST и gRPC требуют ключ API типа Bearer в каждом запросе, кроме неаутентифицированных проверок работоспособности. Ключ имеет вид npk_live_{kid}_{secret}: kid — восьмисимвольный идентификатор, по которому находится запись, а секретная часть содержит энтропию. Сервер хранит только дайджест ключа SHA-256 и сравнивает предъявленный токен за константное время, поэтому недействительный ключ ничего не раскрывает через время ответа. REST считывает токен из заголовка Authorization: Bearer …; gRPC — из метаданных вызова authorization. MCP-транспорт поверх stdio не использует ключ API, поскольку это локальный подпроцесс, которому доверяет запустивший его клиент. Полная модель аутентификации описана на странице Безопасность и эксплуатация.
Четыре уровня риска
Заголовок раздела «Четыре уровня риска»Каждый инструмент объявляет один из четырёх упорядоченных уровней риска, определённых перечислением RiskLevel в src/Config/RiskLevel.php.
| Уровень | Вариант перечисления | Значение | Эффект |
|---|---|---|---|
| Безопасный (Safe) | RiskLevel::Safe | 0 | Только чтение, без побочных эффектов. Выполняется автоматически. |
| Осторожность (Caution) | RiskLevel::Caution | 1 | Создаёт или изменяет состояние в памяти. Выполняется автоматически с записью в журнал аудита. |
| Проверка (Review) | RiskLevel::Review | 2 | Создаёт результат, который можно использовать во вред. Выполняется автоматически с записью в журнал аудита. |
| Требуется подтверждение (ApprovalRequired) | RiskLevel::ApprovalRequired | 3 | Разрушительный, юридически значимый или критичный для конфиденциальности. Требует подтверждения человеком. |
Итоговый риск инструмента определяется ровно двумя источниками: собственным объявлением инструмента riskLevel() и необязательным переопределением в конфигурации оператора. Такое переопределение может только повышать риск и никогда не понижает риск инструмента уровня ApprovalRequired. См. Уровни риска HITL и Конфигурация.
Как проходят токены подтверждения
Заголовок раздела «Как проходят токены подтверждения»Когда вы вызываете инструмент ApprovalRequired без действительного токена, ConfirmationGate (src/Mcp/ConfirmationGate.php) возвращает одноразовый запрос подтверждения с токеном вместо запуска инструмента. Агент передаёт запрос человеку, а затем повторно вызывает тот же инструмент, указывая выданный токен в аргументе _confirmation_token. Токен связывает имя инструмента, случайный одноразовый код и срок жизни (TTL) в 300 секунд. Он не связывает аргументы и не является учётными данными для аутентификации. В REST запрос по-прежнему аутентифицируется ключом API типа Bearer, а тот же шлюз срабатывает в общем исполнителе инструментов перед защищённой операцией. В gRPC тот же шлюз срабатывает перед отправкой операции. Механизм запроса и токена одинаков для всех транспортов.
Инструменты и конечные точки
Заголовок раздела «Инструменты и конечные точки»В таблице каждый инструмент описан по зарегистрированному имени (столбец “Символ”) и классу реализации. Инструменты сгруппированы по уровню и категории. Все классы абстрактного синтаксического дерева (AST) и мутаций находятся в src/Tools/Ast и src/Tools/Ast/Mutation; классы извлечения — в src/Tools/Extraction; остальные классы — в src/Tools/Core.
Базовые инструменты для документов
Заголовок раздела «Базовые инструменты для документов»| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает исключение или завершается с ошибкой | Примечания |
|---|---|---|---|---|---|
create_pdf | page_size (по умолчанию A4), orientation (portrait/landscape), title, author; обязательных нет. | Создаёт документ в памяти с одной страницей; задаёт метаданные, если они указаны. | JSON с document_id, page_count, page_size, orientation. | При сбое возвращает результат с ошибкой и сообщением движка. | Класс CreatePdfTool. Риск RiskLevel::Caution. Уровень core. Возвращённый document_id используется в каждой последующей операции. |
add_page | document_id (обязательный), необязательные размер страницы и ориентация. | Добавляет страницу в конец документа. | JSON с новым числом страниц. | Результат с ошибкой, если document_id неизвестен. | Класс AddPageTool. Риск RiskLevel::Caution. Уровень core. |
add_text | document_id (обязательный), text (обязательный), необязательные положение и стиль. | Добавляет текст в документ. | Сводка состояния документа в формате JSON. | Результат с ошибкой, если document_id неизвестен. | Класс AddTextTool. Риск RiskLevel::Caution. Уровень core. |
add_image | document_id (обязательный), source (обязательный: путь к файлу или base64), необязательное размещение. | Добавляет изображение из файла по пути или из данных base64. | Сводка состояния документа в формате JSON. | Результат с ошибкой при нечитаемом источнике или неизвестном document_id. | Класс AddImageTool. Риск RiskLevel::Caution. Уровень core. |
add_table | document_id (обязательный), html (обязательный). | Отрисовывает HTML-таблицу в документе. | Сводка состояния документа в формате JSON. | Результат с ошибкой при недопустимой разметке или неизвестном document_id. | Класс AddTableTool. Риск RiskLevel::Caution. Уровень core. |
set_font | document_id (обязательный), family (обязательный), необязательные размер и стиль. | Задаёт шрифт для последующих операций с текстом. | Подтверждение активного шрифта в формате JSON. | Результат с ошибкой при неизвестном шрифте или document_id. | Класс SetFontTool. Риск RiskLevel::Caution. Уровень core. |
output_pdf | document_id (обязательный), file_path (необязательный), destroy (по умолчанию true). | Финализирует документ; записывает в file_path или возвращает base64, если путь не указан; по умолчанию уничтожает документ. | JSON с file_path и file_size либо с base64 и file_size. | Результат с ошибкой, если document_id неизвестен; ошибка ограничения пути при записи за пределы базового каталога. | Класс OutputPdfTool. Риск RiskLevel::ApprovalRequired. Уровень core. Запись файла проходит через шлюз подтверждения; режим base64 — нет. |
preview_layout | document_id (обязательный). | Возвращает сводку по макету без отрисовки итогового PDF. | Сводка по макету в формате JSON. | Результат с ошибкой, если document_id неизвестен. | Класс PreviewLayoutTool. Риск RiskLevel::Safe. Уровень core. |
parse_pdf | document_id (обязательный). | Анализирует структурные метаданные: число страниц, шрифты, изображения, шифрование и словарь Info Dictionary. | Структурные метаданные в формате JSON. | Результат с ошибкой при некорректном документе. | Класс ParsePdfTool. Риск RiskLevel::Safe. Уровень core. Регистрируется, только когда NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED равно true или 1. |
Базовые диагностические инструменты
Заголовок раздела «Базовые диагностические инструменты»| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает исключение или завершается с ошибкой | Примечания |
|---|---|---|---|---|---|
diagnostic.doctor | нет. | Выполняет проверку работоспособности и возвращает структурированную диагностику среды. | Отчёт о среде в формате JSON. | Результат с ошибкой при сбое внутренней проверки. | Класс DiagnosticDoctorTool. Риск RiskLevel::Safe. Уровень core. Не требует ни документа, ни подтверждения. |
diagnostic.capabilities | нет. | Перечисляет возможности с информацией об уровне и статусе. | Список возможностей в формате JSON. | Результат с ошибкой при внутреннем сбое. | Класс DiagnosticCapabilitiesTool. Риск RiskLevel::Safe. Уровень core. |
diagnostic.inspect | document_id (обязательный). | Анализирует PDF и возвращает структурные метаданные. | Структурные метаданные в формате JSON. | Результат с ошибкой, если document_id неизвестен. | Класс DiagnosticInspectTool. Риск RiskLevel::Safe. Уровень core. |
diagnostic.verify | document_id (обязательный), необязательный профиль PDF/A или PDF/UA. | Проверяет структурную целостность; при необходимости проверяет PDF/A или PDF/UA, запуская подпроцесс VeraPDF. | Отчёт о проверке в формате JSON. | Результат с ошибкой при сбое подпроцесса, тайм-ауте или превышении размера ввода. | Класс DiagnosticVerifyTool. Риск RiskLevel::Caution. Уровень core. Размер ввода ограничен 50 мебибайтами (МиБ). |
Базовый инструмент для штрихкодов
Заголовок раздела «Базовый инструмент для штрихкодов»| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает исключение или завершается с ошибкой | Примечания |
|---|---|---|---|---|---|
generate_barcode | payload (обязательный), format (например, QR Code, DataMatrix). | Создаёт матрицу модулей двумерного штрихкода для полезной нагрузки. | Матрица модулей в формате JSON. | Результат с ошибкой при неподдерживаемом format или недопустимой полезной нагрузке. | Класс BarcodeTool. Риск RiskLevel::Caution. Уровень core. BarcodeTool регистрируется, только когда базовый реестр кодировщиков barcode присутствует в установленном nextpdf/core; зарегистрированное имя инструмента — generate_barcode. |
Инструменты конфиденциальности Enterprise
Заголовок раздела «Инструменты конфиденциальности Enterprise»Эти инструменты служат оболочкой для классов конфиденциальности Enterprise и регистрируются на уровне Enterprise, только когда эти классы доступны для автозагрузки. Они работают с содержимым в виде обычного текста.
| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает исключение или завершается с ошибкой | Примечания |
|---|---|---|---|---|---|
redact_pdf | content (обязательный), необязательные параметры обнаружения. | Необратимо скрывает персональные данные (PII) в содержимом в виде обычного текста с помощью движка редактирования Enterprise. | JSON с отредактированным содержимым и хешем SHA-256. | Результат с ошибкой, если классы Enterprise отсутствуют или обнаружение завершается неудачей. | Класс RedactPdfTool. Риск RiskLevel::Review. Уровень enterprise. |
deidentify_pdf | content (обязательный), strategy (redact или suppress). | Применяет систематическую стратегию деидентификации к содержимому в виде обычного текста с помощью деидентификатора Enterprise. | JSON с деидентифицированным содержимым. | Результат с ошибкой, если классы Enterprise отсутствуют. | Класс DeIdentifyPdfTool. Риск RiskLevel::Review. Уровень enterprise. |
zone_redact_pdf | content (обязательный), zones (страница и список нормализованных прямоугольников). | Применяет зональное редактирование по координатам с помощью движка редактирования Enterprise. | JSON с отредактированным содержимым. | Результат с ошибкой при недопустимой зоне или отсутствии классов Enterprise. | Класс ZoneRedactionTool. Риск RiskLevel::Review. Уровень enterprise. |
Инструменты чтения абстрактного синтаксического дерева (AST)
Заголовок раздела «Инструменты чтения абстрактного синтаксического дерева (AST)»Эти инструменты поставляются с сервером, регистрируются на уровне Pro и управляются параметром NEXTPDF_AST_TOOLS_ENABLED (включён по умолчанию). Они доступны только для чтения.
| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает исключение или завершается с ошибкой | Примечания |
|---|---|---|---|---|---|
get_document_ast | pdf_data (обязательный). | Строит семантическое AST: полное дерево узлов с якорями ссылок для каждого структурного элемента. | Дерево узлов в формате JSON плюс ETag для управления параллелизмом. | Результат с ошибкой при некорректном документе. | Класс GetDocumentAstTool. Риск RiskLevel::Safe. Уровень pro. |
get_ast_node | pdf_data (обязательный), node_id (обязательный). | Извлекает один узел AST и всех его потомков. | Узел с потомками в формате JSON. | Результат с ошибкой при неизвестном node_id. | Класс GetAstNodeTool. Риск RiskLevel::Safe. Уровень pro. |
get_ast_diff | original_pdf_data (обязательный), modified_pdf_data (обязательный). | Структурно сравнивает два документа, сопоставляя их семантические AST. | Добавленные, удалённые и изменённые узлы в формате JSON. | Результат с ошибкой при некорректном входном документе. | Класс GetAstDiffTool. Риск RiskLevel::Safe. Уровень pro. |
search_ast_nodes | pdf_data (обязательный), необязательные фильтры по типу, индексу страницы и тексту. | Ищет узлы AST по типу, индексу страницы или текстовому содержимому. | Плоский список совпавших узлов с потомками верхнего уровня в формате JSON. | Результат с ошибкой при некорректном документе. | Класс SearchAstNodesTool. Риск RiskLevel::Safe. Уровень pro. |
extract_cited_text | pdf_data (обязательный), необязательный headings_only. | Извлекает блоки текста с якорями ссылок (страница, ограничивающий прямоугольник, достоверность). | Блоки текста со ссылками в формате JSON. | Результат с ошибкой при некорректном документе. | Класс ExtractCitedTextTool. Риск RiskLevel::Safe. Уровень pro. Категория ast. |
extract_cited_tables | pdf_data (обязательный). | Извлекает блоки таблиц с якорями ссылок; возвращает построчную матрицу ячеек для каждого узла Table. | Матрицы таблиц с якорями в формате JSON. | Результат с ошибкой при некорректном документе. | Класс ExtractCitedTablesTool. Риск RiskLevel::Safe. Уровень pro. Категория extraction. |
Инструменты мутации AST
Заголовок раздела «Инструменты мутации AST»Эти инструменты поставляются с сервером, регистрируются на уровне Pro и управляются параметром NEXTPDF_MUTATION_TOOLS_ENABLED (включён по умолчанию). Все четыре имеют уровень ApprovalRequired и используют оптимистическое управление параллелизмом (OCC) через ETag.
| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает исключение или завершается с ошибкой | Примечания |
|---|---|---|---|---|---|
apply_ast_mutations | pdf_data, etag, idempotency_key, mutations (все обязательные). | Применяет пакет мутаций атомарно; для повторного idempotency_key воспроизводит кешированный результат. | JSON с изменённым PDF и новым ETag. | Конфликт OCC при устаревшем ETag; ошибка проверки при некорректной мутации. | Класс ApplyAstMutationsTool. Риск RiskLevel::ApprovalRequired. Уровень pro. |
delete_ast_node | pdf_data, node_id, etag (все обязательные). | Удаляет узел в режиме наложения (исходное содержимое перекрывается, а не удаляется физически). | JSON с изменённым PDF и новым ETag. | Конфликт OCC при устаревшем ETag; ошибка при неизвестном node_id. | Класс DeleteAstNodeTool. Риск RiskLevel::ApprovalRequired. Уровень pro. |
insert_ast_node | pdf_data, parent_node_id, position, etag, node (все обязательные). | Вставляет новый узел как потомок родителя в указанной позиции. | JSON с изменённым PDF и новым ETag. | Конфликт OCC при устаревшем ETag; ошибка проверки при некорректном узле. | Класс InsertAstNodeTool. Риск RiskLevel::ApprovalRequired. Уровень pro. |
update_ast_node | pdf_data, node_id, etag, updates (все обязательные). | Обновляет текстовое содержимое узла. | JSON с изменённым PDF и новым ETag. | Конфликт OCC при устаревшем ETag; ошибка при неизвестном node_id. | Класс UpdateAstNodeTool. Риск RiskLevel::ApprovalRequired. Уровень pro. |
Схема запросов и ответов
Заголовок раздела «Схема запросов и ответов»Транспорт gRPC определяет типизированную схему сервера в пакете Protocol Buffers nextpdf.connect.v1, в proto/nextpdf/connect/v1/*.proto. Служба и её сообщения — канонические символы схемы.
Служба NextPDFConnect
Заголовок раздела «Служба NextPDFConnect»Служба NextPDFConnect предоставляет унарные и серверно-потоковые RPC. Символы схемы — это имена методов RPC и связанные с ними сообщения запросов и ответов.
| RPC | Сообщение запроса | Сообщение ответа | Форма |
|---|---|---|---|
Render | RenderRequest | RenderResponse | Унарный. Синхронная отрисовка без сохранения состояния. |
RenderStream | RenderRequest | RenderChunk (поток) | Серверный поток. Отрисовка доставляется упорядоченными фрагментами. |
SubmitJob | SubmitJobRequest | JobResponse | Унарный. Отправляет асинхронное задание отрисовки. |
GetJobStatus | GetJobStatusRequest | JobResponse | Унарный. Запрашивает статус задания. |
GetJobResult | GetJobResultRequest | RenderResponse | Унарный. Скачивает завершённый результат. |
GetJobResultStream | GetJobResultRequest | RenderChunk (поток) | Серверный поток. Скачивает завершённый результат фрагментами. |
CancelJob | CancelJobRequest | JobResponse | Унарный. Отменяет или удаляет задание. |
CreateSession | CreateSessionRequest | SessionResponse | Унарный. Создаёт сеанс построения документа. |
GetSession | GetSessionRequest | SessionResponse | Унарный. Возвращает метаданные сеанса. |
DestroySession | DestroySessionRequest | DestroySessionResponse | Унарный. Уничтожает сеанс и его документ. |
SessionOperation | SessionOperationRequest | SessionResponse | Унарный. Выполняет операцию над документом сеанса. |
SessionRender | SessionRenderRequest | RenderResponse | Унарный. Отрисовывает документ сеанса в PDF. |
SessionRenderStream | SessionRenderRequest | RenderChunk (поток) | Серверный поток. Отрисовывает документ сеанса фрагментами. |
ExecuteCapability | CapabilityRequest | CapabilityResponse | Унарный. Выполняет операцию возможности, ограниченную уровнем. |
GetCapabilities | GetCapabilitiesRequest | GetCapabilitiesResponse | Унарный. Перечисляет возможности для аутентифицированного клиента. |
HealthCheck | HealthCheckRequest | HealthCheckResponse | Унарный. Проверка жизнеспособности. |
ReadinessCheck | ReadinessCheckRequest | ReadinessCheckResponse | Унарный. Проверка готовности. |
Символы сообщений
Заголовок раздела «Символы сообщений»Сообщения запросов и ответов — структурные символы схемы. Сообщения отрисовки — RenderRequest, RenderResponse и потоковое RenderChunk — содержат размер страницы, ориентацию, упорядоченные операции и итоговые байты PDF. Сообщения заданий — SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest и JobResponse — моделируют асинхронный жизненный цикл задания, при этом метаданные задания хранятся в сообщении JobData. Сообщения сеансов — CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest и SessionRenderRequest — моделируют сеансовый жизненный цикл с сохранением состояния, при этом метаданные сеанса хранятся в сообщении SessionData. Сообщения возможностей — CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest и GetCapabilitiesResponse — содержат диспетчеризацию операций, ограниченных уровнем, и данные интроспекции. Системные сообщения — HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest и ReadinessCheckResponse — содержат статус жизнеспособности и готовности.
Поставляемые файлы .proto — эталонный контракт протокола; см. справочник по транспорту gRPC на странице Транспорт gRPC.
Модель ошибок
Заголовок раздела «Модель ошибок»Сервер сообщает о сбоях через встроенный механизм ошибок каждого транспорта. Каждый транспорт сохраняет одно и то же логическое условие; различается только его кодирование.
Ошибки MCP — это объекты ошибок JSON-RPC 2.0. Неизвестный метод возвращает “метод не найден” (-32601); сообщение, не являющееся корректным JSON-RPC, возвращает “недопустимый запрос” (-32600); ввод, который не удаётся разобрать, возвращает “ошибку разбора” (-32700). Инструмент, завершившийся сбоем, возвращает успешный ответ JSON-RPC, в содержимом которого отмечена ошибка, а не ошибку уровня транспорта, чтобы агент мог прочитать сообщение. Запрос подтверждения для инструмента ApprovalRequired также является успешным ответом, а не ошибкой.
REST использует коды статуса HTTP с семантикой, определённой в RFC 9110. 200 содержит результат; 400 возвращается, когда поле запроса не проходит проверку формата; 401 возвращается, когда не предъявлен действительный ключ API, и содержит заголовок ответа WWW-Authenticate: Bearer; 403 возвращается, когда уровень действительного ключа не имеет права на операцию; 404 возвращается, когда маршрут, ограниченный уровнем, не зарегистрирован из-за отсутствия его пакета. Машиночитаемые тела ошибок — это документы Problem Details согласно RFC 9457, передаваемые с типом носителя application/problem+json и стабильным унифицированным идентификатором ресурса (URI) type для каждого условия. Ошибки проверки на уровне полей перечислены в теле. Для защиты от обхода путей document_id, не соответствующий шаблону doc_[a-f0-9]{24}, отклоняется с 400 до запуска инструмента. Транспорт REST описывает конвейер промежуточного ПО REST и таблицу маршрутов.
gRPC использует стандартные коды статуса gRPC. Отсутствующий, некорректный, неизвестный, отключённый или истёкший токен завершает вызов с UNAUTHENTICATED, а не со статусом HTTP. Подробные сведения об ошибке повторяют форму Problem Details из REST и передаются в деталях статуса gRPC, поэтому URI type ошибки согласован для всех транспортов.
См. также RFC 9110 (HTTP Semantics) для семантики кодов статуса и RFC 9457 (Problem Details for HTTP APIs) для формата тела ошибки.
- RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
- RFC 9457: https://www.rfc-editor.org/rfc/rfc9457
Ограничения частоты запросов и квоты
Заголовок раздела «Ограничения частоты запросов и квоты»Транспорт REST применяет ограничение частоты запросов по IP-адресу и по клиенту в своём конвейере промежуточного ПО, а также ограничения на размер тела, полезную нагрузку уровня и тайм-аут запроса. Эти предельные значения — параметры конфигурации, а не жёстко заданные константы:
- Предельные значения полезной нагрузки по уровням (
corePayloadLimit,proPayloadLimit,enterprisePayloadLimit) и соответствующие тайм-ауты применяются в REST согласно уровню аутентифицированного ключа. См. Конфигурация. - Хранилище документов в памяти ограничено параметрами
max_documents(по умолчанию 50) иdocument_ttl(по умолчанию 1800 секунд). - Состояние ограничения частоты запросов и идемпотентности хранится отдельно для каждого рабочего процесса, если
NEXTPDF_REDIS_HOSTне настроен на общее хранилище. См. развёртывание.
Когда хранилища ограничения частоты запросов и идемпотентности используются совместно, повторные идентичные отправки асинхронных заданий дедуплицируются по idempotency_key. Транспорт MCP обрабатывает по одному запросу за раз через каналы и дедуплицирует повторный id запроса из буфера на 64 записи вместо применения сетевых ограничений частоты запросов.
Примечания для разработки
Заголовок раздела «Примечания для разработки»- Считывайте имена инструментов, классы и уровни риска из исходного кода в
src/Tools/; не предполагайте фиксированное итоговое число. Запрашивайте актуальное число у работающего сервера, как показано на странице Каталог инструментов. - Регенерируйте клиентские заглушки gRPC из поставляемых файлов
proto/nextpdf/connect/v1/*.proto; пакет и пространство имён —nextpdf.connect.v1. Не редактируйте сгенерированные классы сообщений вручную. - Инструмент
ApprovalRequiredпри первом вызове отвечает запросом подтверждения. Реализуйте сценарий повторной попытки — передайте запрос, затем повторно вызовите с_confirmation_token— прежде чем выпускать интеграцию, использующуюoutput_pdfили любой инструмент мутации. - Маршрут или возможность, ограниченные уровнем и не установленные, — это не сбой аутентификации: REST возвращает
404для отсутствующего маршрута, а gRPCExecuteCapabilityсообщает операцию как недоступную. Считайте отсутствие уровня Pro или Enterprise ожидаемым поведением, а не ошибкой. - Не храните ключи API в системе контроля версий; монтируйте их из файла-секрета и предпочитайте файловое хранилище ключей с горячей перезагрузкой, чтобы ротация не требовала перезапуска. См. Безопасность и эксплуатация.
См. также
Заголовок раздела «См. также»- Руководство разработчика — архитектура, жизненный цикл, точки расширения и контрольный список тестирования
- Каталог инструментов — проверенный базовый набор инструментов и количество во время выполнения
- Уровни риска HITL — модель риска и запрос подтверждения
- Транспорт MCP · Транспорт REST · Транспорт gRPC — детали протокола по каждому транспорту
- Безопасность и эксплуатация — аутентификация, безопасность транспорта и модель угроз