JSON-RPC — это протокол удаленного вызова процедур (RPC) , закодированный в JSON . Он похож на протокол XML-RPC , определяющий лишь несколько типов данных и команд. JSON-RPC позволяет отправлять уведомления (данные, отправляемые на сервер, которые не требуют ответа), а также отправлять на сервер несколько вызовов, на которые можно отвечать асинхронно.
JSON-RPC работает, отправляя запрос на сервер, реализующий этот протокол. Клиентом в этом случае обычно является программное обеспечение, предназначенное для вызова одного метода удаленной системы. Несколько входных параметров могут быть переданы удаленному методу в виде массива или объекта, тогда как сам метод также может возвращать несколько выходных данных. (Это зависит от реализованной версии.)
Все типы передачи представляют собой отдельные объекты, сериализованные с использованием JSON. [1] Запрос — это вызов определенного метода, предоставляемого удаленной системой. Он может содержать три члена:
method— Строка с именем вызываемого метода. Имена методов, начинающиеся с «rpc». зарезервированы для внутренних методов rpc.params— Объект или массив значений, которые будут переданы в качестве параметров определенному методу. Этот член может быть опущен.id— Строка или недробное число, используемое для сопоставления ответа с запросом, на который он отвечает. [2] Этот член можно опустить, если ответ не должен быть возвращен. [3]Получатель запроса должен ответить действительным ответом на все полученные запросы. Ответ может содержать участников, упомянутых ниже.
result— Данные, возвращаемые вызванным методом. Если при вызове метода произошла ошибка, этот член не должен существовать. [4]error— Объект ошибки, если при вызове метода произошла ошибка, в противном случае этот член не должен существовать. [5] Объект должен содержать код участника (целое число) и сообщение (строку). [6] Необязательный элемент данных может содержать дополнительные данные, специфичные для сервера. Существуют предопределенные коды ошибок, соответствующие кодам, определенным для XML-RPC.id- Идентификатор запроса, на который он отвечает.Поскольку бывают ситуации, когда ответ не нужен или даже нежелателен, были введены уведомления. Уведомление похоже на запрос, за исключением идентификатора, который не требуется, поскольку ответ не будет возвращен. В этом случае idсвойство должно быть опущено (версия 2.0) или указано null(версия 1.0).
В этих примерах -->обозначает данные, отправленные в службу ( запрос ), а <--обозначает данные, поступающие от службы. Хотя в клиент-серверных вычислениях <--его часто называют ответом , в зависимости от версии JSON-RPC он не обязательно подразумевает ответ на запрос .
Запрос и ответ:
-- > { "jsonrpc" : "2.0" , "method" : "subtract" , "params" : { "minuend" : 42 , "вычитаемое" : 23 }, "id" : 3 } < -- { "jsonrpc " : "2.0" , "результат" : 19 , "id" : 3 } Уведомление (нет ответа):
-- > { "jsonrpc" : "2.0" , "метод" : "обновление" , "параметры" : [ 1 , 2 , 3 , 4 , 5 ]} Запрос и ответ:
-- > { "версия" : "1.1" , "метод" : "confirmFruitPurchase" , "params" : [[ "яблоко" , "апельсин" , "манго" ], 1.123 ], "id" : "194521489" } < -- { "версия" : "1.1" , "результат" : "сделано" , "ошибка" : ноль , "id" : "194521489" } Запрос и ответ:
-- > { "метод" : "echo" , "params" : [ "Привет, JSON-RPC" ], "id" : 1 } < -- { "результат" : "Привет, JSON-RPC" , "ошибка" : ноль , «идентификатор» : 1 } id: идентификатор, установленный Клиентом, который ДОЛЖЕН содержать строку, число или значение NULL, если оно включено.
Если оно не включено, предполагается, что это уведомление.
Значение обычно не ДОЛЖНО быть нулевым, а числа НЕ ДОЛЖНЫ содержать дробные части.
Уведомление — это объект запроса без элемента «id».
Объект Request, который является Уведомлением, означает отсутствие интереса Клиента к соответствующему объекту Response, и поэтому объект Response не должен быть возвращен клиенту.
Сервер НЕ ДОЛЖЕН отвечать на Уведомление, включая те, которые находятся в пакетном запросе.
Уведомления не подлежат подтверждению по определению, поскольку у них нет возвращаемого объекта Response.
Таким образом, Клиент не будет знать о каких-либо ошибках (например, «Неверные параметры», «Внутренняя ошибка»).
результат: Этот участник ТРЕБУЕТСЯ в случае успеха.
Этот член НЕ ДОЛЖЕН существовать, если при вызове метода произошла ошибка.
Значение этого члена определяется методом, вызываемым на Сервере.
ошибка: этот элемент НЕОБХОДИМ в случае ошибки.
Этот член НЕ ДОЛЖЕН существовать, если во время вызова не возникло ошибок.
Значение этого члена ДОЛЖНО быть объектом, как определено в разделе 5.1.
Объект ошибки: когда вызов rpc обнаруживает ошибку, объект ответа ДОЛЖЕН содержать элемент ошибки со значением, которое является объектом со следующими элементами: (код) — число, указывающее тип возникшей ошибки.
Это ДОЛЖНО быть целое число.
(сообщение) — строка с кратким описанием ошибки.
Сообщение ДОЛЖНО быть ограничено одним кратким предложением.
(данные) — примитивное или структурированное значение, содержащее дополнительную информацию об ошибке.
Это можно опустить.
Значение этого элемента определяется Сервером (например, подробная информация об ошибках, вложенных ошибках и т. д.).