JSON-RPC 协议概述

简介

JSON-RPC（JavaScript 对象表示法远程过程调用）是一种远程过程调用（RPC）协议。它使用 JSON 作为数据格式，可通过 TCP Socket、HTTP、WebSocket 等多种传输协议在客户端和服务器之间进行通信。

JSON-RPC 具有以下特点：

• 简洁性：使用 JSON 作为数据交换格式，简单易懂且易于解析。
• 轻量级：采用基于文本的 JSON 格式进行数据交换，数据和协议结构简单，数据量小，网络传输速度快，性能高。
• 跨语言和跨平台：JSON-RPC 支持不同编程语言（如 C++、Python 等）和平台之间的通信。
• 支持多种传输协议：JSON-RPC 可使用多种传输协议，包括 HTTP、TCP Socket、WebSocket 等，适用于多样化的网络环境。
• 错误处理：JSON-RPC 定义了错误对象和错误代码，客户端可根据服务器返回的错误信息进行调试和问题处理。

JSON-RPC 遵循请求-响应模型，用于客户端和服务器之间的远程过程调用。客户端向服务器发送 JSON 格式的请求，例如 { "jsonrpc": "2.0", "method": "getRobotNames", "params": [], "id": 1 }。服务器接收请求后，解析该 JSON 对象，提取“method”“params”和“id”字段的值，并使用提供的参数执行与“method”名称对应的方法。服务器根据执行结果生成响应对象，将其序列化为 JSON 格式后发送回客户端。客户端接收服务器的响应。

支持的传输协议和端口号

AUBO SDK 中的 RPC 模块支持 TCP Socket、HTTP 和 WebSocket 传输协议。对应的端口号如下：

协议	端口号
TCP Socket	30004
HTTP	9012
WebSocket	9012

JSON-RPC 2.0 规范

请求对象

RPC 请求对象包含以下成员：

• jsonrpc：表示 JSON-RPC 协议的版本，必须为“2.0”。
• method：要调用的方法名称，为字符串类型。
• params：传递给方法的参数，为结构化值。
• id：唯一标识符。

响应对象

RPC 响应对象有两种类型：一种用于 RPC 调用成功的情况，另一种用于 RPC 调用失败的情况。

1. 当 RPC 调用成功时，响应对象包含以下成员：

   • jsonrpc：表示 JSON-RPC 协议的版本，必须为“2.0”。
   • result：执行方法后的返回值。
   • id：标识符，必须与请求对象中的标识符一致。

2. 当 RPC 调用失败时，响应对象包含以下成员：

   • jsonrpc：表示 JSON-RPC 协议的版本，必须为“2.0”。
   • error：错误对象，包含以下成员：
     • code：错误代码。
     • message：错误的简要描述。
     • data：有关错误的附加信息（可忽略）。
   • id：标识符，必须与请求对象中的标识符一致。

The error codes are as follows:

错误代码	消息	描述
-32700	Parse error.	接收的 JSON 无效。解析 JSON 文本时发生错误。
-32600	Invalid Request.	发送的 JSON 不是有效的请求对象。
-32601	Method not found.	方法不存在或不可用。
-32602	Invalid params.	方法参数无效。
-32603	Internal error.	内部 JSON-RPC 错误。
-32099..-32000	Server error.	保留用于实现定义的服务器错误。

示例

以下是在 Python 中使用 WebSocket 协议进行传输的示例：

（假设 localhost 是机器人的 IP 地址）

import json
import websocket

# WebSocket 服务器地址
server_address = "ws://localhost:9012"

# 创建 WebSocket 连接
ws = websocket.create_connection(server_address)

# 构建 JSON-RPC 请求
request = {
    "jsonrpc": "2.0",
    "method": "getRobotNames",
    "params": [],
    "id": 1
}

# 将请求转换为 JSON 字符串
request_json = json.dumps(request)

# 发送请求
ws.send(request_json)

# 接收响应
response_json = ws.recv()

# 解析响应
response = json.loads(response_json)

print("Received Response:", response)

# 关闭 WebSocket 连接
ws.close()

程序输出：

Received Response: {'id': 1, 'jsonrpc': '2.0', 'result': ['rob1']}