接口規范 13. 文件上傳及管理相關接口

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":"h364",
                          "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 流編碼格式，例如視頻h364編碼，音頻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":"h364",
                      "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
  }