Upgrade Nuget
|
# Remoting接口文档
Remoting通信支持RPC和HTTP两种架构，[参阅这里](https://github.com/NewLifeX/NewLife.Remoting)，使用完全相同的接口出入参格式，用法一致，不再分开表述。
参考：
[简易远程消息协议](https://newlifex.com/core/srmp)
[**ApiHttpClient客户端**](https://newlifex.com/core/api_http)
## 基础知识
针对常见基础功能，封装了客户端与服务端实现，例如登录、注销和心跳等。
### 主要部件
**ClientBase**是客户端基类，推荐应用客户端类继承该基类，仅需简单配置即可使用；
**BaseDeviceController**是服务端控制器基类，推荐应用服务端控制器类继承该基类，也可以直接拷贝该基类代码来使用；
### 功能设置
默认实现的功能比较多，都集中在ClientBase基类内部，需要通过Features来设置启用哪些功能。一般写在应用客户端构造函数内。例如ZeroIoT中的HttpDevice构造函数：
```c#
public HttpDevice(ClientSetting setting) : base(setting)
{
// 设置动作，开启下行通知
Features = Features.Login | Features.Logout | Features.Ping | Features.Notify | Features.Upgrade;
SetActions("Device/");
Actions[Features.CommandReply] = "Thing/ServiceReply";
}
```
不仅通过Features设置了需要开启的功能，还通过SetActions指定了服务端接口的路径前缀（如Device/Login）。其中CommandReply接口比较特殊，独立设置其路径。
又如星尘节点客户端StarClient，星尘代理StarAgent和码神工具CrazyCoder都通过它连接星尘服务端节点管理平台，提供登录、注销、心跳、更新和指令下发等功能：
```c#
public StarClient()
{
Features = Features.Login | Features.Logout | Features.Ping | Features.Upgrade | Features.Notify | Features.CommandReply | Features.PostEvent;
SetActions("Node/");
Log = XTrace.Log;
}
```
再来看看星尘应用客户端AppClient，所有通过nuget引入Stardust的应用，都通过AppClient连接星尘服务端应用管理平台，提供登录、心跳、指令下发、监控数据上报、服务注册与消费等功能：
```c#
public AppClient()
{
Features = Features.Login | Features.Ping | Features.Notify | Features.CommandReply;
SetActions("App/");
Log = XTrace.Log;
}
```
### 客户端属性
ClientBase客户端主要属性。
| 名称 | 类型 | 说明 |
| ---------------- | ----------------------------- | ------------------------------------------------------------ |
| Server | String | 服务端地址。支持http/tcp/udp，支持客户端负载均衡，多地址逗号分隔 |
| Code | String | 编码。设备编码DeviceCode，或应用标识AppId |
| Secret | String | 密钥。设备密钥DeviceSecret，或应用密钥AppSecret |
| PasswordProvider | IPasswordProvider | 密码提供者。用于保护密码传输，默认提供者为空，密码将明文传输。 |
| OnLogined | <LoginEventArgs> | 登录完成后触发 |
| Received | <CommandEventArgs> | 收到下行命令时触发 |
| Status | LoginStatus | 登录状态 |
| Delay | Int32 | 请求到服务端并返回的延迟时间。单位ms |
| Span | TimeSpan | 时间差。服务器时间减去客户端时间 |
| MaxFails | Int32 | 最大失败数。心跳上报失败时进入失败队列，并稍候重试。重试超过该数时，新的数据将被抛弃，默认1440次，约24小时 |
| Commands | IDictionary<String, Delegate> | 命令集合。注册到客户端的命令与委托 |
| Features | Features | 客户端功能特性。默认登录注销心跳，可添加更新等 |
| Actions | IDictionary<Features, String> | 各功能的动作集合。记录每一种功能所对应的动作接口路径。 |
| JsonHost | IJsonHost | Json主机。提供序列化能力 |
| Setting | IClientSetting | 客户端设置 |
### 异步登录
客户端刚启动时，网络可能尚未就绪。此时直接调用Login就会抛出异常。ClientBase提供了Open方法，内部通过定时器不断检测网络，并在网络恢复时调用Login，直到成功为止。
有可能客户端网络没有问题，而服务端网络有问题，或者中途网络无法连通，或者甚至服务端还没有启动。Open内部的定时登录机制同样有效，直到登录成功为止。
## 接口详解
各个接口按需选用，都不是必须实现。如果没有特殊说明，各接口都是客户端向服务端发起请求，并等待服务端响应。
各个应用接口前缀可能不同，下文使用变量表示，例如`/{Prefix}/Login`在ZeroIoT中就是`/Device/Login`。该前缀由前文功能设置中的SetActions指定，并保存在Actions属性中。少数场景可能会修改接口名，例如`/Device/Register`，具体以Actions中为准。
各接口请求中，非必要字段可以选填，应尽量提供相关信息，以支持服务端各项功能。
各接口默认使用POST请求方式，参数经Json序列化放在Body中。如果使用GET请求，则参数拼接在Url中。
登录获取令牌后，所有接口请求均需要在请求头中携带令牌，HTTP请求头：`Authentication: Bearer {token}` 。
正常响应格式如下（code==0），下文响应表格仅列出data部分：
```json
{
"code": 0,
"data": { /* 各接口响应表格字段 */ }
}
```
异常响应格式如下（code!=0），data部分为异常字符串：
```json
{
"code": 401,
"data": "未登录"
}
```
### 登录Login
**地址**：`POST /{Prefix}/Login`
**功能**：向服务端提交编码和密钥，服务端验证通过后颁发令牌给客户端，后续所有接口调用带上令牌作为身份标识。
**说明**：登录请求一般还提供ClientId、版本信息、IP地址与MAC地址、唯一机器码、本地时间等信息，服务端接口能验证客户端身份，并颁发令牌。服务端找不到关联身份时，也可以根据相关信息注册一个身份，并通过登录响应返回编码和原始明文密钥。
**请求**（ILoginRequest）：
| 名字 | 类型 | 必要 | 说明 |
| -------- | ------ | :--: | --------------------------------------- |
| Code | String | √ | 编码 |
| Secret | String | √ | 密钥 |
| ClientId | String | √ | 实例。应用可能多实例部署，ip@proccessid |
| Version | String | | 版本 |
| Compile | Int64 | | 编译时间。UTC毫秒 |
| IP | String | | 本地IP地址 |
| Macs | String | | MAC地址 |
| UUID | String | | 唯一标识 |
| Time | Int64 | | 本地时间。UTC毫秒 |
**响应**（ILoginResponse）：
| 名字 | 类型 | 必要 | 说明 |
| ---------- | ------ | :--: | ------------------------------------------------- |
| Code | String | | 编码。平台下发新编码，仅用于自动注册 |
| Secret | String | | 密钥。平台下发新密钥，仅用于自动注册 |
| Token | String | √ | 令牌。后续所有接口调用均需要在请求头携带该令牌。 |
| Expire | Int32 | | 令牌过期时间。单位秒。默认7200秒 |
| Time | Int64 | | 本地时间。客户端用于计算延迟，Unix毫秒（UTC） |
| ServerTime | Int64 | | 服务器时间。客户端用于计算时间差，Unix毫秒（UTC） |
### 注销Logout
**地址**：`GET /{Prefix}/Logout`
**功能**：向服务端申请，注销当前令牌。
**请求**：
| 名字 | 类型 | 必要 | 说明 |
| -------- | ------ | :--: | --------------------------------------- |
| reason | String | | 原因 |
**响应**（ILogoutResponse）：
| 名字 | 类型 | 必要 | 说明 |
| ----- | ------ | :--: | -------------------- |
| Token | String | | 令牌。清空令牌后返回 |
### 心跳Ping
**地址**：`POST /{Prefix}/Ping
**功能**：定时向服务端发送心跳，主要目的是链路保活，同时上报客户端的性能数据。
**请求**（IPingRequest）：
| 名字 | 类型 | 必要 | 说明 |
| ------------------ | ------ | :--: | ------------------------------------------ |
| Time | Int64 | √ | 本地UTC时间。Unix毫秒（UTC） |
| Memory | UInt64 | | 内存大小 |
| AvailableMemory | UInt64 | | 可用内存大小 |
| TotalSize | UInt64 | | 磁盘大小。应用所在盘 |
| AvailableFreeSpace | UInt64 | | 磁盘可用空间。应用所在盘 |
| CpuRate | Double | | CPU占用率 |
| Temperature | Double | | 温度 |
| Battery | Double | | 电量 |
| Signal | Int32 | | 信号强度。WiFi/4G |
| UplinkSpeed | UInt64 | | 上行速度。网络发送速度，字节每秒 |
| DownlinkSpeed | UInt64 | | 下行速度。网络接收速度，字节每秒 |
| IP | String | | 本地IP地址。随着网卡变动，可能改变 |
| Uptime | Int32 | | 开机时间，单位s |
| Delay | Int32 | | 延迟。请求到服务端并返回的延迟时间。单位ms |
**响应**（IPingResponse）：
| 名字 | 类型 | 必要 | 说明 |
| ---------- | -------------- | :--: | ------------------------------------------------- |
| Time | Int64 | √ | 本地时间。客户端用于计算延迟，Unix毫秒（UTC） |
| ServerTime | Int64 | √ | 服务器时间。客户端用于计算时间差，Unix毫秒（UTC） |
| Period | Int32 | | 心跳周期。单位秒 |
| Token | String | | 令牌。现有令牌即将过期时，颁发新的令牌 |
| Commands | CommandModel[] | | 下发命令 |
| NewServer | String | | 新服务器地址。用于服务器迁移 |
CommandModel：
```c#
/// <summary>命令模型</summary>
public class CommandModel
{
/// <summary>序号</summary>
public Int64 Id { get; set; }
/// <summary>命令</summary>
public String Command { get; set; } = null!;
/// <summary>参数</summary>
public String? Argument { get; set; }
/// <summary>开始执行时间。用于提前下发指令后延期执行，暂时不支持取消</summary>
/// <remarks>
/// 使用UTC时间传输，客户端转本地时间，避免时区差异。
/// 有些序列化框架可能不支持带时区信息的序列化，因此约定使用UTC时间传输。
/// </remarks>
public DateTime StartTime { get; set; }
/// <summary>过期时间。未指定时表示不限制</summary>
/// <remarks>
/// 使用UTC时间传输，客户端转本地时间，避免时区差异。
/// 有些序列化框架可能不支持带时区信息的序列化，因此约定使用UTC时间传输。
/// </remarks>
public DateTime Expire { get; set; }
/// <summary>跟踪标识。传输traceParent，用于建立全局调用链，便于查找问题</summary>
public String? TraceId { get; set; }
}
```
### 升级更新Upgrade
**地址**：`GET /{Prefix}/Upgrade`
**功能**：定时请求服务端更新接口，获取满足当前客户端条件的升级更新信息，并根据信息执行自动更新流程。
**请求**：
| 名字 | 类型 | 必要 | 说明 |
| ------- | ------ | :--: | -------- |
| channel | String | | 更新通道 |
**响应**（IUpgradeInfo）：
| 名字 | 类型 | 必要 | 说明 |
| ----- | ------ | :--: | -------------------- |
| Token | String | √ | 令牌。清空令牌后返回 |
### 下行通知Notify
**地址**：`WS /{Prefix}/Notify`
**功能**：向服务端建立WebSocket连接，服务端通过下行链路（HTTP是WebSocket，RPC是TCP/UDP）向客户端发送命令，指示客户端即时执行特定流程。
**方向**：服务端->客户端
**下发**（ILoginRequest）：
| 名字 | 类型 | 必要 | 说明 |
| -------- | ------ | :--: | --------------------------------------- |
| Code | String | √ | 编码 |
| Secret | String | √ | 密钥 |
| ClientId | String | √ | 实例。应用可能多实例部署，ip@proccessid |
| Version | String | | 版本 |
| Compile | Int64 | | 编译时间。UTC毫秒 |
| IP | String | | 本地IP地址 |
| Macs | String | | MAC地址 |
| UUID | String | | 唯一标识 |
| Time | Int64 | | 本地时间。UTC毫秒 |
### 命令响应CommandReply
**地址**：`POST /{Prefix}/CommandReply`
**功能**：客户端执行完成服务端下发的命令后，通过CommandReply接口向上汇报执行状态与结果。
**请求**（ILoginRequest）：
| 名字 | 类型 | 必要 | 说明 |
| -------- | ------ | :--: | --------------------------------------- |
| Code | String | √ | 编码 |
| Secret | String | √ | 密钥 |
| ClientId | String | √ | 实例。应用可能多实例部署，ip@proccessid |
| Version | String | | 版本 |
| Compile | Int64 | | 编译时间。UTC毫秒 |
| IP | String | | 本地IP地址 |
| Macs | String | | MAC地址 |
| UUID | String | | 唯一标识 |
| Time | Int64 | | 本地时间。UTC毫秒 |
**响应**：
| 名字 | 类型 | 必要 | 说明 |
| ---------- | ------ | :--: | ------------------------------------------------- |
| Code | String | | 编码。平台下发新编码，仅用于自动注册 |
| Secret | String | | 密钥。平台下发新密钥，仅用于自动注册 |
| Token | String | √ | 令牌。后续所有接口调用均需要在请求头携带该令牌。 |
| Expire | Int32 | | 令牌过期时间。单位秒。默认7200秒 |
| Time | Int64 | | 本地时间。客户端用于计算延迟，Unix毫秒（UTC） |
| ServerTime | Int64 | | 服务器时间。客户端用于计算时间差，Unix毫秒（UTC） |
### 上报事件PostEvent
**地址**：`POST /{Prefix}/PostEvent`
功能：客户端批量上报带有时间戳的事件日志。
**请求**（ILoginRequest）：
| 名字 | 类型 | 必要 | 说明 |
| -------- | ------ | :--: | --------------------------------------- |
| Code | String | √ | 编码 |
| Secret | String | √ | 密钥 |
| ClientId | String | √ | 实例。应用可能多实例部署，ip@proccessid |
| Version | String | | 版本 |
| Compile | Int64 | | 编译时间。UTC毫秒 |
| IP | String | | 本地IP地址 |
| Macs | String | | MAC地址 |
| UUID | String | | 唯一标识 |
| Time | Int64 | | 本地时间。UTC毫秒 |
**响应**：
| 名字 | 类型 | 必要 | 说明 |
| ---------- | ------ | :--: | ------------------------------------------------- |
| Code | String | | 编码。平台下发新编码，仅用于自动注册 |
| Secret | String | | 密钥。平台下发新密钥，仅用于自动注册 |
| Token | String | √ | 令牌。后续所有接口调用均需要在请求头携带该令牌。 |
| Expire | Int32 | | 令牌过期时间。单位秒。默认7200秒 |
| Time | Int64 | | 本地时间。客户端用于计算延迟，Unix毫秒（UTC） |
| ServerTime | Int64 | | 服务器时间。客户端用于计算时间差，Unix毫秒（UTC） |
|