-
Notifications
You must be signed in to change notification settings - Fork 346
API调用说明
chatop2020 edited this page Jan 17, 2021
·
5 revisions
- AKStream采用http restful 风格的WebApi接口提供给第三方应用对接集成
- AKStream的http接口有鉴权认证功能，在调用AKStream WebApi接口时需要在http header上携带AccessKey，AccessKey的值被配置在配置文件中，具体详见配置文件章节介绍
- 在http header上携带AccessKey的方式是KeyValue形式的如下所示： AccessKey=047I4WS1-U51UBO6W-1J4BT21P-MF17IT99-92J8WIHU-944Q4KIW
- AccessKey会在首次运行并生成配置文件时自动生成，你也可以修改AccessKey的值，使之符合你的需求
- AKStream的WebApi调用约定的方法有HttpGet和HttpPost两种，在向AKStream传递普通一般参数时（如基础类型参数）一般采用HttpGet方法，在向AKStream传递复杂参数时（如对象）一般采用HttpPost方法，具体接口采用了什么方式详见每个接口的具体说明
- AKStream将接口按照功能集中程度分为以下几类
-
- AKStreamKeeper 这是专门针对AKStreamKeeper的API接口
-
- MediaServer 专门针对流媒体控制的API接口
-
- RecordPlan 针对录制计划模板的API接口
-
- SipServer 针对GB28181 Sip信令网关的API接口
-
- SystemService 针对系统层面的API接口
-
- WebHook 针对ZLMediaKit的回调而准备的API接口
- AKStream还提供了Swagger API接口Web在线调试工具，可以通过http://ip:port/swagger 来访问它
- 为了保障开发阶段的高效，AKStream的编译模式是Debug的情况下，不需要通过AccessKey鉴权认证；Release模式下则需要AccessKey鉴权认证
- AKStream的WebApi中额外约定如下
-
- DateTime的格式化标准为 yyyy-MM-dd HH:mm:ss
-
- 涉及到枚举类型，可以传枚举的String值也可以传int值
- AKStream的API调用异常有三种类型
- 1.AKStream所知异常
- 2.WebServer异常
- 3.系统内部错误
- 所有AKStream所知异常都会被包装成一个异常结构，结构如下
/// <summary>
/// 返回状态结构
/// </summary>
[Serializable]
public class ResponseStruct
{
private ErrorNumber _code;
private string _message = null!;
private string? _exceptMessage = null!;
private string? _exceptStackTrace = null!;
/// <summary>
/// 返回结构体构造
/// </summary>
/// <param name="code"></param>
/// <param name="message"></param>
public ResponseStruct(ErrorNumber code, string message)
{
Code = code;
Message = message;
}
public ResponseStruct()
{
}
/// <summary>
/// 状态代码
/// </summary>
[JsonConverter(typeof(StringEnumConverter))]
public ErrorNumber Code
{
get => _code;
set => _code = value;
}
/// <summary>
/// 状态描述
/// </summary>
public string Message
{
get => _message;
set => _message = value;
}
/// <summary>
/// 异常的Message
/// </summary>
public string? ExceptMessage
{
get => _exceptMessage;
set => _exceptMessage = value;
}
/// <summary>
/// 异常的StackTrace
/// </summary>
public string? ExceptStackTrace
{
get => _exceptStackTrace;
set => _exceptStackTrace = value;
}
}- 此异常类在namespace LibCommon下
- 异常类主要包含了以下四个内容
private ErrorNumber _code;
private string _message = null!;
private string? _exceptMessage = null!;
private string? _exceptStackTrace = null!;- Code为错误代码，此字段是一个枚举类型，其中0=None表示没有错误（异常），其他值都是有异常情况，具体见后面的附录1
- Message是对Code的具体描述
- ExceptMessage,ExceptStackTrace 这两个字段是在发生Exception时保存Exception的message和堆栈信息，以帮助快速排错
- 如类似以下报错信息
{
"Code": "MediaServer_InstanceIsNull",
"Message": "流媒体服务实例为空，请先创建流媒体服务实例"
}- WebServer异常一般是因为传参不符合要求造成的，比如需要传的参数没有传，传参类型不符等，这些异常由.net core的全局异常拦截器进行拦截并向应用报错
- 如类似以下报错
{
"errors": {
"pageSize": [//这里指出了传参的问题
"Invalid property identifier character: {. Path 'pageSize', line 5, position 4."
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "|4fdb4241-4b91dd00b7b63532."
}- 所有正常调用，http 状态码均为200
- 所有异常调用，http 状态码均不是200,有可能是400也有可能是500
- 可能在极个别情况下产生 http 状态码为500的情况，这类情况一般是AKStream代码流程中没有考虑到的问题造成WebServer的内部错误，这类错误的发生，虽然是致命的，但不会造成AKStream崩溃
- ErrorCode的结构
public enum ErrorNumber : int
{
None = 0, //成功
Sys_GetMacAddressExcept = -1000, //获取Mac地址异常
Sys_GetIpAddressExcept = -1001, //获取IP地址异常
Sys_JsonWriteExcept = -1002, //Json写入异常
Sys_JsonReadExcept = -1003, //Json读取异常
Sys_ConfigDirNotExists = -1004, //配置文件目录不存在
Sys_ConfigFileNotExists = -1005, //配置文件不存在
Sys_ParamsNotEnough = -1006, //参数不足
Sys_ParamsIsNotRight = -1007, //参数不正确
Sys_WebApi_Except = -1008, //WebApi异常
Sys_ConfigNotReady = -1009, //配置文件没有就绪
Sys_DataBaseNotReady = -1010, //数据库没有就绪
Sys_NetworkPortExcept = -1011, //端口不可用
Sys_DiskInfoExcept = -1012, //磁盘不可用
Sys_UrlExcept = -1013, //参数中URL异常
Sys_ReadIniFileExcept = -1014, //读取ini文件异常
Sys_WriteIniFileExcept = -1015, //写入ini文件异常
Sys_SocketPortForRtpExcept = -1016, //查找可用rtp端口时异常，可能已无可用端口
Sys_SpecifiedFileNotExists = -1017, //指定文件不存在
Sys_InvalidAccessKey = -1018, //访问密钥失效
Sys_AKStreamKeeperNotRunning = -1019, //AKStreamKeeper流媒体服务器治理程序没有运行
Sys_DataBaseLimited = -1020, //数据库操作受限，请检查相关参数，如分页查询时每页不能超过10000行
Sys_DB_VideoChannelNotExists = -1021, //数据库中不存在指定音视频通道
Sys_DataBaseExcept = -1022, //数据库执行异常
Sys_DB_VideoChannelAlRedayExists = -1023, //数据库中已经存在指定音视频通道
Sys_DB_RecordNotExists = -1024, //数据库中指定记录不存在
Sys_VideoChannelNotActived = -1025, //音视频通实例没有激活
Sys_HttpClientTimeout = -1026, //http客户端请求超时
Sys_DB_RecordPlanNotExists = -1027, //录制计划不存在
Sys_RecordPlanTimeLimitExcept = -1028, //录制计划时间间隔异常
Sys_DB_RecordPlanAlreadyExists = -1029, //数据库中指定录制计划已经存在
Sys_DvrCutMergeTimeLimit = -1030, //裁剪时间限制，超过120分钟任务不允许执行
Sys_DvrCutMergeFileNotFound = -1031, //时间周期内没有找到相关视频文件
Sys_DvrCutProcessQueueLimit = -1032, //处理队列已满，请稍后再试
Sip_StartExcept = -2000, //启动Sip服务异常
Sip_StopExcept = -2001, //停止Sip服务异常
Sip_Except_DisposeSipDevice = -2002, //Sip网关内部异常(销毁Sip设备时)
Sip_Except_RegisterSipDevice = -2003, //Sip网关内部异常(注册Sip设备时)
Sip_ChannelNotExists = -2004, //Sip音视频通道不存在
Sip_DeviceNotExists = -2005, //Sip设备不存在
Sip_OperationNotAllowed = -2006, //该设备类型下不允许这个操作
Sip_DeInviteExcept = -2007, //结束推流时异常
Sip_InviteExcept = -2008, //推流时异常
Sip_SendMessageExcept = -2009, //发送sip消息时异常
Sip_AlredayPushStream = -2010, //sip通道已经在推流状态
Sip_NotOnPushStream = -2011, //Sip通道没有在推流状态
Sip_Channel_StatusExcept = -2012, //Sip通道设备状态异常
Sip_VideoLiveExcept = -2013, //Sip通道推流请求异常
MediaServer_WebApiExcept = -3000, //访问流媒体服务器WebApi时异常
MediaServer_WebApiDataExcept = -3001, //访问流媒体服务器WebApi接口返回数据异常
MediaServer_TimeExcept = -3002, //服务器时间异常，建议同步
MediaServer_BinNotFound = -3003, //流媒体服务器可执行文件不存在
MediaServer_ConfigNotFound = -3004, //流媒体服务器配置文件不存在，建议手工运行一次流媒体服务器使其自动生成配置文件模板
MediaServer_InstanceIsNull = -3005, //流媒体服务实例为空，请先创建流媒体服务实例
MediaServer_StartUpExcept = -3006, //启动流媒体服务器失败
MediaServer_ShutdownExcept = -3007, //停止流媒体服务器失败
MediaServer_RestartExcept = -3008, //重启流媒体服务器失败
MediaServer_ReloadExcept = -3009, //流媒体服务器配置热加载失败
MediaServer_NotRunning = -3010, //流媒体服务器没有运行
MediaServer_OpenRtpPortExcept = -3011, //申请rtp端口失败，申请端口可能已经存在
MediaServer_WaitWebHookTimeOut = -3012, //等待流媒体服务器回调时超时
MediaServer_StreamTypeExcept = -3013, //流类型不正确
MediaServer_GetStreamTypeExcept = -3014, //指定拉流方法不正确
MediaServer_VideoSrcExcept = -3015, //源流地址异常
Other = -6000 //其他异常
}