JSON-RPC
JSON-RPC (нотация объектов JavaScript — удаленный вызов процедур) — это удаленного вызова процедур (RPC), протокол закодированный в JSON . Он похож на протокол XML-RPC , определяющий лишь несколько типов данных и команд. JSON-RPC позволяет отправлять уведомления (данные, отправляемые на сервер, которые не требуют ответа), а также отправлять на сервер несколько вызовов, на которые можно отвечать асинхронно.
История
[ редактировать ]| Версия | Описание | Датированный |
|---|---|---|
| 1.0 | Оригинальная версия | 2005 |
| 1,1 ВД | Рабочий проект . Добавляет именованные параметры, добавляет определенные коды ошибок и добавляет функции самоанализа. | 2006-08-07 |
| 1.1 Всё | Предложение для простого JSON-RPC 1.1 . Альтернативное предложение 1.1 WD. | 2007-05-06 |
| 1.1 Спецификация объекта | Спецификация объекта . Альтернативное предложение 1.1WD/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— Данные, возвращаемые вызванным методом. Если при вызове метода произошла ошибка, этот член не должен существовать. [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", "result": 19, "id": 3}
Уведомление (нет ответа):
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
Версия 1.1 (Рабочий проект)
[ редактировать ]Запрос и ответ:
--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}
<-- {"version": "1.1", "result": "done", "error": null, "id": "194521489"}
Версия 1.0
[ редактировать ]Запрос и ответ:
--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}
См. также
[ редактировать ]- gRPC
- SOAP — протокол обмена сообщениями
- JSON-WSP — протокол, основанный на JSON-RPC, со спецификацией описания сервиса.
Ссылки
[ редактировать ]- ^ «спецификация — JSON-RPC — Trac» . Архивировано из оригинала 17 мая 2008 г. Проверено 14 мая 2008 г.
- ^ «Спецификация JSON-RPC 2.0» .
id: идентификатор, установленный Клиентом, который ДОЛЖЕН содержать строку, число или значение NULL, если оно включено. Если оно не включено, предполагается, что это уведомление. Значение обычно не ДОЛЖНО быть нулевым, а числа НЕ ДОЛЖНЫ содержать дробные части.
- ^ «Спецификация JSON-RPC 2.0» .
Уведомление — это объект запроса без элемента «id». Объект Request, который является Уведомлением, означает отсутствие интереса Клиента к соответствующему объекту Response, и поэтому никакой объект Response не должен быть возвращен клиенту. Сервер НЕ ДОЛЖЕН отвечать на Уведомление, включая те, которые находятся в пакетном запросе. Уведомления не подлежат подтверждению по определению, поскольку у них нет возвращаемого объекта Response. Таким образом, Клиент не будет знать о каких-либо ошибках (например, «Неверные параметры», «Внутренняя ошибка»).
- ^ «Спецификация JSON-RPC 2.0» .
результат: Этот участник ТРЕБУЕТСЯ в случае успеха. Этот член НЕ ДОЛЖЕН существовать, если при вызове метода произошла ошибка. Значение этого члена определяется методом, вызываемым на Сервере.
- ^ «Спецификация JSON-RPC 2.0» .
ошибка: этот элемент НЕОБХОДИМ в случае ошибки. Этот член НЕ ДОЛЖЕН существовать, если во время вызова не возникло ошибок. Значение этого члена ДОЛЖНО быть объектом, как определено в разделе 5.1.
- ^ «Спецификация JSON-RPC 2.0» .
Объект ошибки: когда вызов rpc обнаруживает ошибку, объект ответа ДОЛЖЕН содержать элемент ошибки со значением, которое является объектом со следующими элементами: (код) — число, указывающее тип возникшей ошибки. Это ДОЛЖНО быть целое число. (сообщение) — строка с кратким описанием ошибки. Сообщение ДОЛЖНО быть ограничено одним кратким предложением. (данные) — примитивное или структурированное значение, содержащее дополнительную информацию об ошибке. Это можно опустить. Значение этого элемента определяется Сервером (например, подробная информация об ошибках, вложенных ошибках и т. д.).
Внешние ссылки
[ редактировать ]- Официальный сайт
- Группа Google JSON-RPC обсуждает темы, связанные с протоколом
- Спецификации JSON-RPC, MNlinks и т. д.
- Описание транспорта HTTP для JSON-RPC-2
- спецификации OpenRPC Формат описания службы для JSON-RPC. (open-api, но для json rpc)
- JSend — аналогичная спецификация, определяющая только формат ответа.
