REST APIの基本構成と仕様
1.概要と構成
REST APIは本体に実装されており、外部サーバーを介さずにディスプレイ内でリクエストを処理します。APIは、電源制御や音量調整、入力切換など、機能ごとに分類しています。また、機能名は対応するエンドポイントURLに含まれます。リクエスト／レスポンスのデータ仕様も定義されているため、必要な制御のみを選択して実装できます。
利用可能なサービス
| サービス | 説明 |
|---|---|
| guide | サーバー上でサポートされているサービスのリストを取得するAPIを提供するサービス。 |
| appControl | アプリケーション自体の起動と、それに付随する特定のアプリケーションに関連する操作を処理するAPI群を扱うサービス。 |
| audio | 音量、効果音などのオーディオ機能に関するAPI群を扱うサービス。 |
| avContent | AVコンテンツの操作や入出力など、全般的な制御に関するAPI群を扱うサービス。 |
| encryption | 暗号化処理に関するAPI群を扱うサービス。 |
| system | 基本的なデバイス機能に関するAPI群を扱うサービス。 |
| videoScreen | 画質、モード、画面設定など、ディスプレイの表示機能に関するAPI群を扱うサービス。 |
URLの構造
Base URLは、IPアドレスまたはホスト名 ＋ /sony で構成されます。
[IP address] or [Host name]/sony
各サービスのAPIには、以下のURL構造でアクセスできます。
http://[IP address] or [Host name]/sony/[サービス名]- サービス名の末尾にスラッシュ（/）が付いたURLは無効です。
- 各サービスは独立しており、APIは対応するサービスのURLで呼び出します。
例 guideサービスのREST API URL (IP：192.168.0.1)
http://192.168.0.1/sony/guide
2.REST APIのバージョン仕様とリクエスト構造
REST APIはバージョン管理されています。API固有のバージョンと、REST API全体のバージョン (generation version)の2種の観点から、実装するディスプレイがサポートするAPIが分かります。
ディスプレイがサポートするREST APIのバージョン確認方法
getSystemInformationのレスポンスで確認できます。
例 リクエスト
{
"method": "getSystemInformation",
"id": 33,
"params": [],
"version": "1.0"
}例 レスポンス
{
"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:API固有バージョンがv1.0、REST API全体のバージョン (generation version)v5.0.0が利用可能です。videoとsystemも同様の指定になっています。
REST APIリストでバージョンを照合し、サポートしている内容を確認ください。
3.JSON-RPC仕様と拡張・制限事項
REST APIでは、標準のJSON形式に加え、独自の拡張フォーマットが定義されており、制限があります。
JSON-RPCデータタイプ
| 種類 | 説明 |
|---|---|
| boolean | 真偽値が格納されます。 |
| boolean-array | 複数の true または false 値が配列に格納されます。 |
| integer | -2147483648 から 2147483647 までの整数が格納されます。 |
| 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}
4.API仕様における内部記述規約
| Multiplicity | 1 : 1回 ? : 0または1回 * : 0回以上 |
| Default | デフォルトは、特定のパラメーターが欠損している場合にデータ受信側が送信側から送信されたと見なす必要がある値です。 |
| Date | 時刻フォーマットとして、ISO 8601を使用しています。 |
| Country | 国名コードとして、ISO 3166 alpha2と追加のコードを使用しています。 |
5.Pre-Shared Keyのレベル別アクセス制御
Pre-Shared Keyの認証レベルは3段階あり、階層的に管理されています。
private：最も高い認証レベル。デバイスIDなどの個人特定情報や、ユーザー固有情報を扱うAPIで使用され、認証が必須です。
generic：デバイス制御やステータス変更を行うAPIで使用され、認証が必要です。
none：認証不要のAPIです。
クライアントは、自身の認証レベルと同じか、それ以下のAPIにアクセス可能です。たとえば、privateレベルの認証を取得していれば、genericおよびnoneレベルのAPIにもアクセスできます。一方で、genericレベルの認証のみを取得している場合は、privateレベルのAPIにはアクセスできません。
ディスプレイ本体は、各APIが定義する認証レベルに従ってアクセス制御を行います。
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"}6.暗号化システム
暗号化システムは、ブラビア プロフェッショナルディスプレイに準搭載して提供している機能で、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要素と少なくとも1つの暗号化データ要素を持ちます。APIに複数の暗号化要素がある場合は、共有のencKeyをparamsに含める必要があります。
例 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
}例 JSON get
{
"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を作成する。
- これらの鍵を使用して暗号化 API を呼び出す。
注意
整合性維持のため、初期化後に鍵を変更しないでください。
暗号鍵のサイズは各システムで定義できます。安全性を考慮した鍵のサイズを使用してください。クライアントは異なるAPI呼び出しで同じ共通鍵を使用できます。また、必要に応じて、クライアントは共通鍵とencKeyを再作成して、セキュリティの向上ができます。
エラーハンドリング
鍵の不整合などの不正な状態が原因で、暗号化モジュールが暗号化または復号化に失敗した場合、ディスプレイは 40002 Encryption Failed エラーを返します。クライアントがこのエラーを受け取った場合は、初期化手順（getPublicKeyの呼び出しから）をやり直してください。
7.デバイスリソースURI
REST APIでは、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使用例
| 入力タイプ | 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機器 |