介绍

REST API 参数规范

协议规范概述

REST API通过HTTP使用JSON-RPC。 本文档主要解释每个API的请求/响应的JSON数据格式。 REST API根据功能分类为服务。 已定义的服务列表列在此页的底部。 服务名称用作REST API URL的一部分。

http://[Base URL]/[service name]

注意：

不接受在[服务器名称 ]后面加上”/”(斜杠)的url。

每个服务都应该是独占的，并且应该清楚API可以属于哪个服务。通过只搜索特定服务中的API列表，用户应该更容易搜索API。应该使用服务的URL调用属于服务的每个API。

基本 URL

[IP]/sony

av控制服务器的REST API URL示例 (IP: 192.168.0.1)

http://192.168.0.1/sony/avControl

版本控制

REST API规范由版本控制系统管理。每个API都有自己的版本。每个版本由两个用“.”(点）分隔的数字表示。

X.Y

X代表少校的版本。如果有很大的变化，这个数字就会增加。在这里，一个大的变化意味着协议规范的变化会影响服务上的定义。Y表示规范的次要版本。当API的定义改变时，这个数字将会增加。API定义表示JSON的格式。例如，如果在请求或响应中添加了成员，则必须增加版本。基本上，每个API都应该从1.0版本定义。客户端可以通过在请求中设置版本来调用特定版本的API。此版本信息只能用于区分API调用功能。如果客户端应用程序希望基于服务器应用程序/产品的生成更改其行为，客户端应用程序应该使用另一个API来检索生成。(例如:获取系统服务器上的内部信息。)

REST API类型

在REST API中，除了JSON类型之外，还定义了扩展类型。

json-rpc和扩展/限制

JSON-RPC的使用带有一些限制和扩展。JSON-RPC是一种简单而轻量级的通信协议。

json-rpc请求示例

{"method": "echo", "params": ["Hello REST API"], "id": 1}

json-rpc反应示例

{"result": ["Hello REST API"], "error": null, "id": 1}

BRAVIA商用显示器对一些扩展和限制进行了调整，以保持api的简单易用。

• 扩展
  • 如果请求成功，响应中将忽略“error”。但是，如果请求失败，则跳过“result”。
  • “error”成员必须是一个数组，定义为 [error_code, error_message]. “error_code” is an integer, “error_message” 是一个字符串. (解释了常见的错误代码和消息 这里. 每个API定义都解释了特定于API的错误代码。)
  • “error_message” 仅用于调试目的。客户端应用程序不能使用它来更改其行为，否则可能会使用相同的消息设置不同的消息 ““error_code”.
  • “版本”必须在请求中设置。通过设置版本，当服务器的行为改变时，客户端不会受到影响。版本可以设置为两个用点(例如)分隔的数字。“1.0”)。上面已经解释了版本控制系统。
• 限制
  • Null valued parameters must be regarded as absent in the request/response, unless otherwise mentioned in each API specification.
  • “params”/”result”必须是一个固定长度的数组类型。(每个API规范都定义了长度。)
  • “id”是一个整数，不能使用“0”。“0”是一个特殊的数字系统。可以将id设置为 “1” - “2147483647” (0x00000001 - 0x7FFFFFFF).

REST API请求示例

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

REST API响应示例(成功案例)

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

REST API响应示例(失败案例)

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

惯例

文档的内部描述约定如下所述。

身份验证

当前定义了以下身份验证级别。

身份验证级别是分层的，其中“私人”在层次结构中是最高的。 在层次结构中具有相同或更高访问级别的客户机应用程序可以访问API。 这意味着，如果用户对客户机应用程序接受级别为“private”的身份验证，那么在较低级别(如：通用的)也可用于客户端应用程序。 相反，如果用户对客户机应用程序接受较低级别的身份验证，那么客户机应用程序就不能使用级别较高的api。

REST API服务器应该遵循每个API部分中描述的这个级别。

请浏览 IP控制认证 在BRAVIA专业显示器上设置身份验证。通过“预共享密钥”进行身份验证后，即可使用“私人”和“通用的”身份验证级别的API。

REST-API HTTP Request Example (Pre-Shared Key: “1234”)

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"}

局域网唤醒

请参照 局域网唤醒.

API服务列表