REST API 基本结构和规范

REST API按功能分类，如电源控制、音量调整、输入切换等。功能名称包含在相应的端点URL中。已定义请求和响应的数据规格，可选择性地仅实现所需的控制。

注意
BRAVIA REST API 旨在受信任的本地网络中使用。若在公共网络中使用，显示器可能会遭到恶意客户端的非法控制。

可用的 API 服务

类型	说明
向导(guide)	guide 服务提供 API 来检索服务器上支持的服务列表。
应用程序控制(appControl)	此服务处理用于启动应用程序本身的 API，以及与特定应用程序相关的操作。
音频(audio)	此服务处理与音频功能相关的 API，例如音量、音效等。
av内容(avContent)	此服务处理显示器 AV 内容的输入和输出的整体控制，以及显示器上 AV 内容本身的操作。
加密(encryption)	此服务处理与加密相关的 API。
系统(system)	此服务处理与基本显示器功能相关的 API。
视频屏幕(videoScreen)	此服务处理与视频屏幕功能相关的 API。

示例 URL 结构

Base URL 由 IP 地址或主机名加上 /sony 组成。

[IP address] or [Host name]/sony

各服务的API可通过以下URL结构进行访问。　

HTTP

http:// [IP address] or [Host name]/sony/[服务名]

http:// [IP address] or [Host name]/sony/[服务名]

服务名末尾带有斜杠（/）的URL无效。
各服务相互独立，API需要通过对应服务的URL调用。

示例 guide 服务（IP：192.168.0.1）

http://192.168.0.1/sony/guide

REST API采用版本管理。包括API固有的版本以及REST API整体版本 (generation version)。通过这两个版本可判断显示器所支持的 API。

如何确认显示器支持的REST API版本

可在getSystemInformation响应中确认REST API版本。

示例请求

JSON

{
"method": "getSystemInformation",
"id": 33,
"params": [],
"version": "1.0"
}

{
"method": "getSystemInformation",
"id": 33,
"params": [],
"version": "1.0"
}

示例响应

JSON

{
"result": [{
"product": "TV",
"region": "",
"language": "eng",
"model": "FW-85BZ35P",
"serial": "1000001",
"macAddr": "12:34:56:78:9A:BC",
"name": "BRAVIA",
"generation": "5.0.0",
"area": "ZZZ",
"cid": "01234567890123456789012345678901"
}],
"id": 33
}

{
"result": [{
"product": "TV",
"region": "",
"language": "eng",
"model": "FW-85BZ35P",
"serial": "1000001",
"macAddr": "12:34:56:78:9A:BC",
"name": "BRAVIA",
"generation": "5.0.0",
"area": "ZZZ",
"cid": "01234567890123456789012345678901"
}],
"id": 33
}

“audio”：v1.0的API固有版本可用，v5.0.0的REST API整体版本 (generation version)可用。
“video”和”system”也采用相同的指定。

请参照 REST API 列表核对版本，确认支持的内容。

REST API除了标准JSON格式外，还定义了自己的扩展格式。该API也有一定的限制。

JSON-RPC数据类型

类型	说明
布尔值（boolean）	存储布尔值。
布尔数组（boolean-array）	在数组中存储多个 true 或 false 值。
整数（integer）	存储 -2,147,483,648 到 2,147,483,647 范围内的整数。
整数数组（integer-array）	在数组中存储多个整数。
双精度浮点数（double）	存储 -2.2250738585072014e-308 到 1.7976931348623157e+308 范围内的浮点数。
双精度浮点数组（double-array）	在数组中存储多个浮点数。
字符串（string）	存储字符串。除非在各 API 规范中另有说明，否则采用 UTF-8 编码。
字符串数组（string-array）	在数组中存储多个字符串。

扩展功能

成功响应中忽略”error”，失败时省略”result”。
“error”是[error_code, error_message]格式的数组。
·”error_code”为整数。
“error_message”为调试字符串（不可用于控制操作）。
在请求中需指定”version”（例如”1.0″）以保持客户端兼容性。

限制事项

“null”原则上视为无效参数。
・”params”和”result”为固定长度数组（符合API规格）。
“id”使用1到2147483647的整数（0是保留值，不可使用）。

示例 JSON-RPC

请求

{"method": "getMyName", "params": [{"key": 1116}], "id": 2, "version": "1.0"}

响应（成功）

{"result": [{"name": "Alice"}], "id": 2}

响应（失败）

{"error": [401, "Unauthorized"], "id": 2}

多重性	1：必需一次 ?：零次或一次 *：零次或多次
默认值	默认值是在缺少特定参数的情况下，数据接收方必须将其视为从发送方发送的值。
日期	本产品采用ISO 8601。
国家	本产品使用iso3166 alpha 2及其他编码。

Pre-Shared Key（预共享密钥）认证有三个级别，采用分级管理。

private：最高认证级别。用于处理设备ID等个人可识别信息及用户特定信息的API，需要认证。
generic：用于进行设备控制或更改状态的API，需要认证。
none：无需认证的API。

客户端可访问与其认证级别相同或更低级别的API。例如，拥有private级别认证的客户端也可访问generic和none级别的API。但是，仅拥有generic级别认证的客户端无法访问private级别的API。

显示器根据各API定义的认证级别控制访问。

HTTP

POST /sony/system HTTP/1.1
 Host: 192.168.0.1 Accept: */* 
Cache-Control: no-cache 
Connection: close 
Content-Type: application/json; charset=UTF-8 
Pragma: no-cache 
X-Auth-PSK: 1234 
Content-Length: 70 {"method": "getPowerStatus", "params": [], "id": 50, "version": "1.0"}

POST /sony/system HTTP/1.1
 Host: 192.168.0.1 Accept: */* 
Cache-Control: no-cache 
Connection: close 
Content-Type: application/json; charset=UTF-8 
Pragma: no-cache 
X-Auth-PSK: 1234 
Content-Length: 70 {"method": "getPowerStatus", "params": [], "id": 50, "version": "1.0"}

加密系统作为BRAVIA专业显示器的标准功能，通过encryption API提供。该系统通过标准2048/1024位RSA（RFC 3447）和128位AES-CBC算法（RFC 3602），对需要安全通信的字符串参数进行加密和解密。

注意
请注意，加密系统用于防止通信被窃听，但并不能阻止非法访问或冒充。此方法并不会对整个通信进行加密，而只对特定参数进行加密，因此其通信方式与JSON协议常规通信一致。

1. 接收流程

加密系统使用RSA公钥和AES对称密钥的混合方式。敏感数据通过AES对称密钥加密。RSA公钥用于在客户端和显示器之间安全共享对称密钥。

加密发送流程图

准备
显示器生成RSA密钥对，客户端生成AES密钥并使用RSA公钥进行加密。
发送
对敏感数据进行AES加密，然后与加密的AES密钥一起发送到显示器。
接收
显示器使用RSA私钥解密AES密钥，然后用解密后的AES密钥解密数据。
使用RSA私钥解密共享密钥，然后使用该共享密钥解密数据。

2. 加密流程

从显示器将数据发送到客户端时也采用相同的加密机制。在预先准备密钥(生成RSA密钥对、创建AES密钥)后，将加密数据与加密密钥进行通信。即使通信被截取，第三者也无法解密。

机密数据接收流程

3.getPublicKey定义

getPublicKey方法是加密系统的通用API。发送或获取加密参数的API包含encKey元素和至少一个加密数据元素。如果API有多个加密元素，则必须在”params”中包含共享的encKey。

示例 JSON

JSON

{
    "method":"sendSecretData",
    "params":[
        {
            "secretData1":"G9KgQDustrxplKFcy9fnVQ==",
            "secretData2":"At2gQDgst6xplKFcy9fnVQ==",
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[],
    "id":1
}

{
    "method":"sendSecretData",
    "params":[
        {
            "secretData1":"G9KgQDustrxplKFcy9fnVQ==",
            "secretData2":"At2gQDgst6xplKFcy9fnVQ==",
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[],
    "id":1
}

示例 JSON get

JSON

{
    "method":"getSecretData",
    "params":[
        {
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[
        {
           "secretData":"G9KgQDustrxplKFcy9fnVQ=="
        }
    ],
    "id":1
}

{
    "method":"getSecretData",
    "params":[
        {
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[
        {
           "secretData":"G9KgQDustrxplKFcy9fnVQ=="
        }
    ],
    "id":1
}

4.实现指南

显示器开机时会生成RSA公钥/私钥对。RSA密钥生成耗时较长。请根据显示器规格设置位大小和管理方法。

客户端初始化步骤

调用getPublicKey获取显示器的公钥。
生成AES对称密钥并使用RSA公钥加密以创建encKey。
3.使用这些密钥调用加密API。

注意
初始化后请勿更改密钥，以保持一致性。

加密密钥的大小可以在各系统中定义。请使用考虑到安全性的密钥大小。客户端可以在不同的 API 调用中使用相同的共享密钥。此外，如有必要，客户端可以重新创建共享密钥和 encKey，以提高安全性。

错误处理

如果由于密钥不匹配等无效状态导致加密模块的加密或解密失败，显示器将返回 40002 Encryption Failed 错误。如果客户端收到此错误，请重新执行初始化步骤（从调用 getPublicKey 开始）。

在REST API中，标准URI结构，如定义RFC 3986, 用于表示设备的资源。方案用于引用设备资源。 URI基本上是由设备/服务器提供的，客户端不应该更改/修改URI。

定义方案

基本架构

架构	类型	说明
extInput	输入资源(input resource)	外部输入资源

定义的来源

架构	来源	说明
extInput	extInput:cec	CEC 输入资源
extInput	extInput:component	分量外部输入资源
extInput	extInput:composite	复合外部输入资源
extInput	extInput:hdmi	HDMI 外部输入资源
extInput	extInput:widi	Wi-Fi 显示资源

举例说明

输入类型	URI 示例	说明
HDMI	extInput:hdmi?port=1	HDMI 1
HDMI	extInput:hdmi?port=2	HDMI 2
HDMI	extInput:hdmi?port=3	HDMI 3
HDMI	extInput:hdmi?port=4	HDMI 4
分量	extInput:component?port=1	分量 1
分量	extInput:component?port=2	分量 2
分量	extInput:component?port=3	分量 3
分量	extInput:component?port=4	分量 4
Wi-Fi 显示输入	extInput:widi?port=1	Wi-Fi 显示
CEC 录像机	extInput:cec?type=recorder&port=1	录像机 1
CEC 录像机	extInput:cec?type=recorder&port=2	录像机 2
CEC 录像机	extInput:cec?type=recorder&port=3	录像机 3
CEC 播放器	extInput:cec?type=player&port=1	播放器 1
CEC 播放器	extInput:cec?type=player&port=2	播放器 2
CEC 播放器	extInput:cec?type=player&port=3	播放器 3
CEC 调谐器	extInput:cec?type=tuner&port=1	调谐器 1
CEC 调谐器	extInput:cec?type=tuner&port=2	调谐器 2
CEC 调谐器	extInput:cec?type=tuner&port=3	调谐器 3
其他 CEC 设备	extInput:cec?type=freeuse	通用 CEC 设备

REST API 基本结构和规范

1.概述和结构

可用的 API 服务

示例 URL 结构

2.REST API版本规格和请求结构

如何确认显示器支持的REST API版本

3.JSON-RPC规格、扩展和限制事项

JSON-RPC数据类型

扩展功能

限制事项

4.API规格中的内部描述规则

5.Pre-Shared Key级别访问控制

6.加密系统

1. 接收流程

加密发送流程图

2. 加密流程

机密数据接收流程

3.getPublicKey定义

4.实现指南

客户端初始化步骤

错误处理

7.设备资源URI

定义方案