mirror of https://github.com/xinyewl/Simpic
510 lines
11 KiB
Markdown
510 lines
11 KiB
Markdown
# 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( string $source, array $tasks )
|
||
```
|
||
|
||
该方法是基于[又拍云云处理](http://docs.upyun.com/cloud/) 服务实现，可以实现音视频的转码、切片、剪辑；文件的压缩解压缩；文件拉取功能
|
||
|
||
注意：
|
||
- 所有需要调用该方法处理的资源，必须已经上传到云存储服务
|
||
- 使用 `process` 之前，必须配置 `config->processNotifyUrl`，否则会提交任务失败
|
||
|
||
例如视频转码：
|
||
```
|
||
process($source, array(
|
||
array(
|
||
'type' => 'video', // video 表示视频任务, audio 表示音频任务
|
||
'avopts' => '/s/240p(4:3)/as/1/r/30', // 处理参数，`s` 表示输出的分辨率，`r` 表示视频帧率，`as` 表示是否自动调整分辨率
|
||
'save_as' => '/video/240/new.mp4', // 新视频在又拍云存储的保存路径
|
||
),
|
||
... // 同时还可以添加其他任务
|
||
))
|
||
```
|
||
注意，被处理的资源需要已经上传到又拍云云存储
|
||
|
||
|
||
**参数列表:**
|
||
|
||
|
||
- **string** `$source`
|
||
需要预处理的图片、音视频资源在又拍云存储的路径
|
||
|
||
- **array** `$tasks`
|
||
需要处理的任务
|
||
|
||
|
||
**返回值：**
|
||
|
||
任务 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)
|