Class: Baidu::PCS::Client

Inherits:
Object
  • Object
show all
Includes:
Support::Request
Defined in:
lib/baidu/pcs/client.rb

Overview

Client 类封装实现了 Baidu PCS 的文件API，主要包括文件上传、下载、拷贝、删除、搜索、断点续传及缩略图等功能。

本文档多数内容取自 文件API列表，使用本 API 之前请先参考 Baidu PCS 开发指南，准备好相应环境。

Examples:

require 'baidu/pcs'

#全局配置，如已在其他地方配置过，可以忽略
Baidu.config do |c|
  # ...
  c.pcs_dir_name  = 'notes'  # 可选，如此处未做配置，那么实例化 Client 时必须指定 dir_name
  # ...
end

# 用户授权完成之后获取的 access token
access_token = 'xxxxxxxxxxxxxxxxxxxxxxxxx'
# 使用全局配置 pcs_dir_name 作为文件目录
client = Baidu::PCS::Client.new(access_token)
# 不使用全局配置 pcs_dir_name
# client = Baidu::PCS::Client.new(access_token, 'notes')

File.open('/opt/ubuntu-12.04.3-server-amd64.iso', 'r') do |f|
  result = client.upload(f)
  # result 为 Hash 实例，是直接根据 Baidu REST API 返回的 JSON 转换而来
  # 具体键值及意义可参看各方法中 “返回的原始 JSON” 部分
  puts result[:path]  # 输出上传后文件的保存路径
  puts result[:size]  # 输出上传的文件大小
  puts result[:md5]   # 输出上传的文件 md5 签名
end

Constant Summary

Constants included from Support::Request

Support::Request::MAX_REDIRECT_LIMIT

1 基本功能 collapse

2 高级功能 collapse

3 回收站 collapse

Instance Method Summary collapse

Methods included from Support::Request

#get, #post

Constructor Details

#initialize(access_token, dir_name = Baidu.pcs_dir_name) ⇒ Client #initialize(session, dir_name = Baidu.pcs_dir_name) ⇒ Client

创建一个 Baidu::PCS::Client 文件API 实例，通过此实例可以执行 文件API 调用

Overloads:

  • #initialize(access_token, dir_name = Baidu.pcs_dir_name) ⇒ Client

    Parameters:

    • access_token (String) —

      通过 Baidu OAuth API 获得的 Access Token

    • dir_name (String) (defaults to: Baidu.pcs_dir_name) —

      开通 PCS API 权限时，填写的文件目录。如果未设置此参数，则使用全局配置

  • #initialize(session, dir_name = Baidu.pcs_dir_name) ⇒ Client

    Parameters:

    • session (Baidu::Session) —

      通过 Baidu OAuth API 获得的 Session

    • dir_name (String) (defaults to: Baidu.pcs_dir_name) —

      开通 PCS API 权限时，填写的文件目录。如果未设置此参数，则使用全局配置

Raises:

  • (ArgumentError)

See Also:



50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/baidu/pcs/client.rb', line 50

def initialize(access_token_or_session, dir_name=Baidu.pcs_dir_name)
  @dir_name = dir_name
  @access_token = case access_token_or_session
                  when String then access_token_or_session
                  when Baidu::Session then access_token_or_session.access_token
                  end
  raise ArgumentError, 'dir_name must not be blank' if Util.blank? @dir_name
  raise ArgumentError, 'access_token must not be blank' if Util.blank? @access_token
  @site = Baidu::PCS::SITE
  @dir_path = "#{APPS_PATH_PREFIX}/#{@dir_name}"
end

Instance Method Details

#add_task(source_url, options = {}) ⇒ Hash

添加离线下载任务，实现单个文件离线下载

Examples:

返回的原始 JSON

{"task_id":432432432432432,"request_id":3372220525}

:task_id 任务ID号

Parameters:

  • source_url (String) —

    源文件的URL

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :save_path (String) —

    下载后的文件保存路径（相对于应用根目录）如果未指定则获取源文件的URL名称，如果获取失败则使用当前时间

  • :timeout (Fixnum) —

    下载超时时间

  • :expires (Fixnum) —

    请求失效时间，如果有，则会校验

  • :rate_limit (Fixnum) —

    下载限速，默认不限速

  • :callback (String) —

    下载完毕后的回调

Returns:

  • (Hash)

See Also:



756
757
758
759
760
761
762
763
764
765
766
767
 
# File 'lib/baidu/pcs/client.rb', line 756

def add_task(source_url, options={})
  query = { source_url: source_url }
  query[:timeout] = options.delete(:timeout) || 3600
  save_path = options.delete(:save_path)
  unless save_path
    save_path = URI(source_url).path.split('/').last || Time.now.localtime.to_s
  end
  save_path = build_path save_path, true
  query[:save_path] = save_path
  query.update options
  post "#{BASE_PATH}/services/cloud_dl", query.update(base_query 'add_task')
end

#cancel_task(task_id, expires = nil) ⇒ Hash

取消离线下载任务

Examples:

返回的原始 JSON

{"request_id":12394838223}

Parameters:

  • task_id (String) —

    要取消的任务ID号

  • expires (Fixnum) (defaults to: nil) —

    请求失效时间，如果有，则会校验

Returns:

  • (Hash)

See Also:



893
894
895
896
 
# File 'lib/baidu/pcs/client.rb', line 893

def cancel_task(task_id, expires=nil)
  query = { task_id: task_id, expires: expires }
  post "#{BASE_PATH}/services/cloud_dl", query.update(base_query 'cancel_task')
end

#copy(from, to) ⇒ Hash #copy(froms, tos) ⇒ Hash

单个或批量拷贝文件/目录

Examples:

返回的原始 JSON

{
  "extra": {
    "list": [
      {
        "to": "/apps/album/test2/6.jpg",
        "from": "/apps/album/test1/6.jpg"
      }
    ]
  },
  "request_id": 2298812844
}

:from 执行copy操作成功的源文件地址
:to   执行copy操作成功的目标文件地址

Overloads:

  • #copy(from, to) ⇒ Hash
    Note:

    move操作后，源文件被移动至目标地址；copy操作则会保留原文件

    拷贝单个文件/目录

    Parameters:

    • from (String) —

      源文件地址（包括文件名，相对于应用根目录）

    • to (String) —

      目标文件地址（包括文件名，相对于应用根目录）

    Returns:

    • (Hash) —

      如果copy操作执行成功，那么response会返回执行成功的from/to列表

    See Also:

  • #copy(froms, tos) ⇒ Hash
    Note:

    批量执行copy操作时，copy接口一次对请求参数中的每个from/to进行操作；执行失败就会退出，成功就继续，返回执行成功的from/to列表

    批量拷贝文件/目录

    Parameters:

    • froms (Array<String>) —

      源文件地址（相对于应用根目录）

    • tos (Array<String>) —

      目标文件地址（相对于应用根目录）

    Returns:

    • (Hash) —

      返回参数extra由list数组组成，list数组的两个元素分别是“from”和“to”，代表copy操作的源地址和目的地址

    See Also:

Returns:

  • (Hash) 


464
465
466
 
# File 'lib/baidu/pcs/client.rb', line 464

def copy(from, to)
  move_or_copy :copy, from, to
end

#create_super_file(block_list, path, overwrite = false) ⇒ Hash

合并分片文件

与分片文件上传 #upload_block 方法配合使用，可实现超大文件（>2G）上传，同时也可用于断点续传的场景

Examples:

返回的原始 JSON

{
  "path": "/apps/album/1.png",
  "size": 6844,
  "ctime": 1331197101,
  "mtime": 1331197101,
  "md5": "baa7c379639b74e9bf98c807498e1b64",
  "fs_id": 1548308694,
  "request_id": 4043313276
}

:path  该文件的绝对路径
:size  文件字节大小
:ctime 文件创建时间
:mtime 文件修改时间
:md5   文件的md5签名
:fs_id 文件在PCS的临时唯一标识ID

Parameters:

  • block_list (Array<String>) —

    数组，数组的取值为子文件内容的MD5；子文件至少2个，最多1024个

  • path (String) —

    上传文件路径（含上传的文件名称）

  • overwrite (Boolean) (defaults to: false) —

    true: 表示覆盖同名文件false: 表示生成文件副本并进行重命名，命名规则为“文件名_日期.后缀”

Returns:

  • (Hash)

Raises:

  • (ArgumentError)

See Also:



208
209
210
211
212
213
214
 
# File 'lib/baidu/pcs/client.rb', line 208

def create_super_file(block_list, path, overwrite=false)
  raise ArgumentError, 'block_list must be Array'           unless block_list.instance_of? Array
  raise ArgumentError, 'block_list size must be in 2..1024' unless block_list.length.between? 2, 1024
  query = build_upload_query 'createsuperfile', path, overwrite
  param = { block_list: block_list }
  post "#{BASE_PATH}/file", query, param: JSON.dump(param)
end

#delete(path) ⇒ Hash #delete(paths) ⇒ Hash

Note:

文件/目录删除后默认临时存放在回收站内，删除文件或目录的临时存放不占用用户的空间配额；存放有效期为10天，10天内可还原回原路径下，10天后则永久删除

单个或批量删除文件/目录

Examples:

返回的原始 JSON

{"request_id":4043312866}

Overloads:

  • #delete(path) ⇒ Hash

    删除单个文件/目录

    Parameters:

    • path (String) —

      需要删除的文件或者目录路径

    Returns:

    • (Hash)

    See Also:

  • #delete(paths) ⇒ Hash

    批量删除文件/目录

    Parameters:

    • paths (Array<String>) —

      需要删除的文件或者目录路径

    Returns:

    • (Hash)

    See Also:

Returns:

  • (Hash) 


488
489
490
 
# File 'lib/baidu/pcs/client.rb', line 488

def delete(path)
  meta_or_delete :delete, path
end

#diff(cursor = 'null') ⇒ Hash

Note:

本接口有数秒延迟，但保证返回结果为最终一致

文件增量更新操作查询

Examples:

返回的原始 JSON

{
  "entries": {
    "/apps/album/6.png": {
      "fs_id": 3858723392,
      "path": "/apps/album/6.png",
      "size": 4914,
      "isdir": 0,
      "isdelete": 0,
      "revision": 0,
      "md5": "6c37219ba0d3dfdfa95ff6912e2c42b9",
      "mtime": 1384526979,
      "ctime": 1384526979
    },
    "/apps/ablum/logo.png": {
      "fs_id": 3866920660,
      "path": "/apps/album/logo.png",
      "size": 4914,
      "isdir": 0,
      "isdelete": 0,
      "revision": 0,
      "md5": "6c37219ba0d3dfdfa95ff6912e2c42b9",
      "mtime": 1384486230,
      "ctime": 1384021638
    }
  },
  "has_more": true,
  "reset": true,
  "cursor": "MxKx6UPie%2F9WzBkwALPrVWQlyxlmK0LgHG8zutwXp8oyC%2F2BQ%3D%3D...",
  "request_id": 3355443548
}

:entries  k-v形式的列表，分为以下两种形式：
            1. key为path，value为path对应的meta值，meta中isdelete=0为更新操作
                 如果path为文件，则更新path对应的文件；
                 如果path为目录，则更新path对应的目录信息，但不更新path下的文件。
            2. key为path，value为path删除的meta信息，meta中“isdelete!=0”为删除操作
                 isdelete=1 该文件被永久删除；
                 isdelete=-1 该文件被放置进回收站；
                 如果path为文件，则删除该path对应的文件；
                 如果path为目录，则删除该path对应的目录和目录下的所有子目录和文件；
                 如果path在本地没有任何记录，则跳过本删除操作。
:has_more True：  本次调用diff接口，增量更新结果服务器端无法一次性返回，客户端可以立刻再调用一次diff接口获取剩余结果；
          False： 截止当前的增量更新结果已经全部返回，客户端可以等待一段时间（1-2分钟）之后再diff一次查看是否有更新。
:reset    True： 服务器通知客户端，服务器端将按时间排序从第一条开始向客户端返回一份完整的数据列表；
          False：返回上次请求返回cursor之后的增量更新结果。
:cursor   用于下一次调用diff接口时传入的断点参数。

Parameters:

  • cursor (String) (defaults to: 'null') —

    用于标记更新断点：首次调用cursor=null；非首次调用，使用最后一次调用diff接口的返回结果中的cursor

Returns:

  • (Hash)

See Also:



631
632
633
634
 
# File 'lib/baidu/pcs/client.rb', line 631

def diff(cursor='null')
  query = { cursor: cursor }
  get "#{BASE_PATH}/file", query.update(base_query 'diff')
end

#download(path, options = {}) ⇒ String #download(path, options = {}) {|segment| ... } ⇒ void

下载单个文件

Download 接口支持 HTTP 协议标准 range 定义，通过指定 range 的取值可以实现断点下载功能。

Examples:

下载文件第 101 - 200 字节之间的内容

File.open('logo.part2.png', 'w') do |f|
  f.write client.download('logo.png', begin: 100, end: 199)
end

Overloads:

  • #download(path, options = {}) ⇒ String
    Note:

    下载大文件会占用过多的内存, 请使用 block 方法 #download(path, &block)

    适合下载小文件，简单直接

    Examples:

    File.open('logo.png', 'w') do |f|
  f.write client.download('logo.png')
end

    Parameters:

    • path (String) —

      下载文件路径，路径相对于应用目录，从应用根目录起计算

    Options Hash (options):

    • :begin (Fixnum) —

      断点下载的开始字节索引

    • :end (Fixnum) —

      断点下载的结束字节索引

    Returns:

    • (String) —

      直接返回文件内容

  • #download(path, options = {}) {|segment| ... } ⇒ void

    This method returns an undefined value.

    针对下载大文件优化的方法

    Examples:

    File.open('ubuntu.iso', 'w') do |f|
  client.download('ubuntu-12.04.3-server-amd64.iso') do |segment|
    f.write segment
  end
end

    Parameters:

    • path (String) —

      下载文件路径，路径相对于应用目录，从应用根目录起计算

    Options Hash (options):

    • :begin (Fixnum) —

      断点下载的开始字节索引

    • :end (Fixnum) —

      断点下载的结束字节索引

    Yields:

    • (segment) —

      下载内容将以片段的方式提供

See Also:



254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/baidu/pcs/client.rb', line 254

def download(path, options={}, &block)
  site = Baidu::PCS::DOWNLOAD_SITE
  query = { path: build_path(path) }.update(base_query 'download')
  headers = if options[:begin] || options[:end]
              range = "#{options[:begin] || 0}-#{options[:end]}"
              { Range: "bytes=#{range}" }
            end
  if block_given?
    get "#{BASE_PATH}/file", query, site: site, headers: headers, &block
  else
    get "#{BASE_PATH}/file", query, site: site, headers: headers, raw: true
  end
end

#empty ⇒ Hash

清空回收站

Examples:

返回的原始 JSON

{"request_id":2307473052}

Returns:

  • (Hash)

See Also:



996
997
998
999
 
# File 'lib/baidu/pcs/client.rb', line 996

def empty
  query = { type: 'recycle' }
  post "#{BASE_PATH}/file", query.update(base_query 'delete')
end

#list(path, options = {}) ⇒ Hash

获取目录下的文件列表

Examples:

调用示例

client.list('apitest/movies', order: 'asc', by: 'time', limit: '2-10')

返回的原始 JSON

{
  "list": [
    {
      "fs_id": 703525418,
      "path": "/apps/Backups/apitest/movies/1.mkv",
      "ctime": 1377136220,
      "mtime": 1384493344,
      "md5": "6366d2a234e8139c63dab707ec4569c3",
      "size": 74818037,
      "isdir": 0
    }
  ],
  "request_id": 4043312670
}

:fs_id 文件或目录在PCS的临时唯一标识id
:path  文件或目录的绝对路径
:ctime 文件或目录的创建时间
:mtime 文件或目录的最后修改时间
:md5   文件的md5值
:size  文件大小（byte）
:isdir 是否是目录的标识符：“0”为文件，“1”为目录

Parameters:

  • path (String) —

    需要list的目录（相对于应用的根目录）

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :by (String) —

    排序字段，缺省根据文件名排序：time（修改时间），name（文件名），size（大小，注意目录无大小）

  • :order (String) —

    “asc”或“desc”，缺省采用降序排序：asc（升序），desc（降序）

  • :limit (String) —

    返回条目控制，参数格式为：n1-n2。返回结果集的[n1, n2)之间的条目，缺省返回所有条目；n1从0开始

Returns:

  • (Hash)

See Also:



382
383
384
385
386
387
388
 
# File 'lib/baidu/pcs/client.rb', line 382

def list(path, options={})
  query = { path: build_path(path) }
  query[:by]    = options[:by]    || 'name'
  query[:order] = options[:order] || 'desc'
  query[:limit] = options[:limit]
  get "#{BASE_PATH}/file", query.update(base_query 'list')
end

#list_task(options = {}) ⇒ Hash

查询离线下载任务列表

查询离线下载任务ID列表及任务信息

Examples:

不包含任务信息，返回的原始 JSON

{"task_info":[{"task_id":"26"}, {"task_id":"27"}],"total":"2","request_id":1283164486}

包含任务信息，返回的原始 JSON

{
  "task_info": [
    {
      "task_id": "26",
      "source_url": "https://example.com/1.dmg",
      "save_path": "/apps/album/1.dmg",
      "rate_limit": "100",
      "timeout": "10000",
      "callback": "",
      "status": "1",
      "create_time": "1347449048"
    }
  ],
  "total": "1",
  "request_id": 1285732167
}

Parameters:

  • options (Hash) (defaults to: {}) —

    皆为可选参数

Options Hash (options):

  • :start (Fixnum) —

    查询任务起始位置，默认为0

  • :limit (Fixnum) —

    设定返回任务数量，默认为10

  • :asc (Fixnum) —

    0：降序；1：升序；默认为0

  • :need_task_info (Fixnum) —

    是否需要返回任务信息：0：不需要；1：需要；默认为1

  • :status (Fixnum) —

    任务状态

  • :create_time (Fixnum) —

    任务创建时间，note：此参数似乎无效

  • :source_url (String) —

    源地址URL

  • :save_path (String) —

    文件保存路径（相对于应用根目录）

  • :expires (Fixnum) —

    请求失效时间，如果有，则会校验

Returns:

  • (Hash)

See Also:



879
880
881
882
 
# File 'lib/baidu/pcs/client.rb', line 879

def list_task(options={})
  query = options.dup
  post "#{BASE_PATH}/services/cloud_dl", query.update(base_query 'list_task')
end

#listrecycle(start = 0, limit = 1000) ⇒ Hash

查询回收站文件

获取回收站中的文件及目录列表

Examples:

返回的原始 JSON

{
  "list": [
    {
      "fs_id": 1579174,
      "path": "/apps/album/2.7z",
      "ctime": 1361934614,
      "mtime": 1361934625,
      "md5": "1131170ac11cfbec411a5e8d4e111769",
      "size": 10730431,
      "isdir": 0
    },
    {
      "fs_id": 304521061,
      "path": "/apps/album/3.7z",
      "ctime": 1361934605,
      "mtime": 1361934625,
      "md5": "9552bf5e5abdf962e2de94be243bec7c",
      "size": 4287611,
      "isdir": 0
    }
  ],
  "request_id": 3779302504
}

:fs_id 目录在PCS上的临时唯一标识
:path  该目录的绝对路径
:ctime 文件在服务器上的创建时间
:mtime 文件在服务器上的修改时间
:md5   分片MD5
:size  文件大小（byte）
:isdir 是否是目录的标识符：

Parameters:

  • start (Fixnum) (defaults to: 0) —

    返回条目的起始值

  • limit (Fixnum) (defaults to: 1000) —

    返回条目的长度

Returns:

  • (Hash)

See Also:



943
944
945
946
 
# File 'lib/baidu/pcs/client.rb', line 943

def listrecycle(start=0, limit=1000)
  query = { start:start, limit: limit }
  get "#{BASE_PATH}/file", query.update(base_query 'listrecycle')
end

#meta(path) ⇒ Hash #meta(paths) ⇒ Hash

单个或批量获取文件/目录的元信息

Examples:

返回的原始 JSON

{
  "list": [
    {
      "fs_id": 3528850315,
      "path": "/apps/album/music/hello",
      "ctime": 1331184269,
      "mtime": 1331184269,
      "block_list": [
        "59ca0efa9f5633cb0371bbc0355478d8"
      ],
      "size": 13,
      "isdir": 1
    }
  ],
  "request_id": 4043312678
}

:fs_id       文件或目录在PCS的临时唯一标识ID
:path        文件或目录的绝对路径
:ctime       文件或目录的创建时间
:mtime       文件或目录的最后修改时间
:block_list  文件所有分片的md5数组JSON字符串
:size        文件大小（byte）
:isdir       是否是目录的标识符：“0”为文件，“1”为目录
:ifhassubdir 是否含有子目录的标识符：“0”表示没有子目录，“1”表示有子目录

Overloads:

  • #meta(path) ⇒ Hash

    获取单个文件或目录的元信息

    Parameters:

    • path (String) —

      文件或目录路径，相对于应用根目录

    Returns:

    • (Hash)

    See Also:

  • #meta(paths) ⇒ Hash

    批量获取文件或目录的元信息

    Parameters:

    • paths (Array<String>) —

      文件或目录路径，相对于应用根目录

    Returns:

    • (Hash)

    See Also:

Returns:

  • (Hash) 


336
337
338
 
# File 'lib/baidu/pcs/client.rb', line 336

def meta(path)
  meta_or_delete :meta, path
end

#mkdir(path) ⇒ Hash

创建目录

为当前用户创建一个目录

Examples:

返回的原始 JSON

{
  "fs_id": 1636599174,
  "path": "/apps/yunfom/music",
  "ctime": 1331183814,
  "mtime": 1331183814,
  "request_id": 4043312656
}

:fs_id 目录在PCS的临时唯一标识id
:path  该目录的绝对路径
:ctime 目录创建时间
:mtime 目录修改时间

Parameters:

  • path (String) —

    需要创建的目录，相对于应用根目录

Returns:

  • (Hash)

See Also:



289
290
291
292
 
# File 'lib/baidu/pcs/client.rb', line 289

def mkdir(path)
  query = { path: build_path(path, true) }
  post "#{BASE_PATH}/file", query.update(base_query 'mkdir')
end

#move(from, to) ⇒ Hash #move(froms, tos) ⇒ Hash

单个或批量移动文件/目录

Examples:

返回的原始 JSON

{
  "extra": {
    "list": [
      {
        "to": "/apps/album/test2/2.jpg",
        "from": "/apps/album/test1/1.jpg"
      }
    ]
  },
  "request_id": 2298812844
}

:from 执行move操作成功的源文件地址
:to   执行move操作成功的目标文件地址

Overloads:

  • #move(from, to) ⇒ Hash
    Note:

    调用move接口时，目标文件的名称如果和源文件不相同，将会在move操作时对文件进行重命名

    移动单个文件/目录

    Parameters:

    • from (String) —

      源文件地址（包括文件名，相对于应用根目录）

    • to (String) —

      目标文件地址（包括文件名，相对于应用根目录）

    Returns:

    • (Hash) —

      如果move操作执行成功，那么response会返回执行成功的from/to列表

    See Also:

  • #move(froms, tos) ⇒ Hash
    Note:

    批量执行move操作时，move接口一次对请求参数中的每个from/to进行操作；执行失败就会退出，成功就继续，返回执行成功的from/to列表

    批量移动文件/目录

    Parameters:

    • froms (Array<String>) —

      源文件地址（包括文件名，相对于应用根目录）

    • tos (Array<String>) —

      目标文件地址（包括文件名，相对于应用根目录）

    Returns:

    • (Hash) —

      返回参数extra由list数组组成，list数组的两个元素分别是“from”和“to”，代表move操作的源地址和目的地址

    See Also:

Returns:

  • (Hash) 


425
426
427
 
# File 'lib/baidu/pcs/client.rb', line 425

def move(from, to)
  move_or_copy :move, from, to
end

#query_task(task_id, options = {}) ⇒ Hash #query_task(task_ids, options = {}) ⇒ Hash

精确查询离线下载任务

根据任务ID号，查询离线下载任务信息及进度信息

Examples:

查询进度信息，返回的原始 JSON

{
  "task_info": {
    "23998044": {
      "create_time": "1384703711",
      "start_time": "1384703711",
      "finish_time": "1384703717",
      "file_size": "0",
      "finished_size": "0",
      "task_name": "1.dmg",
      "save_path": "/apps/album/1.dmg",
      "source_url": "https://example.com/1.dmg",
      "status": "1",
      "result": 0
    }
  },
  "request_id": 631260401
}

:result 0查询成功，结果有效，1要查询的task_id不存在
:status 0下载成功，1下载进行中 2系统错误，3资源不存在，4下载超时，
        5资源存在但下载失败 6存储空间不足 7任务取消
:status status为0、1时，其余字段有效

查询任务信息，返回的原始 JSON

{
  "task_info": {
    "23654044": {
      "source_url": "https://example.com/1.dmg",
      "finished_size": "0",
      "save_path": "/apps/album/1.dmg",
      "rate_limit": "0",
      "timeout": "3600",
      "callback": "",
      "status": "7",
      "create_time": "1384703711",
      "task_name": "1.dmg",
      "od_type": "0",
      "result": 0
    }
  },
  "request_id": 689959608
}

:result      0查询成功，结果有效，1要查询的task_id不存在
:source_url  下载数据源地址
:save_path   下载完成后的存放地址
:status      0下载成功，1下载进行中 2系统错误，3资源不存在，4下载超时，
             5资源存在但下载失败 6存储空间不足 7目标地址数据已存在 8任务取消
:create_time 任务创建时间

Overloads:

  • #query_task(task_id, options = {}) ⇒ Hash

    Parameters:

    • task_id (String) —

      要查询的任务ID

    Returns:

    • (Hash)
  • #query_task(task_ids, options = {}) ⇒ Hash

    Parameters:

    • task_ids (Array<String>) —

      要查询的任务ID

    Returns:

    • (Hash)

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :op_type (Fixnum) —

    0：查任务信息；1：查进度信息；默认为1

  • :expires (Fixnum) —

    请求失效时间，如果有，则会校验

Returns:

  • (Hash)

See Also:



836
837
838
839
840
 
# File 'lib/baidu/pcs/client.rb', line 836

def query_task(task_ids, options={})
  task_ids = task_ids.join(',') if task_ids.is_a? Array
  query = { task_ids: task_ids }.update options
  post "#{BASE_PATH}/services/cloud_dl", query.update(base_query 'query_task')
end

#quota ⇒ Hash

空间配额信息

获取当前用户空间配额信息

Examples:

返回的原始 JSON

{"quota":15000000000,"used":5221166,"request_id":4043312634}

:quota 空间配额，单位为字节
:used  已使用空间大小，单位为字节

Returns:

  • (Hash)

See Also:



76
77
78
 
# File 'lib/baidu/pcs/client.rb', line 76

def quota
  get "#{BASE_PATH}/quota", base_query('info')
end

#rapid_upload(path, content_length, content_md5, slice_md5, content_crc32, overwrite = false) ⇒ Hash

Note:

被秒传文件必须大于256KB（即 256*1024 B）；校验段为文件的前256KB，秒传接口需要提供校验段的MD5。

Note:

非强一致接口，上传后请等待1秒后再读取

秒传文件

Examples:

返回的原始 JSON

{
  "path": "/apps/album/1.jpg",
  "size": 372121,
  "ctime": 1234567890,
  "mtime": 1234567890,
  "md5": "cb123afcc12453543ef",
  "fs_id": 12345,
  "isdir": 0,
  "request_id": 12314124
}
:path  秒传文件的绝对路径
:size  秒传文件的字节大小
:ctime 秒传文件的创建时间。
:mtime 秒传文件的修改时间
:md5   秒传文件的md5签名
:fs_id 秒传文件在PCS的唯一标识ID
:isdir  “0”文件 “1”目录

Parameters:

  • path (String) —

    上传文件的全路径名（相对于应用根目录）

  • content_length (Fixnum) —

    待秒传的文件长度

  • content_md5 (String) —

    待秒传的文件的MD5

  • slice_md5 (String) —

    待秒传文件校验段的MD5

  • content_crc32 (String) —

    待秒传文件校验段的MD5

  • overwrite (Boolean) (defaults to: false) —

    true: 表示覆盖同名文件，false：表示生成文件副本并进行重命名，命名规则为“文件名_日期.后缀”

Returns:

  • (Hash)

See Also:



729
730
731
732
733
734
735
736
737
738
 
# File 'lib/baidu/pcs/client.rb', line 729

def rapid_upload(path, content_length, content_md5, slice_md5, content_crc32, overwrite=false)
  path = build_path path, true
  query = { :path             => path,
            :'content-length' => content_length,
            :'content-md5'    => content_md5,
            :'slice-md5'      => slice_md5,
            :'content-crc32'  => content_crc32 }
  query[:ondup] = overwrite ? 'overwrite' : 'newcopy'
  post "#{BASE_PATH}/file", query.update(base_query 'rapidupload')
end

#restore(fs_id) ⇒ Hash #restore(fs_ids) ⇒ Hash

Note:

非强一致接口，调用后请sleep 1秒读取

单个或批量还原文件/目录

Overloads:

  • #restore(fs_id) ⇒ Hash

    还原单个文件或目录

    Examples:

    还原成功返回的原始 JSON

    {"extra":{"list":[{"fs_id":"1356099017"}]},"request_id":3775323016}

    Parameters:

    • fs_id (String) —

      所还原的文件或目录在PCS的临时唯一标识ID

    Returns:

    • (Hash)

    See Also:

  • #restore(fs_ids) ⇒ Hash

    批量还原文件或目录

    Examples:

    全部还原成功返回的原始 JSON

    {"extra":{"list":[{"fs_id":"3275514389"}]},"request_id":3859098573}

    部分还原成功返回的原始 JSON

    {"error_code":31078,"error_msg":"invalid fs id","extra":{"list":[{"fs_id":"706533300"}]},"request_id":3825218191}

    全部还原失败返回的原始 JSON

    {"error_code":31078,"error_msg":"invalid fs id","extra":{"list":[]},"request_id":805400333}

    Parameters:

    • fs_ids (Array<String>) —

      所还原的文件或目录在PCS的临时唯一标识ID的数组

    Returns:

    • (Hash)

    See Also:

Returns:

  • (Hash) 


976
977
978
979
980
981
982
983
984
985
986
987
 
# File 'lib/baidu/pcs/client.rb', line 976

def restore(fs_ids)
  query = case fs_ids
          when String
            { fs_id: fs_ids }
          when Array
            fs_ids = fs_ids.map { |id| { fs_id: id } }
            { param: JSON.dump({ list: fs_ids }) }
          else
            raise ArgumentError, 'fs_id(s) must be kind of String or Array'
          end
  post "#{BASE_PATH}/file", query.update(base_query 'restore')
end

#search(path, wd, re = false) ⇒ Hash

Note:

不支持查找目录

按文件名搜索文件

Examples:

返回的原始 JSON

{
  "list": [
    {
      "fs_id": 3528850315,
      "path": "/apps/album/music/hello",
      "ctime": 1331184269,
      "mtime": 1331184269,
      "block_list": [
        "59ca0efa9f5633cb0371bbc0355478d8"
      ],
      "size": 13,
      "isdir": 0
    }
  ],
  "request_id": 4043312670
}

:fs_id 目录在PCS的临时唯一标识ID。
:path  该目录的绝对路径。
:ctime 文件服务器创建时间。
:mtime 文件服务器修改时间。
:md5   文件的md5值。
:size  文件大小（byte）。
:isdir 是否是目录的标识符：“0”为文件，“1”为目录

Parameters:

  • path (String) —

    需要检索的目录（相对于应用根目录）

  • wd (String) —

    关键词

  • re (Boolean) (defaults to: false) —

    是否递归：true 表示递归，false 表示不递归

Returns:

  • (Hash)

See Also:



526
527
528
529
530
 
# File 'lib/baidu/pcs/client.rb', line 526

def search(path, wd, re=false)
  path = build_path path
  query = { path: path, wd: wd, re: (re ? 1 : 0) }
  get "#{BASE_PATH}/file", query.update(base_query 'search')
end

#stream_list(type, options = {}) ⇒ Hash

获取流式文件列表

以视频、音频、图片及文档四种类型的视图获取所创建应用程序下的文件列表。

Examples:

返回的原始 JSON

{
  "total": 13,
  "start": 0,
  "limit": 1,
  "list": [
    {
      "path": "/apps/album/1.jpg",
      "size": 372121,
      "ctime": 1234567890,
      "mtime": 1234567890,
      "md5": "cb123afcc12453543ef",
      "fs_id": 12345,
      "isdir": 0
    }
  ]
}

:total      文件总数
:start      起始数
:limit      获取数
:path       获取流式文件的绝对路径
:block_list 分片MD5列表
:size       流式文件的文件大小（byte）
:mtime      流式文件在服务器上的修改时间
:ctime      流式文件在服务器上的创建时间
:fs_id      流式文件在PCS中的唯一标识ID
:isdir      “0”文件，“1”目录

Parameters:

  • type (String) —

    类型分为video、audio、image及doc四种

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :start (Fixnum) —

    返回条目控制起始值，默认为0

  • :limit (Fixnum) —

    返回条目控制长度，默认为1000

  • :filter_path (String) —

    需要过滤的前缀路径，如：/apps/album

Returns:

  • (Hash)

See Also:



693
694
695
696
 
# File 'lib/baidu/pcs/client.rb', line 693

def stream_list(type, options={})
  query = { type: type }.update options
  get "#{BASE_PATH}/stream", query.update(base_query 'list')
end

#streaming(path, type, &block) ⇒ String

Note:

目前这个接口支持的源文件格式如下：m3u8/m3u/asf/avi/flv/gif/mkv/mov/mp4/m4a/3gp/3g2/mj2/mpeg/ts/rm/rmvb/webm

视频转码

对视频文件进行转码，实现实时观看视频功能。可下载支持HLS/M3U8的媒体云播放器SDK配合使用。

Parameters:

  • path (String) —

    需要下载的视频文件路径，需含源文件的文件名（相对于应用根目录）

  • type (String) —

    目前支持以下格式：M3U8_320_240、M3U8_480_224、M3U8_480_360、M3U8_640_480和M3U8_854_480

Returns:

  • (String) —

    直接返回文件内容（在线播放的 URL 地址清单）

See Also:



644
645
646
647
648
649
650
651
652
 
# File 'lib/baidu/pcs/client.rb', line 644

def streaming(path, type, &block)
  path = build_path path
  query = { path: path, type: type }.update base_query('streaming')
  if block_given?
    get "#{BASE_PATH}/file", query, &block
  else
    get "#{BASE_PATH}/file", query, raw: true
  end
end

#thumbnail(path, width, height, quality = 100) ⇒ String #thumbnail(path, width, height, quality = 100) {|segment| ... } ⇒ void

Note:

限制条件：原图大小(0, 10M]；原图类型: jpg、jpeg、bmp、gif、png；目标图类型和原图的类型有关；例如：原图是gif图片，则缩略后也为gif图片

获取指定图片文件的缩略图

Overloads:

  • #thumbnail(path, width, height, quality = 100) ⇒ String

    Returns 缩略图文件内容.

    Examples:

    File.open('logo_120.png', 'w') do |f|
  f.write client.thumbnail('logo.png', 120, 120)
end

    Returns:

    • (String) —

      缩略图文件内容

  • #thumbnail(path, width, height, quality = 100) {|segment| ... } ⇒ void

    This method returns an undefined value.

    使用 block 方式，减少内存占用率

    Examples:

    File.open('logo_1600.png', 'w') do |f|
  client.thumbnail('logo.png', 1600, 1600) do |segment|
    f.write segment
  end
end

    Yields:

    • (segment) —

      内容将以片段的方式提供

Parameters:

  • path (String) —

    源图片的路径（相对于应用根目录）

  • width (Fixnum) —

    指定缩略图的宽度，取值范围为(0,1600]

  • height (Fixnum) —

    指定缩略图的高度，取值范围为(0,1600]

  • quality (Fixnum) (defaults to: 100) —

    缩略图的质量，默认为“100”，取值范围(0,100]

See Also:



565
566
567
568
569
570
571
572
573
 
# File 'lib/baidu/pcs/client.rb', line 565

def thumbnail(path, width, height, quality=100, &block)
  path = build_path path
  query = { path: path, width: width, height: height, quality: quality }.update base_query('generate')
  if block_given?
    get "#{BASE_PATH}/thumbnail", query, &block
  else
    get "#{BASE_PATH}/thumbnail", query, raw: true
  end
end

#upload(file, options = {}) ⇒ Hash

Note:

百度PCS服务目前支持最大2G的单个文件上传

Note:

文件大小超过 128MB 时，自动启用文件分块上传；如果不想启用文件分块上传，可以通过 block_upload: false 来关闭

上传单个文件

Examples:

File.open('/opt/ubuntu-12.04.3-server-amd64.iso', 'r') do |f|
  c.upload(f, block_upload: true)
end

返回的原始 JSON

{
  "fs_id": 3916799999,
  "path": "/apps/album/1.png",
  "ctime": 1384493574,
  "mtime": 1384493574,
  "md5": "6c37219ba0d3dfdfa95ff6912e2c42b9",
  "size": 4914,
  "request_id": 3036629135
}

:fs_id 文件在PCS的临时唯一标识ID
:path  该文件的绝对路径
:ctime 文件创建时间
:mtime 文件修改时间
:md5   文件的md5签名
:size  文件字节大小

Parameters:

  • file (File) —

    待上传的文件

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :path (String) —

    上传文件路径，含上传的文件名称（相对于应用根目录），默认为 file 的文件名

  • :overwrite (Boolean) —

    true: 表示覆盖同名文件，false: 表示生成文件副本并进行重命名，命名规则为“文件名_日期.后缀”，默认为 false

  • :block_upload (Boolean) —

    对文件分块上传，仅当 file 大小超过 8MB 时，此设置有效；分块大小取决于文件大小，4GB 以下文件分块大小为 4MB

  • :retry_times (Fixnum) —

    分块上传时，出错自动重试次数，默认 5

  • :retry_waitsec (Fixnum) —

    分块上传时，出错自动重试暂停秒数，默认 30

Returns:

  • (Hash)

Raises:

  • (ArgumentError)

See Also:



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/baidu/pcs/client.rb', line 123

def upload(file, options={})
  raise ArgumentError, 'file must be an instance of File' unless file.instance_of? File
  path = options[:path] || File.basename(file)
  size = file.size
  if (options[:block_upload] && size >= 4*1024*1024*2) ||  # at least 2 blocks
     (options[:block_upload].nil? && size >= 128*1024*1024)
    block_size = 4*1024*1024
    while block_size * 1024 < size  # at most 1024 blocks1
      block_size *= 2
    end
    offset, block_list = 0, []
    max_retry_times = options[:retry_times]   || 5
    retry_waitsec   = options[:retry_waitsec] || 30
    loop do
      with_retries(max_retry_times, retry_waitsec) do
        rest = upload_block IO.binread(file, block_size, offset)
        block_list << rest[:md5]
      end
      offset += block_size
      break if offset >= size
    end
    with_retries(max_retry_times, retry_waitsec) do
      create_super_file block_list, path, options[:overwrite]
    end
  else
    raise IOError, 'file is too large (larger than 2G)' if size > 2*1024*1024*1024
    query = build_upload_query 'upload', path, options[:overwrite]
    post "#{BASE_PATH}/file", query, { file: file }, site: Baidu::PCS::UPLOAD_SITE
  end
end

#upload_block(data) ⇒ Hash

Note:

百度PCS服务支持每次直接上传最大2G的单个文件。如需支持上传超大文件（>2G），则可以通过组合调用分片文件上传方法和合并分片文件方法实现：

首先，将超大文件分割为2G以内的单文件，并调用 {#upload_block} 将分片文件依次上传；
其次，调用 {#create_super_file} ，完成分片文件的重组。

除此之外，如果应用中需要支持断点续传的功能，也可以通过分片上传文件并调用 #create_super_file 的方式实现。

上传分片文件

Examples:

返回的原始 JSON

{"md5":"a7619410bca74850f985e488c9a0d51e","request_id":3238563823}

:md5 上传内容的md5签名

Parameters:

  • data (String) —

    上传的内容

Returns:

  • (Hash)

See Also:



172
173
174
175
 
# File 'lib/baidu/pcs/client.rb', line 172

def upload_block(data)
  query = build_upload_query 'upload', nil, nil, true
  post "#{BASE_PATH}/file", query, { file: StringIO.new(data) }, site: Baidu::PCS::UPLOAD_SITE
end