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] Запрос - это вызов определенного метода, предоставляемого удаленной системой. Он может содержать три члена:
method
- Строка с именем вызываемого метода. Имена методов, начинающиеся с «rpc». зарезервированы для внутренних методов rpc.params
- Объект или массив значений, передаваемых в качестве параметров определенному методу. Этот член может быть опущен.id
- Строка или не дробное число, используемое для сопоставления ответа с запросом, на который он отвечает. [2] Этот член может быть опущен, если ответ не должен возвращаться. [3]
Получатель запроса должен дать действительный ответ на все полученные запросы. Ответ может содержать членов, упомянутых ниже.
result
- Данные, возвращаемые вызванным методом. Этот элемент отформатирован как объект JSON-stat. Если при вызове метода произошла ошибка, этот член не должен существовать. [4]error
- Объект ошибки, если при вызове метода произошла ошибка, в противном случае этот член не должен существовать. [5] Объект должен содержать код членов (целое число) и сообщение (строка). [6] Необязательный элемент данных может содержать дополнительные данные, относящиеся к серверу. Существуют предопределенные коды ошибок, которые соответствуют кодам, определенным для XML-RPC.
id
- Идентификатор запроса, на который он отвечает.
Поскольку бывают ситуации, когда ответ не требуется или даже не желателен, были введены уведомления. Уведомление похоже на запрос, за исключением идентификатора, который не нужен, потому что ответ не будет возвращен. В этом случае id
свойство должно быть опущено (Версия 2.0) или быть null
(Версия 1.0).
Примеры
В этих примерах -->
обозначает данные, отправленные службе ( запрос ), а <--
обозначает данные, поступающие от службы. Хотя <--
это часто называется ответом в вычислениях клиент-сервер, в зависимости от версии JSON-RPC он не обязательно подразумевает ответ на запрос .
Версия 2.0
Запрос и ответ:
-> { "jsonrpc" : "2.0" , "method" : "subtract" , "params" : { "minuend" : 42 , "subtrahend" : 23 }, "id" : 3 } <- { "jsonrpc " : " 2.0 " , " результат " : 19 , " id " : 3 }
Уведомление (нет ответа):
-> { "jsonrpc" : "2.0" , "method" : "update" , "params" : [ 1 , 2 , 3 , 4 , 5 ]}
Версия 1.1 (рабочий проект)
Запрос и ответ:
-> { "версия" : "1.1" , "метод" : "confirmFruitPurchase" , "params" : [[ "яблоко" , "апельсин" , "манго" ], 1.123 ], "id" : "194521489" } <- { "версия" : "1.1" , "результат" : "готово" , "ошибка" : null , "id" : "194521489" }
Версия 1.0
Запрос и ответ:
-> { "method" : "echo" , "params" : [ "Hello JSON-RPC" ], "id" : 1 } <- { "result" : "Hello JSON-RPC" , "error" : null , "id" : 1 }
Смотрите также
Рекомендации
- ^ "спецификация - JSON-RPC - Trac" . Архивировано из оригинала на 2008-05-17 . Проверено 14 мая 2008 .
- ^ «Спецификация JSON-RPC 2.0» .
id: идентификатор, установленный Клиентом, который ДОЛЖЕН содержать значение String, Number или NULL, если включено. Если он не включен, предполагается, что это уведомление. Обычно значение НЕ ДОЛЖНО быть NULL, а числа НЕ ДОЛЖНЫ содержать дробные части.
- ^ «Спецификация JSON-RPC 2.0» .
Уведомление - это объект запроса без члена «id». Объект запроса, который является уведомлением, означает отсутствие интереса клиента к соответствующему объекту ответа, и поэтому объект ответа не требуется возвращать клиенту. Сервер НЕ ДОЛЖЕН отвечать на уведомления, включая те, которые находятся в пакетном запросе. Уведомления не могут быть подтверждены по определению, поскольку они не имеют объекта Response, который должен быть возвращен. Таким образом, Клиент не будет знать никаких ошибок (например, «Недействительные параметры», «Внутренняя ошибка»).
- ^ «Спецификация JSON-RPC 2.0» .
результат: этот участник НЕОБХОДИМ в случае успеха. Этот член НЕ ДОЛЖЕН существовать, если при вызове метода произошла ошибка. Значение этого члена определяется методом, вызываемым на сервере.
- ^ «Спецификация JSON-RPC 2.0» .
ошибка: этот член НЕОБХОДИМ при ошибке. Этот член НЕ ДОЛЖЕН существовать, если во время вызова не возникла ошибка. Значение этого члена ДОЛЖНО быть объектом, как определено в разделе 5.1.
- ^ «Спецификация JSON-RPC 2.0» .
Объект ошибки: когда вызов rpc обнаруживает ошибку, объект ответа ДОЛЖЕН содержать член ошибки со значением, которое является объектом со следующими элементами: (код) - Число, указывающее тип возникшей ошибки. Это ДОЛЖНО быть целым числом. (сообщение) - строка с кратким описанием ошибки. Сообщение ДОЛЖНО быть ограничено одним кратким предложением. (данные) - примитивное или структурированное значение, которое содержит дополнительную информацию об ошибке. Это можно не указывать. Значение этого элемента определяется Сервером (например, подробная информация об ошибках, вложенные ошибки и т. Д.).
Внешние ссылки
- Официальный веб-сайт
- JSON-RPC Группа Google обсуждает темы протокола и связанные с ним
- Спецификации JSON-RPC, MNlinks и т. Д.
- Описание транспорта HTTP для JSON-RPC-2
- Формат описания OpenRPC Specification Service для JSON-RPC. (open-api, но для json rpc)