接口规范 13. 文件上传及管理相关接口

Posted 2020-10-22

13 文件上传及管理相关接口

这组接口实现视频资源的上传及管理，为视频转码和发布提供支持。
上传的服务器上的视频文件，经过转码发布后形成可以对外播出的在线视频资源。
本小节描述文件上传和管理的接口，转码接口在下一章节说明。

• 13.1.文件上传接口
  用途
  通过HTTP POST协议上传视频文件。文件上传接口是一个特殊的接口，接口位置与其他接口有差异。
  上传协议采用HTTP POST协议，提交form的数据采用multipart/form-data编码（enctype="multipart/form-data"）。
  这里有详细的规范（对于Web开发，通常您无需阅读这个文档）：
  rfc1867 http://www.ietf.org/rfc/rfc1867.txt
  对于采用Web页面上传的应用，采用典型的form提交上传文件即可，数据提交地址设为本接口地址。
  请求
  http://host/upload?app=g3_video&sub_path=&file_name=&token=abcd&field_name=field_abcd
  其中:
  http://host/upload 是上传位置，保持不变。host替换成实际的流媒体服务器IP地址或域名。
  参数：
  app=g3_video,表示上传的是视频文件，要保持不变。
  sub_path表示上传到哪个子目录下，如果省略表示上传到用户根目录下。
  file_name上传文件要在服务器上保存的文件名，如果跟上传文件名一样，则省略。该参数提供了一个上传文件在服务器上重新命名的机会。中文件名要采用UTF-8编码。
  token意义跟其他接口一样。

  响应

  {
  "code":0
  }

• 13.2.查询文件列表接口
  用途
  查询服务器上的某个目录下的视频文件列表。
  请求
  fileMgr/?request=list_files&subpath=&page=1
  sub_path 文件存放的子目录，对应上传文件时的sub_path参数。如果省略，则查询用户根目录下的文件。
  page页码，该接口支持分页查询，分页信息在返回数据中。
  响应

  {
  "code":0,
  "data":{
      "page":"1",
      "page_size":"50",
      "pages":"1",
      "total":"1",
      "count":1,
      "items":[{
              "filename":"案例视频8.mp4",
              "mtime":"2018-01-12 12:43",
              "size":"3153954",
              "charset":"UTF-8",
              "timestamp":1515732410,
              "is_media":1,
              "duration":98,
              "bitrate":255309,
              "stream_number":2,
              "timestamp_m":1515397208,
              "streams":[
                          {
                          "index":"0",
                          "type":"video",
                          "codec":"h264",
                          "pic_width":640,
                          "pic_height":352,
                          "bitrate":208980,
                          "duration":98,
                          "pix_fmt":"yuv420p",
                          "frame_rate":"28/1"
                          },
                          {
                          "index":"1",
                          "type":"audio",
                          "codec":"aac",
                          "lan":"und",
                          "channels":1,
                          "bitrate":43970,
                          "duration":98,
                          "sample_rate":44100
                          }
                        ]
              }]
      }
  }

  返回数据包含分页信息，在文件量较大时要按页查询。
  items元素包含0或多个文件信息。streams元素是该文件包含的音视频流信息，一个多媒体文件会包含1到多个音视频流
  filename 文件名，返回的文件名总是采用UTF-8编码
  charset 文件名在服务器上的字符集编码，省略表示是UTF-8编码。如果为非UTF-8编码，在后续的接口中请将该属性带入
  mtime 文件最后的修改时间
  size 文件大小，单位字节
  duration 文件播出时长，单位秒
  bitrate 综合码率，单位bps
  stream_number 文件包含的音视频流总数
  streams元素：
  streams包含0或多个音视频流，属性：
  index 流的索引编号，在转码接口中，在多语言音频流的情况下，可以通过传入音频流索引号选择指定的音频流。
  type 视频或音频，对应 video 或 audio
  codec 流编码格式，例如视频h264编码，音频aac编码等
  bitrate 流的比特率，单位bps
  pix_fmt 视频帧格式
  frame_rate 帧率
  pic_width 视频画幅宽度
  pic_height 视频画幅高度
  lan 音频语言信息，语言编码缩写
  channels 音频声道数
  sample_rate音频采样率

• 13.3.查询文件目录接口
  用途
  查询服务器上的文件目录。
  请求
  fileMgr/?request=list_dirs&subpath=
  sub_path 文件存放的子目录，如果省略，则查询用户根目录下的文件目录。
  响应

  {
  "code":0,
  "data":{
      "count":2,
      "items":[
          {
              "filename":"auto",
              "mtime":"2018-01-06 16:36",
              "size":"4096",
              "timestamp":0,
              "auto_transcode":1
          },
          {
              "filename":"audio",
              "mtime":"2017-12-27 18:09",
              "size":"4096",
              "timestamp":0,
              "auto_transcode":0
          }]
   }
  }

  items元素包含0或多个目录信息。
  filename 目录名
  mtime 最后修改时间
  auto_transcode 是否针对该目录设置了自动转码任务，1表示有自动转码任务

• 13.4.查询文件信息接口
  用途
  查询服务器上的某个视频文件的信息。
  请求
  fileMgr/?request=get_file&filename=案例视频8.mp4&charset=UTF-8
  filename 文件名，如果在子目录中，应当包含完整的相对目录，如 mypath/myfile.mp4，文件名采用UTF-8编码
  charset 文件名在服务器上的实际字符集编码，在查询文件列表接口中有返回。
  响应

  {
  "code":0,
  "data":{
      "count":1,
      "items":[
          {
              "filename":"/案例视频8.mp4",
              "charset":"UTF-8",
              "mtime":1515732213,
              "size":3153954,
              "timestamp":1516941450,
              "is_media":1,
              "duration":98,
              "bitrate":255309,
              "stream_number":2,
              "timestamp_m":1515397208,
              "streams":[
                  {
                      "index":"0",
                      "type":"video",
                      "codec":"h264",
                      "pic_width":640,
                      "pic_height":352,
                      "bitrate":208980,
                      "duration":98,
                      "pix_fmt":"yuv420p",
                      "frame_rate":"28/1"
                  },
                  {
                      "index":"1",
                      "type":"audio",
                      "codec":"aac",
                      "lan":"und",
                      "channels":1,
                      "bitrate":43970,
                      "duration":98,
                      "sample_rate":44100
                  }
              ]
          }
      ]
  }
  }

  返回一个文件的信息，包含多媒体信息。
  返回数据的文件信息的描述与查询文件列表接口中对文件信息的描述相同。

• 13.5.删除文件接口
  用途
  删除服务器上的文件。
  请求
  fileMgr/?request=remove&filename=myvideo.mp4&charset=ASCII
  filename 文件名，如果在子目录中，应当包含完整的相对目录，如 mypath/myfile.mp4，文件名采用UTF-8编码
  charset 文件名在服务器上的实际字符集编码，在查询文件列表接口中有返回。
  响应

  {
  "code":0
  }