JSON-RPC - JSON-RPC

JSON-RPC это удаленный вызов процедур протокол закодировано в JSON. Это похоже на XML-RPC протокол, определяющий только несколько типов данных и команд. JSON-RPC позволяет отправлять уведомления (данные, отправляемые на сервер, не требующие ответа), а также отправлять несколько вызовов на сервер, на которые можно отвечать асинхронно.

История

ВерсияОписаниеДатировано
1.0Оригинальная версия2005
1.1 WDРабочий проект. Добавляет именованные параметры, добавляет конкретные коды ошибок и добавляет функции самоанализа.2006-08-07
1.1 AltПредложение для простого JSON-RPC 1.1. Альтернативное предложение 1.1 WD.2007-05-06
1.1 Спецификация объектаСпецификация объекта. Альтернативное предложение 1.1 WD / 1.1ALT.2007-07-30
1.2Предложение. Более поздняя версия этого документа была переименована в 2.0.2007-12-27
2.0Предложение по спецификации2009-05-24
2.0 (пересмотренный)Технические характеристики2010-03-26

использование

JSON-RPC работает, отправляя запрос на сервер, реализующий этот протокол. Клиент в этом случае обычно представляет собой программное обеспечение, которое намеревается вызвать единственный метод удаленной системы. Несколько входных параметров могут быть переданы удаленному методу в виде массива или объекта, тогда как сам метод также может возвращать несколько выходных данных. (Это зависит от реализованной версии.)

Все типы передачи представляют собой отдельные объекты, сериализованные с использованием JSON.[1] Запрос - это вызов определенного метода, предоставляемого удаленной системой. Он может содержать три члена:

  • метод - Строка с именем вызываемого метода. Имена методов, начинающиеся с «rpc». зарезервированы для внутренних методов rpc.
  • параметры - Объект или массив значений, передаваемых в качестве параметров определенному методу. Этот член может быть опущен.
  • я бы - Строка или не дробное число, используемое для сопоставления ответа с запросом, на который он отвечает.[2] Этот член может быть опущен, если ответ не должен возвращаться.[3]

Получатель запроса должен дать действительный ответ на все полученные запросы. Ответ может содержать членов, упомянутых ниже.

  • результат - Данные, возвращаемые вызванным методом. Этот элемент отформатирован как объект JSON-stat. Если при вызове метода произошла ошибка, этот член не должен существовать.[4]
  • ошибка - Объект ошибки, если при вызове метода произошла ошибка, в противном случае этот член не должен существовать.[5] Объект должен содержать члены код (целое число) и сообщение (нить).[6] Необязательный данные member может содержать дополнительные данные, специфичные для сервера. Существуют предопределенные коды ошибок, которые соответствуют кодам, определенным для XML-RPC.
  • я бы - Идентификатор запроса, на который он отвечает.

Поскольку бывают ситуации, когда ответ не требуется или даже не требуется, были введены уведомления. Уведомление похоже на запрос, за исключением идентификатора, который не нужен, потому что ответ не будет возвращен. В этом случае я бы свойство должно быть опущено (версия 2.0) или быть ноль (Версия 1.0).

Примеры

В этих примерах --> обозначает данные, отправленные в службу (запрос), пока <-- обозначает данные, поступающие от службы. Несмотря на то что <-- часто называют отклик в клиент-серверных вычислениях, в зависимости от версии JSON-RPC, это не обязательно подразумевает отвечать на запрос.

Версия 2.0

Запрос и ответ:

--> {"jsonrpc": "2.0", "метод": "вычесть", "параметры": {"уменьшаемое": 42, "вычитаемое": 23}, "я бы": 3}<-- {"jsonrpc": "2.0", "результат": 19, "я бы": 3}

Уведомление (нет ответа):

--> {"jsonrpc": "2.0", "метод": "Обновить", "параметры": [1,2,3,4,5]}

Версия 1.1 (рабочий проект)

Запрос и ответ:

--> {"версия": "1.1", "метод": "confirmFruitPurchase", "параметры": [["яблоко", "апельсин", "манго"], 1.123], "я бы": "194521489"}<-- {"версия": "1.1", "результат": "сделано", "ошибка": ноль, "я бы": "194521489"}

Версия 1.0

Запрос и ответ:

--> {"метод": "эхо", "параметры": [«Привет, JSON-RPC»], "я бы": 1}<-- {"результат": «Привет, JSON-RPC», "ошибка": ноль, "я бы": 1}

Смотрите также

Рекомендации

  1. ^ "спецификация - JSON-RPC - Trac". Архивировано из оригинал на 2008-05-17. Получено 2008-05-14.
  2. ^ «Спецификация JSON-RPC 2.0». id: идентификатор, установленный Клиентом, который ДОЛЖЕН содержать значение String, Number или NULL, если включено. Если он не включен, предполагается, что это уведомление. Обычно значение НЕ ДОЛЖНО быть NULL, а числа НЕ ДОЛЖНЫ содержать дробные части.
  3. ^ «Спецификация JSON-RPC 2.0». Уведомление - это объект запроса без члена "id". Объект запроса, который является уведомлением, означает отсутствие интереса клиента к соответствующему объекту ответа, и поэтому объект ответа не требуется возвращать клиенту. Сервер НЕ ДОЛЖЕН отвечать на уведомления, включая те, которые находятся в пакетном запросе. Уведомления не подлежат подтверждению по определению, поскольку они не имеют объекта Response, который должен быть возвращен. Таким образом, Клиент не будет знать о каких-либо ошибках (например, «Недействительные параметры», «Внутренняя ошибка»).
  4. ^ «Спецификация JSON-RPC 2.0». результат: этот участник НЕОБХОДИМ в случае успеха. Этот член НЕ ДОЛЖЕН существовать, если при вызове метода произошла ошибка. Значение этого члена определяется методом, вызываемым на сервере.
  5. ^ «Спецификация JSON-RPC 2.0». ошибка: этот член НЕОБХОДИМ при ошибке. Этот член НЕ ДОЛЖЕН существовать, если во время вызова не возникла ошибка. Значение этого члена ДОЛЖНО быть объектом, как определено в разделе 5.1.
  6. ^ «Спецификация JSON-RPC 2.0». Объект ошибки: когда вызов rpc обнаруживает ошибку, объект ответа ДОЛЖЕН содержать член ошибки со значением, которое является объектом со следующими элементами: (код) - число, указывающее тип возникшей ошибки. Это ДОЛЖНО быть целым числом. (сообщение) - строка с кратким описанием ошибки. Сообщение ДОЛЖНО быть ограничено одним кратким предложением. (данные) - примитивное или структурированное значение, которое содержит дополнительную информацию об ошибке. Это можно не указывать. Значение этого элемента определяется Сервером (например, подробная информация об ошибках, вложенные ошибки и т. Д.).

внешняя ссылка