# SDK 文档 又拍云 php sdk 中所有封装的接口，均通过 `Upyun\Upyun` 类封装，后续新版本也会保持 该类方法向下兼容，sdk 中其他类及其方法不保证兼容性。如果有使用疑问欢迎提 [issues](https://github.com/upyun/php-sdk/issues) ## 方法列表 * [Upyun](#upyun) * [__construct](#__construct) * [setConfig](#setconfig) 更新服务配置 * [write](#write) 上传一个文件到又拍云存储 * [read](#read) 读取云存储文件/目录内容 * [has](#has) 判断文件是否存在于又拍云存储 * [info](#info) 获取云存储文件/目录的基本信息 * [getMimetype](#getmimetype) 获取云存储文件类型 * [delete](#delete) 删除文件或者目录 * [createDir](#createdir) 创建目录 * [deleteDir](#deletedir) 删除文件或者目录 * [usage](#usage) 获取目录下存储使用量 * [purge](#purge) 刷新缓存 * [process](#process) 异步云处理 * [queryProcessStatus](#queryprocessstatus) 查询异步云处理任务进度 * [queryProcessResult](#queryprocessresult) 查询异步云处理任务结果 ## Upyun `Upyun\Upyun` 类实现了又拍云云存储和云处理的所有接口，通过该类可以实现文件上传、下载；图片视频等多媒体资源云处理。 本文档中，提到的"服务"是指又拍云文件加速回又拍云源类型的服务（即原先的存储类服务）。 * 命名空间: `\Upyun\Upyun` ### __construct Upyun constructor. ```php Upyun::__construct( \Upyun\Config $config ) ``` **参数列表:** - **\Upyun\Config** `$config` 服务配置 --- ### setConfig 更新服务配置 ```php Upyun::setConfig( \Upyun\Config $config ) ``` 当需要操作的新的服务时，使用该方法传入新的服务配置即可 **参数列表:** - **\Upyun\Config** `$config` 服务配置 --- ### write 上传一个文件到又拍云存储 ```php Upyun::write( string $path, string|resource $content, array $params = array(), boolean $withAsyncProcess = false ) ``` 上传的文件格式支持文件流或者字符串方式上传。除简单的文件上传外，针对多媒体资源（图片、音视频），还可以设置同步/异步预处理多媒体资源，例如：图片的裁剪缩放，音视频的转码截图等等众多又拍云强大的云处理功能 **参数列表:** - **string** `$path` 被上传的文件在又拍云存储服务中保存的路径 - **string|resource** `$content` 被上传的文件内容（字符串），或者打开该文件获得的文件句柄（文件流）。当上传本地大文件时，推荐使用文件流的方式上传 - **array** `$params` 上传文件时，附加的自定义参数。支持 Content-MD5 Content-Type Content-Secret 等，详见 [上传参数](http://docs.upyun.com/api/rest_api/#_2)，例如： - 设置文件[保护秘钥](http://docs.upyun.com/api/rest_api/#Content-Secret) `write($path, $content, array('Content-Secret' => 'my-secret'))`； - 添加[文件元信息](http://docs.upyun.com/api/rest_api/#metadata) `write($path, $content, array('X-Upyun-Meta-Foo' => 'bar'))` - [图片同步预处理](http://docs.upyun.com/cloud/image/#_5) `write($path, $content, array('x-gmkerl-thumb' => '/format/png'))` - **boolean** `$withAsyncProcess` 默认为 `false`，当上传图片或者音视频资源时，可以设置该参数为 `true`，开启图片音视频的[异步处理功能](http://docs.upyun.com/api/form_api/#_6) ，例如： ``` // 以下参数会将新上传的图片，再异步生成另一份 png 格式的图片，原图不受影响 write($path, $content, array( 'apps' => array( array( 'name' => 'thumb', //异步图片处理任务 'x-gmkerl-thumb' => '/format/png', // 格式化图片为 png 格式 'save_as': '/iamge/png/new.png', // 处理成功后的图片保存路径 'notify_url': 'http://your.notify.url' // 异步任务完成后的回调地址 ) ) ), true); ``` **返回值：** 若文件是图片则返回图片基本信息，如：`array('x-upyun-width' => 123, 'x-upyun-height' => 50, 'x-upyun-frames' => 1, 'x-upyun-file-type' => 'JPEG')`，否则返回空数组。当使用异步预处理功能时，返回结果为布尔值，成功为 `true`。 --- ### read 读取云存储文件/目录内容 ```php Upyun::read( string $path, resource $saveHandler = NULL, array $params = array() ) ``` **参数列表:** - **string** `$path` 又拍云存储中的文件或者目录路径 - **resource** `$saveHandler` 文件内容写入本地文件流。例如 `$saveHandler = fopen('/local/file', 'w') `。当设置该参数时，将以文件流的方式，直接将又拍云中的文件写入本地的文件流，或其他可以写入的流 - **array** `$params` 可选参数，读取目录内容时，需要设置三个参数： `X-List-Iter` 分页开始位置（第一页不需要设置），`X-List-Limit` 获取的文件数量（默认 100，最大 10000），`X-List-Order` 结果以时间正序或者倒序 **返回值：** $return 当读取文件且没有设置 `$saveHandler` 参数时，返回一个字符串类型，表示文件内容；设置了 `$saveHandler` 参数时，返回布尔值 `true`。当读取目录时，返回一个数组，表示目录下的文件列表。目录下文件内容过多时，需要通过判断返回数组中的 `is_end` 属性，进行分页读取内容 --- ### has 判断文件是否存在于又拍云存储 ```php Upyun::has( string $path ) ``` 注意: 对刚删除的文件, 立即调用该方法可能会返回 true, 因为服务端执行删除操作后可能会有很短暂的延迟. **参数列表:** - **string** `$path` 云存储的文件路径 **返回值：** 存在时返回 `true`，否则返回 `false` --- ### info 获取云存储文件/目录的基本信息 ```php Upyun::info( string $path, array $otherHeaders) ``` **参数列表:** - **string** `$path` 云存储的文件路径 - **string** `$otherHeaders` 设置了后，方法将返回其他 http header 中的信息，默认为空 **返回值：** 返回一个数组，默认包含以下 key - `x-upyun-file-type` 当 $path 是目录时，值为 *folder*，当 $path 是文件时，值为 *file*， - `x-upyun-file-size` 文件大小 - `x-upyun-file-date` 文件的创建时间 --- ### getMimetype 获取云存储文件的文档类型 ```php Upyun::getMimetype( string $path ) ``` **参数列表:** - **string** `$path` 云存储的文件路径 **返回值：** 文档类型，e.g: `appcation/json`，获取失败返回空字符串 --- ### delete 删除文件或者目录 ```php Upyun::delete( string $path, boolean $async = false ) ``` **参数列表:** - **string** `$path` 文件或目录在又拍云存储的路径 - **boolean** `$async` 是否异步删除，默认为 false，表示同步删除。当需要批量删除大量文件时，必须选择异步删除 **返回值：** 删除成功返回 true，否则 false --- ### createDir 创建目录 ```php Upyun::createDir( string $path ) ``` **参数列表:** - **string** `$path` 需要在又拍云存储创建的目录路径 **返回值：** 创建成功返回 true，否则返回 false --- ### deleteDir 删除文件或者目录 ```php Upyun::deleteDir( string $path ) ``` **参数列表:** - **string** `$path` 需要被删除的云存储文件或目录路径 **返回值：** 成功返回 true，否则 false --- ### usage 获取目录下存储使用量 ```php Upyun::usage( string $path = '/' ) ``` **参数列表:** - **string** `$path` 云存储目录路径，默认为根目录，表示整个云存储服务使用的空间大小 **返回值：** 存储使用量，单位字节 --- ### purge 刷新缓存 ```php Upyun::purge( array|string $urls ) ``` **参数列表:** - **array|string** `$urls` 需要刷新的文件 url 列表 **返回值：** 刷新失败的 url 列表，若全部刷新成功则为空数组 --- ### process 异步云处理 ```php Upyun::process( array $tasks, string $type, string $source ) ``` 该方法是基于[又拍云云处理](http://docs.upyun.com/cloud/) 服务实现，可以实现音视频的转码、切片、剪辑；文件的压缩解压缩；文件拉取功能 注意： - 所有需要调用该方法处理的资源，必须已经上传到云存储服务 - 使用 `process` 之前，必须配置 `config->processNotifyUrl`，否则会提交任务失败 例如视频转码： ``` process(array( array( 'type' => 'video', // video 表示视频任务, audio 表示音频任务 'avopts' => '/s/240p(4:3)/as/1/r/30', // 处理参数，`s` 表示输出的分辨率，`r` 表示视频帧率，`as` 表示是否自动调整分辨率 'save_as' => '/video/240/new.mp4', // 新视频在又拍云存储的保存路径 ), ... // 同时还可以添加其他任务 ), Upyun::$PROCESS_TYPE_MEDIA, $source) ``` 注意，被处理的资源需要已经上传到又拍云云存储 **参数列表:** - **array** `$tasks` 需要处理的任务 - **string** `$type` 异步云处理任务类型，可选值: - `Upyun::$PROCESS_TYPE_MEDIA` 异步音视频处理 - `Upyun::$PROCESS_TYPE_ZIP` 文件压缩 - `Upyun::$PROCESS_TYPE_UNZIP` 文件解压 - `Upyun::$PROCESS_TYPE_SYNC_FILE` 文件拉取 - `Upyun::$PROCESS_TYPE_STITCH` 图片拼接 - **string** `$source` 可选参数，处理异步音视频任务时，需要传递该参数，表示需要处理的文件路径 **返回值：** 任务 ID，提交了多少任务，便会返回多少任务 ID，与提交任务的顺序保持一致。可以通过任务 ID 查询处理进度。格式如下： ``` array( '35f0148d414a688a275bf915ba7cebb2', '98adbaa52b2f63d6d7f327a0ff223348', ) ``` --- ### queryProcessStatus 音视频预处理任务进度查询 ```php Upyun::queryProcessStatus( array $taskIds ) ``` 根据 `process` 方法返回的任务 ID，通过该访问查询处理进度 **参数列表:** - **array** `$taskIds` 任务 ID **返回值：** 查询失败返回布尔值 `false`，否则返回每个任务的百分比进度信息，格式如下： ``` array( '35f0148d414a688a275bf915ba7cebb2' => 100, // 100 表示任务完成 'c3103189fa906a5354d29bd807e8dc51' => 35, '98adbaa52b2f63d6d7f327a0ff223348' => null, // null 表示任务未开始，或异常 ) ``` --- ### queryProcessResult 音视频预处理任务结果查询 ```php Upyun::queryProcessResult( array $taskIds ) ``` 根据 `process` 方法返回的任务 ID，通过该访问查询处理结果，会包含每个任务详细信息 **参数列表:** - **array** `$taskIds` 任务 ID **返回值：** 查询失败返回 `false`，否则返回每个任务的处理结果，格式如下： ``` array( '9d9c32b63a1034834e77672c6f51f661' => array( 'path' => array('/v2.mp4'), 'signature' => '4042c1f07f546d28', 'status_code' => 200, 'service' => 'your_storage_service', 'description' => 'OK', 'task_id' => '9d9c32b63a1034834e77672c6f51f661', 'timestamp' => 1472010684 ) ) ``` --- -------- > This document was automatically generated from source code comments on 2017-02-06 using [phpDocumentor](http://www.phpdoc.org/) and [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public)