如何使用 Cloud API

在开始使用Cloud API之前，需要将以下信息注册到专用服务器。请通过安全的方式（如带密码的邮件或访问受限的聊天工具）提供给索尼负责人。

在开始使用Cloud API之前，需要将以下信息注册到专用服务器。请通过安全的方式（如带密码的邮件或访问受限的聊天工具）提供给索尼负责人。

※日本不支持Provisioning API。请参阅Control & Monitoring API。

1. 准备注册信息

收集注册操作所需的以下信息。

2. 获取Device ID

将Service Provider ID和API Key包含在HTTP标头中，并向API端点发送请求以连接到专用服务器。如向”Register a device” 请求MAC地址和User data，即可生成Device ID。

curl -i ^
  https://[Cloud API端点]/kitting/v1/devices^
  -H 'Content-Type: application/json’^
  -H 'X-API-Key:~’^
  -d '{"mac":"AA-BB-CC-DD-EE-FF", "userData":“~" }’^

curl -i ^
  https://[Cloud API端点]/kitting/v1/devices^
  -H 'Content-Type: application/json’^
  -H 'X-API-Key:~’^
  -d '{"mac":"AA-BB-CC-DD-EE-FF", "userData":“~" }’^

3. 将显示器连接到LAN

请使用有线LAN连接。

注意
如果已在使用显示器，请执行”主机设置”中的[恢复出厂设置]。
操作步骤：[设置]→[关于]→[重置]→[恢复出厂设置]→[全部清除]
显示器将自动重启。

4. 使用One Time Code认证专用服务器

显示器启动后，几秒钟后会显示One-Time Code（6位数代码和二维码）。
One-Time Code的有效期约为30分钟。
通过API “Input a one-time code” 将6位数代码发送到专用服务器。

5. 显示器自动开始设置

专用服务器认证One-Time Code后，将根据先前提供的信息自动开始显示器设置。此过程可能需要数十分钟。

6. 向Webhook URL发送设置完成通知

设置完成后，Token将POST到先前提供的Webhook URL。Token的有效期约为1小时。

7. 验证设置完成

通过”Get Device events”发送Token后，即可确认已完成设置的显示器Device ID和User data。

1. 向Webhook URL发送设置完成通知

※ 使用Provisioning API时，由于重复，请跳过此步骤。
设置完成后，Token将POST到先前提供的Webhook URL。Token的有效期约为1小时。

2. 确认显示器的Device ID和User data

※使用Provisioning API时会重复，请跳过此步骤。
使用Get Device events发送Token，即可确认显示器的Device ID和User data。

3. Access Key的创建

使用Create Access Key可生成用于对显示器进行分组管理的Access Key。

4. Control & Monitoring API的执行

使用”Associate the device with the access key”将各Device ID与Access Key关联。

5. Device Management的执行

使用Device ID和Access Key指定设备，然后执行任何Cloud API以监控和控制显示器。

使用”set screen rotate”旋转应用程序显示方向

可使用Control & Monitoring API的set screen rotate旋转应用的显示方向。

注意

• 不支持SurfaceView旋转。请改用TextureView进行视频播放。
• 请注意，以下型号不支持使用set screen rotate进行屏幕旋转。
• BZ40J (100英寸)
• BZ53L/50L/30L(98英寸)

可通过”take a screenshot”获取的图像、获取图像时的注意事项

1. 可获取的图像

可通过”take a screenshot”获取的图像会因播放应用程序和输入源而异。

关于BZ40J（100英寸）/ BZ53L / BZ50L / BZ30L（98英寸）的使用
如果将”主机设置”中的[画质模式]设置为[游戏]或[图形]以外的模式，通过HDMI连接获取4K以下的视频或Decimated Video（降采样视频）的图像时，将缩小显示在屏幕左上方的1/4区域。

使用”take a screenshot”获取的图像

屏幕状态：显示[主页]画面

实际屏幕

screenshot获取的图像
※分辨率 1920×1080

可捕获与实际屏幕相同的图像。

screenshot?plane=video
获取的图像（Video Plane）

［不支持］

屏幕状态：显示设置画面

实际屏幕

screenshotの取得画像
※分辨率 1920×1080

可捕获与实际屏幕相同的图像。

screenshot?plane=video
获取的图像（Video Plane）

［不支持］

屏幕状态：播放应用 – 非Tunnel模式

实际屏幕

screenshot获取的图像
※分辨率 1920×1080

可捕获与实际屏幕相同的图像。

screenshot?plane=video
获取的图像（Video Plane）

［不支持］

屏幕状态：播放应用 – 使用Tunnel模式

实际屏幕

screenshot获取的图像
※分辨率 320×180

BZ40J（100英寸）/ BZ53L / BZ50L / BZ30L（98英寸)

无法获取UI

---

其他型号

可捕获与实际屏幕相同的图像。

screenshot?plane=video
获取的图像（Video Plane）

BZ40J（100英寸）/ BZ53L / BZ50L / BZ30L（98英寸)

无法获取UI

---

其他型号

可捕获与实际屏幕相同的图像。

屏幕状态：HDMI输入源　※机身固件 PKG6.7612 以上支持

实际屏幕

screenshot获取的图像
※分辨率 320×180

BZ40J（100英寸）/ BZ53L / BZ50L / BZ30L（98英寸)

无法获取UI

---

其他型号

可捕获与实际屏幕相同的图像。

screenshot?plane=video
获取的图像（Video Plane）

BZ40J（100英寸）/ BZ53L / BZ50L / BZ30L（98英寸)

无法获取UI

---

其他型号

可捕获与实际屏幕相同的图像。

2. 防止截屏时播放暂停的措施

“take a screenshot”调用Android回调函数onPause()和onResume()。因此，如果播放应用程序在onPause()中暂停视频，则播放将停止约0.1至0.5秒。

因此，建议在onStop()中实现视频暂停处理。这可防止截屏期间出现暂停。

示例 Java的情况

Java

@Override
    protected void onStop() {
        super.onStop();
        if (videoView.isPlaying()) {
            videoView.pause();

@Override
    protected void onStop() {
        super.onStop();
        if (videoView.isPlaying()) {
            videoView.pause();

关于使用Control & Monitoring API时的显示器画面显示与调用次数

在显示器屏幕开启的状态下使用以下Control & Monitoring API时，可能会显示”Please Wait”对话框，显示器可能会在几秒到几十秒内无响应。

适用的Control & Monitoring API

/devices/{deviceId}/apk-install/requests
/devices/{deviceId}/apk-uninstall/requests
/devices/{deviceId}/pro-mode/requests
/devices/{deviceId}/reboot/requests
/devices/{deviceId}/settings-export/requests
/devices/{deviceId}/settings-import/requests
/{deviceId}/system-software-update/requests

这是因为显示器在API处理期间执行内部处理，会暂时限制用户的操作。处理完成后即可恢复正常操作。另外，建议将Cloud API调用次数限制为每秒不超过50次。如果调用次数过多，可能因服务器过载而导致错误。万一发生错误，请稍等片刻后重新尝试请求。