Спецификация JSON-RPC 2.0

27.10.21

Интеграция - Файловый обмен (TXT, XML, DBF), FTP

Перевод спецификации с официального сайта https://www.jsonrpc.org/specification (2013-01-04), автор JSON-RPC Working Group.

1 Обзор

JSON-RPC - это упрощенный протокол удаленного вызова процедур (RPC) без сохранения состояния. В первую очередь эта спецификация определяет несколько структур данных и правила их обработки. Он не зависит от транспорта в том смысле, что эти концепции могут использоваться в рамках одного и того же процесса, через сокеты, по протоколу http или во многих различных средах передачи сообщений. Он использует JSON (RFC 4627) в качестве формата данных.

Он разработан, чтобы быть простым!

 

2 Соглашения

Ключевые слова "ДОЛЖЕН", "НЕ ДОЛЖЕН", "ТРЕБУЕТСЯ", "РЕКОМЕНДУЕТСЯ", "МОЖЕТ" и "НЕОБЯЗАТЕЛЬНО" в этом документе должны интерпретироваться как описано в RFC 2119. ("MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL").

Поскольку JSON-RPC использует JSON, он имеет систему того же типа (см. http://www.json.org или RFC 4627). JSON может представлять четыре примитивных типа (Строки, числа, логические значения и Null) и два структурированных типа (Объекты и Массивы). Термин "Примитивный" в этой спецификации ссылается на любой из этих четырех примитивных типов JSON. Термин "Структурированный" относится к любому из структурированных типов JSON. Всякий раз, когда этот документ ссылается на какой-либо тип JSON, первая буква всегда пишется с заглавной буквы: Объект, Массив, Строка, Число, Логическое значение, Null. Истина и Ложь также пишутся с заглавной буквы.

Все имена реквизитов, которыми обмениваются Клиент и Сервер и которые рассматриваются на предмет соответствия любого рода, должны учитываться с учетом регистра. Термины функция, метод и процедура можно считать взаимозаменяемыми.

Клиент определяется как источник объектов Запроса и обработчик объектов Ответа.
Сервер определяется как источник объектов Ответа и обработчик объектов Запроса.

Одна реализация этой спецификации может свободно выполнять обе эти роли, даже в одно и то же время, для разных клиентов или одного и того же клиента. Эта спецификация не затрагивает этот уровень сложности.

 

3 Совместимость

Объекты запроса JSON-RPC 2.0 и объекты ответа могут не работать с существующими клиентами или серверами JSON-RPC 1.0. Тем не менее, легко различить две версии, так как в версии 2.0 всегда есть элемент с именем "jsonrpc" со строковым значением "2.0", тогда как в версии 1.0 его нет. В большинстве реализаций 2.0 следует рассмотреть возможность обработки объектов 1.0, даже если это не одноранговые и классовые аспекты 1.0.

 

4 Объект запроса

Вызов RPD представлен отправкой объекта запроса на Сервер. Объект запроса содержит следующие элементы:

  • jsonrpc - Строка, указывающая версию протокола JSON-RPC. ДОЛЖНО быть точно "2.0".
  • method - Строка, содержащая имя вызываемого метода. Имена методов, начинающиеся со слова rpc, за которым следует символ точки (U+002E или ASCII 46), зарезервированы для внутренних методов и расширений rpc и НЕ ДОЛЖНЫ использоваться ни для чего другого.
  • params - Структурированное значение, содержащее значения параметров, которые будут использоваться во время вызова метода. Этот элемент МОЖЕТ быть опущен.
  • id - Идентификатор, установленный Клиентом, который ДОЛЖЕН содержать строку, число или NULL значение, если оно включено. Если он не включен, предполагается, что это уведомление. Значение обычно не должно быть нулевым [1], а числа НЕ ДОЛЖНЫ содержать дробных частей [2]

[1] Использование Null в качестве значения для элемента идентификатора в объекте запроса не рекомендуется, поскольку в этой спецификации используется значение Null для ответов с неизвестным идентификатором. Кроме того, поскольку JSONRPC 1.0 использует значение идентификатора Null для уведомлений, это может привести к путанице в обработке.

[2] Дробные части могут быть проблематичными, так как многие десятичные дроби не могут быть представлены точно как двоичные дроби.

 

4.1 Уведомление

Уведомление - это объект запроса без элемента "id". Объект запроса, являющийся Уведомлением, означает отсутствие интереса Клиента к соответствующему объекту Ответа, и поэтому клиенту не требуется возвращать объект Ответа. Сервер НЕ ДОЛЖЕН отвечать на Уведомления, в том числе на те, которые находятся в пакетном запросе.

Уведомления не могут быть подтверждены по определению, так как у них нет объекта ответа, который должен быть возвращен. Таким образом, Клиент не будет знать о каких-либо ошибках (например, "Недопустимые параметры", "Внутренняя ошибка").

 

4.2 Структуры параметров

При наличии параметры для вызова RPC ДОЛЖНЫ быть предоставлены в виде структурированного значения. Либо по позиции через массив, либо по имени через объект.

  • по позиции: параметры ДОЛЖНЫ быть массивом, содержащим значения в ожидаемом сервером порядке.
  • по имени: параметры ДОЛЖНЫ быть объектом с именами членов, которые соответствуют ожидаемым именам параметров Сервера. Отсутствие ожидаемых имен МОЖЕТ привести к возникновению ошибки. Имена ДОЛЖНЫ точно соответствовать, включая регистр, ожидаемым параметрам метода

 

5 Объект ответа

Когда выполняется вызов rpc, Сервер ДОЛЖЕН ответить Ответом, за исключением случаев Уведомлений. Ответ выражается в виде одного объекта JSON со следующими элементами:

  • jsonrpc - Строка, указывающая версию протокола JSON-RPC. ДОЛЖНО быть точно "2.0".
  • result
    • Этот элемент НЕОБХОДИМ при успешном ответе.
    • Этот элемент НЕ ДОЛЖЕН существовать, если произошла ошибка при вызове метода.
    • Значение этого элемента определяется методом, вызываемым на Сервере.
  • error -
    • Этот элемент ТРЕБУЕТСЯ при ошибке.
    • Этот элемент НЕ ДОЛЖЕН существовать, если во время вызова не было ошибки.
    • Значение для этого элемента ДОЛЖНО быть Объектом, как определено в разделе 5.1.
  • id
    • Этот элемент ЯВЛЯЕТСЯ ОБЯЗАТЕЛЬНЫМ.
    • Он ДОЛЖНО совпадать со значением элемента идентификатора в объекте запроса.
    • Если произошла ошибка при определении идентификатора в объекте запроса (например, ошибка синтаксического анализа/Недопустимый запрос), он ДОЛЖЕН быть нулевым.

ДОЛЖЕН быть включен либо элемент "result", либо элемент "error", но оба элемента НЕ ДОЛЖНЫ быть включены.

 

5.1 Объект ошибки

Когда вызов RPC обнаруживает ошибку, объект ответа ДОЛЖЕН содержать элемент ошибки со значением, которое является объектом со следующими элементами:

  • code
    • Число, указывающее тип возникшей ошибки.
    • Это ДОЛЖНО быть целое число.
  • message
    • Строка, содержащая краткое описание ошибки.
    • Сообщение ДОЛЖНО быть ограничено кратким одним предложением.
  • data
    • Примитивное или структурированное значение, содержащее дополнительную информацию об ошибке.
    • Может быть опущено.
    • Значение этого элемента определяется Сервером (например, подробная информация об ошибках, вложенные ошибки и т.д.).

Коды ошибок от -32768 до -32000 включительно зарезервированы для предопределенных ошибок. Любой код в этом диапазоне, но явно не определенный ниже, зарезервирован для использования в будущем. Коды ошибок почти совпадают с кодами, предлагаемыми для XML-RPC по следующему URL-адресу: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

Код Сообщение Значение
-32700 Ошибка синтаксического анализа Неверный JSON был получен сервером.
При анализе текста JSON на сервере произошла ошибка.
-32600 Неверный Запрос Отправленный JSON не является допустимым объектом запроса.
-32601 Метод не найден Метод не существует /недоступен.
-32602 Недопустимые параметры Недопустимый параметр(ы) метода.
-32603 Внутренняя ошибка Внутренняя ошибка JSON-RPC.
-32000 to -32099 Ошибка сервера Зарезервировано для ошибок сервера, определенных реализацией.

 

Оставшаяся часть пространства доступна для ошибок, определенных приложением.

 

6 Пакетная обработка

Чтобы отправить несколько объектов запроса одновременно, Клиент МОЖЕТ отправить Массив, заполненный объектами запроса.

Сервер должен ответить Массивом, содержащим соответствующие объекты ответа, после обработки всех объектов пакетного запроса. Объект ответа ДОЛЖЕН существовать для каждого объекта запроса, за исключением того, что НЕ ДОЛЖНО быть никаких объектов ответа для уведомлений. Сервер МОЖЕТ обрабатывать пакетный вызов rpc как набор параллельных задач, обрабатывая их в любом порядке и с любой шириной параллелизма.

Объекты ответа, возвращаемые из пакетного вызова, МОГУТ быть возвращены в любом порядке в Массиве. Клиент ДОЛЖЕН сопоставлять контексты между набором объектов запроса и результирующим набором объектов ответа на основе элемента "id" внутри каждого объекта.

Если сам пакетный вызов rpc не распознается как допустимый JSON или как массив с хотя бы одним значением, ответ Сервера ДОЛЖЕН быть одним объектом ответа. Если в массиве ответов нет объектов ответа, которые должны быть отправлены клиенту, сервер НЕ ДОЛЖЕН возвращать пустой массив и вообще ничего не должен возвращать.

 

7 Примеры

--> данные, отправленные на Сервер
<-- данные, отправленные Клиенту

вызов rpc с позиционными параметрами:

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

вызов rpc с именованными параметрами:

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}
<-- {"jsonrpc": "2.0", "result": 19, "id": 4}

Уведомление:

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "foobar"}

вызов rpc несуществующего метода:

--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}

вызов rpc с недопустимым JSON:

--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

вызов rpc с недопустимым объектом Запроса:

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

пакет вызовов rpc, недопустимый JSON:

--> [
  {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
  {"jsonrpc": "2.0", "method"
]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

вызов rpc с пустым массивом:

--> []
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

вызов rpc с недопустимым Пакетом (но не пустым):

--> [1]
<-- [
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
]

вызов rpc с недопустимым Пакетом:

--> [1,2,3]
<-- [
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
]

Пакетный вызов rpc:

--> [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
        {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
        {"foo": "boo"},
        {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
        {"jsonrpc": "2.0", "method": "get_data", "id": "9"} 
    ]
<-- [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
        {"jsonrpc": "2.0", "result": 19, "id": "2"},
        {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
        {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "5"},
        {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
    ]

пакет вызовов rpc (все уведомления):

--> [
        {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]}
    ]
<-- //Для всех пакетов уведомлений ничего не возвращается

 

Расширения

Имена методов, начинающиеся с rpc., зарезервированы для системных расширений и НЕ ДОЛЖНЫ использоваться ни для чего другого. Каждое системное расширение определено в соответствующей спецификации. Все системные расширения являются НЕОБЯЗАТЕЛЬНЫМИ.

 

---

Авторское право (C) 2007-2010 Рабочей группой JSON-RPC

Этот документ и его переводы могут быть использованы для реализации JSON-RPC, он может быть скопирован и предоставлен другим лицам, а производные работы, которые комментируют или иным образом объясняют его или помогают в его реализации, могут быть подготовлены, скопированы, опубликованы и распространены, полностью или частично, без каких-либо ограничений, при условии, что вышеупомянутое уведомление об авторских правах и этот параграф включены во все такие копии и производные работы. Однако сам этот документ не может быть изменен каким-либо образом.

Ограниченные разрешения, предоставленные выше, являются бессрочными и не будут отменены.

Этот документ и содержащаяся в нем информация предоставляются "КАК ЕСТЬ", и ОТ ВСЕХ ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ОТКАЗЫВАЮТСЯ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ЛЮБЫМИ ГАРАНТИЯМИ ТОГО, ЧТО ИСПОЛЬЗОВАНИЕ ПРИВЕДЕННОЙ ЗДЕСЬ ИНФОРМАЦИИ НЕ НАРУШИТ НИКАКИХ ПРАВ ИЛИ КАКИХ-ЛИБО ПОДРАЗУМЕВАЕМЫХ ГАРАНТИЙ ТОВАРНОЙ ПРИГОДНОСТИ ИЛИ ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ.

---

Лого взято из Sajya {JSON-RPC} server for Laravel framework

См. также

SALE! 10%

Перенос данных 1C Файловый обмен (TXT, XML, DBF), FTP Системный администратор Программист Платформа 1С v8.3 1С:Розница 2 1С:Управление нашей фирмой 1.6 1С:Бухгалтерия 3.0 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х 1С:Управление нашей фирмой 3.0 1С:Розница 3.0 Россия Платные (руб)

Правила в универсальном формате обмена для ERP 2.5, КА 2.5, УТ 11.5, БП 3.0, Розница, УНФ, для последних версий конфигураций. Ссылки на другие конфигурации в описании публикации. Правила совместимы со всеми другими версиями конфигураций новыми и старыми, поддерживающими обмен и синхронизацию в формате EnterpriseData. Не требуется синхронного обновления правил после обновления другой конфигурации, участвующей в обмене. Типовой обмен через планы обмена кнопкой Синхронизация вручную или автоматически по расписанию, или вручную обработкой.

25080 руб.

12.06.2017    138097    761    292    

404

Перенос данных 1C Файловый обмен (TXT, XML, DBF), FTP Программист Платформа 1С v8.3 1С:ERP Управление предприятием 2 1С:Бухгалтерия 3.0 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х Россия Платные (руб)

Перенос данных из ERP в БП 3 | из КА 2 в БП 3 | из УТ 11 в БП 3 | из ЕРП в БП 3 | В продаже с 2019г. | Воспользовались более 176 предприятий! | Сэкономьте время - используйте готовое решение для перехода! | Перенос разработан в формате КД 2 (правила конвертации данных) | Переносятся все возможные виды документов, начальных остатков и нормативно-справочная информация| Можно опционально выгружать каждую пару "номенклатура+характеристика" как отдельную номенклатуру | Есть выгрузка настроек счетов учета и зарплатных данных из ERP / КА 2 | Можно проверить на вашем сервере перед покупкой, обращайтесь!

45650 руб.

15.04.2019    70356    175    146    

116

Перенос данных 1C Файловый обмен (TXT, XML, DBF), FTP Программист Платформа 1С v8.3 1С:Управление производственным предприятием 1С:ERP Управление предприятием 2 Бухгалтерский учет Управленческий учет Платные (руб)

Переход и перенос данных из 1С:Управление производственным предприятием 1.3 в 1С:ERP Управление предприятием 2.5 и 1С:Комплексную автоматизацию 2.5 с помощью правил обмена. Переносятся остатки, документы (обороты за период), справочная информация. Правила проверены на конфигурациях УПП 1.3 (1.3.227.x), ERP 2.5 (2.5.16.x), КА 2.5 (2.5.16.x) .

28000 руб.

24.06.2020    62349    51    27    

81

Перенос данных 1C Файловый обмен (TXT, XML, DBF), FTP Системный администратор Программист Платформа 1С v8.3 1С:Управление производственным предприятием 1С:Бухгалтерия 3.0 Россия Бухгалтерский учет Управленческий учет Платные (руб)

Перенос данных из 1С:Управление производственным предприятием 1.3 в 1С:Бухгалтерия предприятия 3.0 с помощью правил обмена. Переносятся остатки, документы (обороты за период), справочная информация. Правила проверены на конфигурациях УПП 1.3 (1.3.228.x) и БП 3.0 (3.0.154.x). Правила подходят для версии ПРОФ и КОРП.

28000 руб.

15.12.2021    21778    144    40    

104

Перенос данных 1C Файловый обмен (TXT, XML, DBF), FTP Системный администратор Программист Платформа 1С v8.3 Оперативный учет 1С:Управление торговлей 10 1С:Управление торговлей 11 Россия Управленческий учет Платные (руб)

Перенос данных из 1С:Управление торговлей 10.3 в 1С:Управление торговлей 11.5 с помощью правил обмена. Переносятся остатки, документы (обороты за период), справочная информация. Правила проверены на конфигурациях УТ 10.3.87.x и УТ 11.5.16.x

28000 руб.

23.07.2020    48418    208    64    

170

Перенос данных 1C Файловый обмен (TXT, XML, DBF), FTP Системный администратор Программист Платформа 1С v8.3 Платформа 1C v8.2 1С:Комплексная автоматизация 1.х 1С:Управление торговлей 10 1С:Управление производственным предприятием Россия Платные (руб)

Регулярный обмен, выгрузка, перенос из КА 1.1, УПП 1.3, УТ 10.3 для обмена с любыми конфигурациями, поддерживающими обмен в формате EnterpriseData (КД3) - БП 3.0, ERP, КА 2, УТ 11, Розница 2, УНФ 1.6 и другими. Правила для старых и доработанных конфигураций не требуют синхронного обновления и совместимы с новыми и будущими конфигурациями. Обмен по расписанию, через папку, FTP, почту.

14580 руб.

18.02.2016    184501    573    509    

516

Перенос данных 1C Файловый обмен (TXT, XML, DBF), FTP Программист Платформа 1С v8.3 1С:Управление нашей фирмой 1.6 1С:Бухгалтерия 3.0 1С:Управление нашей фирмой 3.0 Россия Платные (руб)

В продаже с 2018г. | Воспользовались более 41 предприятия! | Правила конвертации (КД 2) для переноса данных из БП 3 в УНФ | Переносятся все виды документов, начальные остатки и вся возможная справочная информация | Есть фильтр по организациям | Оперативно обновляем на новые релизы | Учет в БП 3 должен быть корректным, некорректные данные не переносятся | Можно бесплатно проверить на вашем сервере до покупки!

45650 руб.

10.07.2018    69148    46    126    

49

SALE! %

Перенос данных 1C Взаиморасчеты Оптовая торговля Логистика, склад и ТМЦ Файловый обмен (TXT, XML, DBF), FTP Системный администратор Программист Платформа 1С v8.3 1С:Управление торговлей 10 1С:ERP Управление предприятием 2 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х Россия Управленческий учет Платные (руб)

Можно проверить до покупки, оставьте заявку! Воспользовались более 268 компаний! Перенос в продаже с 2015г., и мы постоянно работаем над его развитием. Перенос данных из УТ 10.3 в УТ 11 | из УТ 10.3 в КА 2 | из УТ 10.3 в ERP. Предлагаем качественное и проверенное временем решение для перехода с УТ 10.3. Можно перенести начальные остатки, нормативно-справочную информацию и все возможные документы. При выгрузке можно установить отбор по периоду, организациям и складам. При выходе новых релизов конфигураций 1C оперативно выпускаем обновление переноса данных.

45650 27000 руб.

24.04.2015    192437    141    241    

272
Оставьте свое сообщение