收录系统对外接口v1 4 1

收录系统（Record）对外接口规范(V1.0)2017年6月目 录第1章 调用说明31.1 概述31.2 调用方式31.2.1 通讯协议31.2.2 请求方法31.2.3 字符编码5第2章 接口说明52.1 任务提交52.1.1 功能描述52.1.2 接口地址52.1.3 请求参数62.1.4 返回参数142.2 任务查询142.2.1 功能描述142.2.2 接口地址152.2.3 请求参数152.2.4 返回参数162.3 任务反馈172.3.1 功能描述172.3.2 接口地址172.3.3 请求参数182.3.4 返回参数20页26第1章 调用说明1.1 概述欢迎使用Record收录系统。用户可以使用本文档介绍的 API 对Record收录系统进行相关操作。1.2 调用方式1.2.1 通讯协议通过 HTTP 或 HTTPS 通道进行请求通信。1.2.2 请求方法所有请求通过HTTP POST方法发送请求。所有请求参数/数据放在JSON串中。下面的例子中展示了一个HTTP POST请求是如何发送JSON数据的。POST /xxx/xxx.shtml HTTP/1.1Host: 02:8180Connection: keep-aliveContent-Length: 1802Accept: application/json, text/javascript, */*; q=0.01Origin: 02:8180X-Requested-With: XMLHttpRequestUser-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36Content-Type: application/json; charset=UTF-8Referer: http:/xxx/port/xxx.htmlAccept-Encoding: gzip, deflateAccept-Language: zh-CN,zh;q=0.8Cookie: xxx systemId: cms, systemTaskId: here is taskid , taskName: test eg, dealFlag: add, groupId: TranscodeGroup, taskInfo: taskID: c00001, taskDate: 2017-01-11, channel: ID: CCTV1, name: CCTV1 , program: sequenceNumber: 0, startDateTime: 2017-01-11T15:01:00, playTimeLength: 60, fragmentLength: 60 , inputInfo: profileName: 1.2M, resourceInfo: URL: muct:/:5003/live.ts, videoPID: 69, audioPID: 68 , outputInfo: mediaPath: mediaPath, xmlPath: xmlPath , createUser: user, stateReportAddress: callbackurl1.2.3 字符编码请求及返回结果都使用 UTF-8 字符集进行编码。第2章 接口说明2.1 任务提交2.1.1 功能描述第三方系统向收录系统提交收录任务。提交的任务所收录的节目时间必须是当天以后或者当天的任务。2.1.2 接口地址地址： /framework/recorder/taskSubmit.shtml方式：post2.1.3 请求参数属性含义类型说明必填systemId系统IDString(32)第三方系统Id，由收录系统事先给定是systemTaskId业务任务IDString(32)任务唯一Id是taskName任务名称String(255)否dealFlag操作String(10)枚举值 add-添加任务 delete-删除任务 update-更新任务是priority优先级Int(1)取值：1-10 默认为1 否groupId组idString(32)Mcp中配置的节点组标识，由mcp事先定义否taskInfo任务描述信息Json详细定义参看recordtask.xsd文件是createTime创建时间String(32)日期字串: 例如：2017-01-11T15:01:00，注意”T”隔开日期与实践否createUser创建人String(32)否taskType任务String(32)固定值：“RecorderType指收录任务是stateReportAddress回调地址String(200)任务状态汇报地址，绝对路径，以http:/开头的合法url字串或者空字串，为空表示不接收任务结果汇报。是说明：MCP系统是指任务管控系统。请求示例： systemId: cms第三方系统id, systemTaskId: task001【唯一的任务Id】, taskName: CCTV1收录计划【收录计划名】, dealFlag: add【添加任务】, groupId: TranscodeGroup【任务分组，事先再MCP里定义】, taskInfo: taskID: task001【唯一任务Id与systemTaskId相同】, taskDate: 2017-01-11【收录日期】, channel: ID: CCTV1【收录频道,由字母或数字组成，不能有其它字符。可能用于拼写文件名，不可随意填写】, name: CCTV1【频道名称】 , program: sequenceNumber: 0【节目序号0】, startDateTime: 2017-01-11T15:01:00【收录开始时间】, playTimeLength: 60【收录时长，单位：秒】, fragmentLength: 60【分片时长，单位：秒，和收录时长相等则表示不分片】 , sequenceNumber: 1【节目序号1】, startDateTime: 2017-01-11T15:03:00, playTimeLength: 60, fragmentLength: 60, inputInfo: profileName: 1.2M【收录码流字串，由字母、数字、点号组成。可能用于拼写文件名，不可随意填写】, resourceInfo: URL: muct:/:5003/live.ts【ts流地址，注意端口】, videoPID: 69【视频Pid，重要。错误则收录失败】, audioPID: 68【音频Pid，重要，错误则收录失败】 ， profileName: 0.5M【0.5M码流的ts流，必须是同一视频出的不同码率的流，否则收录失败】, resourceInfo: URL: muct:/:5004/live.ts【ts流地址，和上一路端口不同】, videoPID: 69, audioPID: 68 , outputInfo: mediaPath: cmsRecord%(channel)_%(profile)%(date)_%(time).mp4【视频文件存放地址和文件名，参看注解1】, xmlPath: cmsRecord%(channel)_%(profile)%(date)_%(time).xml【生成的xml，暂不支持】 , createUser: username【任务创建者，用户名】, stateReportAddress: /cms/callback.do【收录平台会把收录结果汇报到这个地址，必须是绝对路径的url】注意事项：注解1：收录任务生成文件可用的适配符号：提供以下特殊字符来为你生成特殊收录文件路径或者文件名。这些适配符号可以任意组合。收录系统在生成文件时会把他们替换成实际值。%(channel) - 频道%( profile) - profilename%( date) -当前日期%(time) -当前时间例如：record%(channel)%(profile)-%(date)-%(time).mp4,可能生成的文件为：recordcctv11.2M-2017-1-1-1130.mp3注解2：nas路径和windows文件路径目前收录系统支持nas路径和windows文件路径，如果要把文件存在nas里，则需要按nas规范填写地址。例如：record 表示主机下record共享目录。注意主机ip地址或者域名前加双斜杠。注解3：任务变更任务变更时，任务的ID参数： systemTaskId和taskID保持不变。dealFlag参数设置为：update”。收录变更分为以下2种情况：n 收录任务未开始变更条件：由于收录任务有一个处理，下发过程。因此收录任务变更要有10分钟提前量。所以第一条子任务（序号为0的子任务）开始时间=当前时间+10分钟。外围系统变更单下发：外围系统提交整张任务单。子任务序号从0开始，序号连续，子任务开始时间正序。收录系统处理：收录系统会用新单子整体替换旧单子，下发给收录节点。n 收录任务已经开始变更条件：收录任务已开始，且任务未完成。在这种情况下，只能变更当前时间+10分钟以后的子任务，以前的子任务不能变更。外围系统变更单下发：外围系统提交整张任务单。子任务序号从0开始，序号连续，子任务开始时间正序。只能变更当前时间+10分钟以后的子任务，以前的子任务不变。收录源不可更改。收录系统处理：收录系统以服务器时间为准，合并新旧任务单。合并方法为：删除旧单子子任务中开始时间=当前时间+10分钟的子任务。添加新单子子任务中开始时间=当前时间+10分钟的子任务。合成后的新单子下发给收录节点。任务变更示例： systemId: cms第三方系统id, systemTaskId: task001【唯一的任务Id，保持不变】, taskName: CCTV1收录计划【收录计划名】, dealFlag: update【变更任务】, groupId: TranscodeGroup【任务分组，事先再MCP里定义】, taskInfo: taskID: task001【唯一任务Id 保持不变】, taskDate: 2017-01-11【收录日期】, channel: ID: CCTV1【收录频道,由字母或数字组成，不能有其它字符。可能用于拼写文件名，不可随意填写】, name: CCTV1【频道名称】 , program: sequenceNumber: 0, startDateTime: 2017-01-11T15:04:00【收录开始时间】, playTimeLength: 60【收录时长，单位：秒】, fragmentLength: 60【分片时长，单位：秒，和收录时长相等则表示不分片】 , sequenceNumber: 1, startDateTime: 2017-01-11T15:06:00, playTimeLength: 60, fragmentLength: 60, inputInfo: #收录任务开始后，收录源不可更改 profileName: 1.2M【收录码流字串，由字母、数字、点号组成。可能用于拼写文件名，不可随意填写】, resourceInfo: URL: muct:/:5003/live.ts【ts流地址，注意端口】, videoPID: 69【视频Pid，重要。错误则收录失败】, audioPID: 68【音频Pid，重要，错误则收录失败】 ， profileName: 0.5M【0.5M码流的ts流，必须是同一视频出的不同码率的流，否则收录失败】, resourceInfo: URL: muct:/:5004/live.ts【ts流地址，和上一路端口不同】, videoPID: 69, audioPID: 68 , outputInfo: mediaPath: cmsRecord%(channel)_%(profile)%(date)_%(time).mp4【视频文件存放地址和文件名，参看注解1】, xmlPath: cmsRecord%(channel)_%(profile)%(date)_%(time).xml【生成的xml，暂时保留，路径和mediaPath相同，后缀变成xml】 , createUser: username【任务创建者，用户名】, stateReportAddress: /cms/callback.do【收录平台会把收录结果汇报到这个地址，必须是绝对路径的url。如果不想回传，请填写“noneedcallback”字串】注解5：删除任务当收录任务需要停止，以便腾出资源时，可下发删除任务。任务的ID参数： systemTaskId和taskID保持不变。dealFlag参数设置为：update”。任务删除后，收录系统会把收录任务置为“delete”状态。只有任务状态处于未开始或者正在执行时才可以做“删除任务”操作。任务删除示例： systemId: cms第三方系统id, systemTaskId: task001【唯一的任务Id，保持不变】, taskName: CCTV1收录计划【收录计划名】, dealFlag: delete【变更任务】, groupId: TranscodeGroup【任务分组，事先再MCP里定义】, taskInfo: , createUser: username【任务创建者，用户名】, stateReportAddress: /cms/callback.do【收录平台会把收录结果汇报到这个地址，必须是绝对路径的url】2.1.4 返回参数属性含义类型说明必填state任务接受状态int0:接受成功 1:接受失败是desc描述String否返回示例 state: 0【接收任务状态】, desc: 【错误提示，任务接收成功，则为空】2.2 任务查询2.2.1 功能描述第三方系统查询收录任务执行情况。2.2.2 接口地址地址：/framework/recorder/getTaskProgress.shtml方式：post2.2.3 请求参数属性含义类型说明必填systemId系统IDString(64)第三方系统Id是systemTaskIds任务IDString可以多个任务id，用逗号隔开，例如：100001,100002,100004是请求参数示例： systemTaskIds: taskid1,taskid2,taskid3,taskid4【任务id用逗号隔开】, systemId: cms【第三方系统Id】2.2.4 返回参数属性含义类型说明必填ip接收ipString是state查询状态String0成功1失败是tasks任务进度信息集合集合里包含的对象是map否systemTaskId外围系统任务IDString是taskState任务处理状态String0成功1处理中2失败是retryCount重发次数Int任务失败之后mcp会自动重发1次是taskProgress任务进度Float(3,1)进度百分数，例如：89.5表示进度89.5%否nodeIp节点IPString执行任务节点Ip地址是desc任务信息String每个任务错误信息否desc描述string任务查询错误信息否返回参数示例： state: 0, tasks: nodeIp: , desc: null, retryCount: 0, taskProgress: 100, systemTaskId: pmSubTask_20170704114942763, taskState: 0 , nodeIp: , desc: null, retryCount: 0, taskProgress: 100, systemTaskId: pmSubTask_20170704114942334, taskState: 0 2.3 任务反馈2.3.1 功能描述收录系统向第三方系统反馈任务执行结果。此接口由第三方系统实现。当收录系统完成一个收录任务中的一个节目（program）收录时，会主动调用反馈接口，向第三方系统反馈子任务收录结果。每次只反馈其中一个子任务结果。所有当主任务有收录多个节目时，每个节目的收录结果都会反馈。2.3.2 接口地址地址：由第三方在调用任务下发接口时提交，即callback值。方法：post2.3.3 请求参数属性含义类型说明必填MediaRecorderTask收录任务Object是taskId任务IdString主任务Id是taskState任务状态String主任务状态： 0-成功 1-进行中 2-失败是taskProgress任务进度Float=100的数是taskResults子任务结果Object是profileProfile名String收录流码率名称是programIndex节目序号Int是state节目收录状态String子任务状态：0-成功 1-进行中 2-失败是url收录文件地址String如果 hasSlice=Y，则为空否hasSlice节目是否再分片StringY-有分片 N-不再分片是info节目收录错误信息String如果收录错误，返回错误信息否Slices节目分片信息组 数组否Slice分片收录信息Object否index分片序号int否url分片收录文件地址String否state分片收录状态String0-成功 1-进行中 2-失败否info错误信息String如果收录错误，返回错误信息否请求示例： MediaRecorderTask: taskId: ABC0001【任务Id】, taskState: 1【主任务状态0-成功 1-进行中 2-失败 4-部分失败】, taskProgress: 0.792361【主任务进度】, taskResults: profile: 4000k【流的码率】, programIndex: 1【节目序号1】, state: 2【子任务状态 0-成 2-失败】, hasSlice: Y【是否有分片 Y-有 N-无】, Slices: Slice: index: 0【分片序号】, url: E: ctvitChannel_4000k2016-12-26_15-09-38.mp4【收录文件地址】, state: 2【收录状态 0-成功 2-失败】, info: 错误信息【错误信息】 , index: 1, url: E: ctvitChannel_4000k2016-12-26_15-09-48.mp4, state: 0, info: 没有ts流 , index: 2, url: E: ctvitChannel_4000k2016-12-26_15-09-57.mp4, state: 0, info: 没有ts流 属性含义类型说明必填pkGUID资源包IdString是2.3.4 返回参数属性含义类型说明必填state结果接收状态int0:接收成功 1:接收失败是desc描述String否返回示例 state: 0【接收任务状态】, desc: 【错误提示，任务接收成功，则为空】2.4 任务详细信息查询2.4.1 功能描述第三方系统通过此接口查询某个收录任务详细信息。任务详细信息包括：总任务信息、返回收到文件的子任务（program）的收录状态、收录进度、文件地址、文件时长、错误信息等。子任务收录状态为：0-成功 2-失败 3待执行 4-收录数据不完整，有丢包。本接口只返回状态0、4两种的子任务。2.4.2 接口地址地址：/framework/recorder/getTaskDetail.shtml方式：post2.4.3 请求参数属性含义类型说明必填systemId系统IDString(64)第三方系统Id是systemTaskId任务IDString任务Id是startTime开始时间datetime子任务开始时间.日期+时间。例如：2017-12-04 12:31:02 .否endTime结束时间datetime子任务结束时间.日期+时间。例如：2017-12-04 12:31:02 .否示例： systemId: cms【第三方系统Id】, systemTaskId: taskid1【任务id】, startTime: 2017-02-03 12:02:12 【开始时间,可为空】, endTime: 2017-02-03 12:20:12 【结束时间,可为空】2.4.4 返回参数属性含义类型说明必填systemTaskId任务IdString任务Id是state查询状态String0有效查询1失败查询是taskProgress总任务进度float例如：98.5否taskState总任务状态String0-成功 1-进行中 2-失败 4-部分成功 3-待执行否nodeIp执行任务的node的ipStringnode系统ip地址否programs子任务信息集合集合里包含的对象是map,可为空数组是programIndex子任务序号String从0开始是programState子任务处理状态String0成功 4数据不完整是startTime子任务收录开始时间datetime格式：2017-02-05 07:12:03是programDuration子任务时长（秒）int单位：秒是fileSimpleName收录生成的文件名String 例如：xxx.mp4是fileSize收录文件实际大小long单位：Btye是fileDuration收录文件实际时长long单位：毫秒是subTaskErrorInfo任务错误信息String子任务错误信息否desc描述string任务查询错误信息否示例： systemTaskId: taskId01【收录任务Id】, state: 0【查询状态:0有效查询 1失败查询】, taskProgress : 50.0【总任务进度】, taskState : 1【总任务状态】, nodeIp : 【执行任务的node Ip】, desc: 【查询任务错误描述】, programs: programIndex: 0【子任务序号】, programState: 0【子任务状态：0成功 2失败 4数据不完整】, startTime: 2017-02-03 02:15:00, programDuration: 60, fileSimpleName: 2017-09-08_16-07-47-07212071.mp4【收录文件路径】, fileSize: 12000, fileDuration: 60000 , programIndex: 0【子任务序号】, programState: 4【子任务状态：0成功 2失败 4数据不完整】, startTime: 2017-02-03 02:20:00, programDuration: 60, fileSimpleName: 2017-09-08_16-07-47-07212072.mp4【收录文件路径】, fileSize: 12000, fileDuration: 58