欢迎各位兄弟 发布技术文章

这里的技术是共享的

You are here

七牛 PHP SDK

此 SDK ( version: 7.x.x ) 适用于PHP >= 5.3.0

此 SDK 包含了如下几个功能:

  • 数据的上传和下载。

  • 数据的管理: 复制,移动,删除,获取元信息,列取文件。

  • 数据的处理: 图片的处理,音视频的处理,文档的处理。

SDK(version: 6.x.x 适用于PHP >= 5.1.0): PHP SDK历史文档

安装

支持以下3种安装 SDK 的方法,推荐通过Composer安装 SDK。

  • 使用 Composer 安装

Composer是 PHP 依赖管理工具。你可以在自己的项目中声明所依赖的外部工具库,Composer 会自动帮你安装这些依赖的库文件。

   1. 安装 Composer


  1. curl -sS https://getcomposer.org/installer | php

   2. 运行 Composer 命令安装最新稳定版本的 SDK:


  1. php composer.phar require qiniu/php-sdk

   3. Require Composer 生成的 autoloader:


  1. <?php
  2. require 'vendor/autoload.php';
  3.  

  1. 如果需要更详细的关于 Composer 的使用说明,你可以访问[Composer官方网站](http://getcomposer.org/),或对应的[中文网站](http://www.phpcomposer.com/)。

  • 直接下载 Composer 安装包

    鉴于某些原因,国内的用户使用 Composer 下载依赖库比较慢,开发者也可以直接下载我们准备好的符合 Composer 规范的vendor 压缩包并在本地解压。解压后的内容和使用 Composer 方式获取到的内容完全一致,之后的使用方式也一致。

  • 下载源代码包

    直接下载源代码压缩包并解压是另一种 SDK 的安装方法。不过因为有版本更新的维护问题,这种安装方法并不推荐,仅作为万一 Composer 安装有问题的情况下的一种备选。并且,源码中也包含 SDK 的 autoloader

    下载源代码包后,解压到您的项目中。 然后在您的项目中引入 autoloader:

    
    
    1. require 'path_to_sdk/autoload.php';

基本使用方法

安装好 SDK 后,接下来介绍如何使用 SDK。在使用 SDK 之前,需要注册一个七牛帐号,并登录控制台获取一对有效的AccessKey和SecretKey,并且详细阅读[安全机制][securityHref]以进一步了解如何正确使用和管理密钥。

引入SDK

无论你是通过哪种方式安装的 SDK,只需要一句简单的 require 语句将安装好的SDK包含到你的项目中。请参考如下表格,找到适合你的安装方式,将SDK引入到你的项目中。请用你项目中的实际路径替换 path_to_sdk

安装方式引入SDK
Composer 安装require 'path_to_sdk/vendor/autoload.php';
下载Composer安装包require 'path_to_sdk/vendor/autoload.php';
下载源码安装包require 'path_to_sdk/autoload.php';

SDK结构

可以直接查看我们的SDK目录,即可大致了解我们SDK的结构。

  • 最外层包含:配置文件, 鉴权和一些公共的函数。
  • HTTP 目录主要包含了一些对 http 进行封装的类,这块你可以不用关心。
  • Storage 目录主要包含两大块:Bucket 中文件的管理和文件的上传。
  • Processing 目录主要包含文件的处理,文件处理又包含两个方面:同步处理和异步处理。

为了帮助您更好的了解和使用我们的sdk,我们还提供了各种使用示例。 如果使用中遇到问题,可以通过Github或者我们的工单进行反馈。下面我们对一些关键点进行简单的介绍,方便您快速入门。

鉴权类

在使用七牛的SDK的过程中鉴权是很重要的一块,不管是上传鉴权,下载签权, 还是回调的签权。 PHP SDK 中的 Auth 类封装了所有的鉴权方式。 所以在使用 PHP SDK 时基本都会先对鉴权类进行初始化:


  1. <?php
  2. require 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5.  
  6. // 用于签名的公钥和私钥
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9.  
  10. // 初始化签权对象
  11. $auth = new Auth($accessKey, $secretKey);

初始化好Auth 类后,就可以调用相应的方法了,比如生成私有下载链接方法 privateDownloadUrl,获取上传Token方法 uploadToken,验证回调方法 verifyCallback等。

上传类

在上传类 UploadManager 中主要负责文件的上传, 七牛的文件上传分为两种上传方式:表单上传分片上传。当然在PHP SDK中你不用关心这个细节,只需要调用 UploadManager 中的上传方法即可。UploadManager 中的上传方法会根据上传文件的大小选择不同的上传方式,小于4MB的进行表单上传,大于4MB的进行分片上传。 以下一个简单的示例使你更清晰地了解如何初始上传对象:


  1. <?php
  2. require 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\UploadManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9. $auth = new Auth($accessKey, $secretKey);
  10.  
  11. // 空间名 https://developer.qiniu.io/kodo/manual/concepts
  12. $bucket = 'Bucket_Name';
  13.  
  14. // 生成上传Token
  15. $token = $auth->uploadToken($bucket);
  16.  
  17. // 构建 UploadManager 对象
  18. $uploadMgr = new UploadManager();

空间名请参阅空间

资源管理类

在资源管理类 BucketManager 中主要负责空间中文件的管理: 复制,移动,删除,获取元信息,修改Mime,拉取文件到七牛空间,列取文件。 以下一个简单的示例使你更清晰地了解如何初始空间管理对象:


  1. <?php
  2. require 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\BucketManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9.  
  10. //初始化Auth状态
  11. $auth = new Auth($accessKey, $secretKey);
  12.  
  13. //初始化BucketManager
  14. $bucketMgr = new BucketManager($auth);

触发持久化类

触发持久化类 PersistentFop 中主要负责对空间中已上传的文件进行异步处理,并对异步处理的结果进行持久化操作。比如对已上传的视频文件进行转码,拼接,切片,水印等处理,并将处理后的结果保存在空间中。


  1. <?php
  2.  
  3. require_once __DIR__ . '/../autoload.php';
  4.  
  5. use Qiniu\Auth;
  6. use Qiniu\Processing\PersistentFop;
  7.  
  8. $accessKey = 'Access_Key';
  9. $secretKey = 'Secret_Key';
  10. $auth = new Auth($accessKey, $secretKey);
  11.  
  12. // 要转码的文件所在的空间
  13. $bucket = 'Bucket_Name';
  14.  
  15. // 转码时使用的队列名称
  16. $pipeline = 'abc';
  17.  
  18. // 初始化
  19. $pfop = new PersistentFop($auth, $bucket, $pipeline);

场景化示例

接下来我们,对一些常见的使用场景,提供一些简单的Demo,使您更快速的接入七牛。

Hello, World!

在了解了基本概念和编程模型后,我们现在以最短的篇幅将第一个云存储服务的示例程序跑起来。该示例的目标是:将一个本地小文件上传到指定的存储空间中。

提交页面

我们先写一个简单的 HTML 表单来供用户上传到七牛存储空间信息并选择一个本地文件。在点击提交按钮后,浏览器会发送一个 HTTP 请求到七牛上传域名执行文件上传动作。


  1. <form method="post" action="http://up.qiniu.com" enctype="multipart/form-data">
  2. <input name="token" type="hidden" value="<upload_token>">
  3. <input name="file" type="file" />
  4. <input type="submit" value="上传"/>
  5. </form>

上传动作

也许你注意到了这个上传表单有一个token字段,所以想要使用 form 直传七牛一个文件,必须在页面加载的时候,向服务端请求token并设置到这个表单项中。服务端生成这个token涉及到我们 SDK 中提供的方法:Qiniu\Auth

关键代码如下所示:


  1. use Qiniu\Auth;
  2.  
  3. $bucket = '<your_bucket>';
  4. $accessKey = '<your_access_key>';
  5. $secretKey = '<your_secret_key>';
  6. $auth = new Auth($accessKey, $secretKey);
  7.  
  8. $upToken = $auth->uploadToken($bucket);
  9.  
  10. echo $upToken;

可以看出,以上代码主要做了以下几步工作:

  1. 使用你的 AccessKey 及 SecretKey 用于初始化Auth对象
  2. 调用初始化的对象Auth对象的方法uploadToken来生成上传token

到这里为止,第一个示例就可以运行起来了。您可以查看该示例的在线演示。您也可以直接获取和查看该示例的源代码

小结

这个示例仅用于演示如何使用 PHP SDK 快速运行第一个云存储服务的程序。本事例尽可能简单的展现七牛的表单上传,因此请大家仅将本示例作为学习 PHP SDK 的一个步骤,而不是在产品环境中应用。

一个完整的移动应用

我们将详细介绍如何使用 PHP SDK 与其他端配合构建一个类似于微信朋友圈的移动应用。

在这个移动应用里终端用户可以进行如下操作:

  1. 使用预设的帐号密码登录(不支持注册新帐号)
  2. 查看自己和朋友分享的照片以及描述(不支持评论)
  3. 上传一张新图片,并添加一段描述。

Demo截图

总体架构

对于此类应用,我们推荐的总体架构如下图所示:

arch-with-callback

对于此架构有以下关键要点:

  1. AK/SK 只能在业务服务器端使用,如果将 AK 和 SK 同时保存或者传输到移动端会有严重的信息泄露风险。
  2. AK/SK 是企业帐号信息,业务服务器需要有自己的帐号数据库,对应到每一个终端用户的帐号信息。
  3. 由于不同的业务都需要存放一些跟文件相关的描述信息,且图片又属于不同的终端用户,因此需要维护文件管理表,以管理文件的描述信息和所有者关系。

基于以上这些关键要点,我们来设计和实现我们的 PHP 版本的业务服务器。

接口设计

我们来简单的设计我们的业务服务器接口。

帐号验证:


  1. POST /login.php HTTP/1.1
  2. HOST: demos.qiniu.io
  3. Accept: */*
  4. Content-Type: application/x-www-form-urlencoded
  5.  
  6.  
  7. uname=<username>&pwd=<password>
  8.  

获取文件列表:


  1. POST /files.php HTTP/1.1
  2. HOST: demos.qiniu.io
  3. Accept: */*
  4. Cookie: <cookie>
  5. Content-Type: application/x-www-form-urlencoded

获取上传授权,因为移动端并不知道 AK/SK 信息,客户端在需要上传文件时都需要向业务服务器发起一个获取上传授权的请求:


  1. POST /uptoken.php HTTP/1.1
  2. HOST: demos.qiniu.io
  3. Accept: */*
  4. Cookie: <cookie>
  5. Content-Type: application/x-www-form-urlencoded

回调,移动端会直接上传文件到云存储服务,因此业务服务器不需要提供上传接口,但是需要提供一个供云存储服务在接收到文件后的回调接口。回调接口的响应内容会由云存储服务返回给移动端:


  1. POST /callback.php HTTP/1.1
  2. HOST: demos.qiniu.io
  3. Accept: */*
  4. Cookie: <cookie>
  5. Content-Type: application/x-www-form-urlencoded
  6.  
  7. uid=<uid>&fname=<file_name>&fkey=<file_key>&desc=<description>
  8.  

数据表,业务服务需要一个业务数据库的支撑以管理提到的帐号信息和文件信息。在本示例中我们选用 MySQL 来搭建业务数据库。帐号表:

字段名字段类型字段说明
idint唯一标识。 
uidint唯一用户标识。 
unamechar(128)用户名,格式为邮箱如 admin@example.com 
passwordchar(128)加密后的密码。 
statusint1: active 
0: disabled
 

文件信息表:

字段名字段类型字段说明
idint唯一标识。 
uidint用户唯一标识。 
fnamechar(512)文件的显示名 
keychar(512)文件对应到云存储服务中的唯一标识。 
createTimetime上传时间。 
descriptionchar(2048)文件的描述内容。 

相应的 SQL 语句如下:


  1. create database qspace;
  2.  
  3. CREATE TABLE users (
  4. uid INT NOT NULL AUTO_INCREMENT,
  5. uname VARCHAR(128) NOT NULL,
  6. password VARCHAR(128) NOT NULL,
  7. status INT,
  8. PRIMARY KEY (uid)
  9. );
  10.  
  11. CREATE TABLE files_info (
  12. id INT NOT NULL AUTO_INCREMENT,
  13. uid INT NOT NULL,
  14. fname VARCHAR(512) NOT NULL,
  15. fkey VARCHAR(512) NOT NULL,
  16. createTime INT,
  17. description VARCHAR(1024),
  18. PRIMARY KEY (id),
  19. FOREIGN KEY (uid) REFERENCES users(uid),
  20. UNIQUE INDEX (id)
  21. );

服务实现

接下来我们一步步的实现以上定义的接口。这些实现主要考虑流程的完整性,因此在安全性上没有做充分的考量,请不要直接使用于产品环境中。

配置文件

我们需要在一个地方存放全局的设置。本示例中我们直接用一个 config.php 文件包含若干全局变量的方式来解决这个问题。


  1. <?php
  2. class Config
  3. {
  4. const DB_NAME = 'qspace',
  5. DB_USER = 'root',
  6. DB_PWD = '****',
  7. DB_HOST = '<your_db_host>',
  8. ACCESS_KEY = '<your_access_key>',
  9. SECRET_KEY = '<your_secret_key>',
  10. BUCKET_NAME = '<your_bucket_name>';
  11. }

帐号验证

帐号验证的逻辑非常简单,就是将请求中包含的用户信息与数据库表中的信息进行比对,因此不需要涉及 SDK 的功能。


  1. <?php
  2. require_once 'db.php';
  3.  
  4. session_start();
  5.  
  6. if(!isset($_POST['uname']) && !isset($_POST['pwd']))
  7. {
  8. http_response_code(401);
  9. $resp = array('status' => 'failed', 'msg' => 'please input username & password!');
  10. echo json_encode($resp);
  11. return;
  12. }
  13.  
  14. $uname = $_POST['uname'];
  15. $_pwd = $_POST['pwd'];
  16.  
  17. $salt = 'Qiniu' . $uname;
  18. $pwd = crypt($_pwd, $salt);
  19.  
  20. $stmt = $DB->prepare('select * from users where uname = :name');
  21. $stmt->execute(array('name' => $uname));
  22.  
  23. $user = $stmt->fetch();
  24.  
  25. if ($user['password'] !== $pwd)
  26. {
  27. http_response_code(401);
  28. $resp = array('status' => 'failed', 'msg' => 'incorrect username or password!');
  29. echo json_encode($resp);
  30. return;
  31. }
  32.  
  33. $_SESSION['uid'] = $user['uid'];
  34. $_SESSION['uname'] = $uname;
  35.  
  36. $resp = array('status' => 'ok', 'uname' => $uname);
  37. echo json_encode($resp);

获取文件列表

同帐号验证功能一样,获取文件列表也只是查询数据库,因此不多做解释。


  1. <?php
  2. require_once 'db.php';
  3.  
  4. session_start();
  5.  
  6. $uid = $_SESSION['uid'];
  7. if(!isset($uid))
  8. {
  9. header('location: login.php');
  10. return;
  11. }
  12.  
  13. $stmt = $DB->prepare('select * from files_info where uid = :uid');
  14. $stmt->execute(array('uid' => $uid));
  15.  
  16. $files = $stmt->fetchAll();
  17.  
  18. echo json_encode($files);

获取上传授权

客户端在需要上传文件时都需要先向业务服务器发起一个获取上传授权的请求。 SDK 中的 Qiniu\Auth 类提供了 uploadToken($bucket, ...) 方法,可以非常便利的生成对应的上传授权。


  1. <?php
  2. require_once 'vendor/autoload.php';
  3. require_once 'db.php';
  4. require_once 'config.php';
  5.  
  6. use Qiniu\Auth;
  7.  
  8. session_start();
  9. $uid = $_SESSION['uid'];
  10. if(!isset($uid))
  11. {
  12. header('location: login.php');
  13. return;
  14. }
  15.  
  16. $bucket = Config::BUCKET_NAME;
  17. $accessKey = Config::ACCESS_KEY;
  18. $secretKey = Config::SECRET_KEY;
  19. $auth = new Auth($accessKey, $secretKey);
  20.  
  21. $policy = array(
  22. 'callbackUrl' => 'http://172.30.251.210/callback.php',
  23. 'callbackBody' => '{"fname":"$(fname)", "fkey":"$(key)", "desc":"$(x:desc)", "uid":' . $uid . '}'
  24. );
  25.  
  26. $upToken = $auth->uploadToken($bucket, null, 3600, $policy);
  27.  
  28. header('Access-Control-Allow-Origin:*');
  29. echo $upToken;

回调

在收到回调时,通常表示一个文件已经成功上传。回调会包含该文件所对应的描述信息。因此业务服务器在收到回调后,需要将相应的文件信息写入到文件信息表中。


  1. <?php
  2. require_once 'db.php';
  3.  
  4. $_body = file_get_contents('php://input');
  5. $body = json_decode($_body, true);
  6.  
  7. $uid = $body['uid'];
  8. $fname = $body['fname'];
  9. $fkey = $body['fkey'];
  10. $desc = $body['desc'];
  11.  
  12. $date = new DateTime();
  13. $ctime = $date->getTimestamp();
  14.  
  15. $stmt = $DB->prepare('INSERT INTO files_info (uid, fname, fkey, createTime, description) VALUES (:uid, :fname, :fkey, :ctime, :desc);');
  16. $ok = $stmt->execute(array('uid' => $uid, 'fname' => $fname, 'fkey' => $fkey, 'ctime' => $ctime, 'desc' => $desc));
  17.  
  18. header('Content-Type: application/json');
  19. if (!$ok)
  20. {
  21. $resp = $DB->errorInfo();
  22. http_response_code(500);
  23. echo json_encode($resp);
  24. return;
  25. }
  26.  
  27. $resp = array('ret' => 'success');
  28. echo json_encode($resp);

服务监控

为了确认服务的正常运行,我们还实现了一个简单的监控页面以查看所有上传的图片。该页面假设admin的管理员才有权访问。后端代码就是将用户上传的文件从数据库中列取出来。


  1. <?php
  2. require_once 'vendor/autoload.php';
  3. require_once 'db.php';
  4.  
  5. if (!$_SESSION['logged'])
  6. {
  7. header('login.php');
  8. }
  9.  
  10. $id = $_POST['id'];
  11. if ($id)
  12. {
  13. $stmt = $DB->prepare('delete from files_info where id = :id');
  14. $stmt->execute(array('id' => $id));
  15. }
  16.  
  17. $stmt = $DB->prepare('select * from files_info');
  18. $stmt->execute();
  19. $files = $stmt->fetchAll();
  20.  
  21. $smarty = new Smarty();
  22. $smarty->assign('files', $files);
  23.  
  24. $smarty->display('file_mgr.tpl');

前端页面使用 Bootstrap 的控件实现,并使用 Smarty 模板技术来循环生成最终页面:


  1. {foreach from=$files item=file}
  2. <tr>
  3. <td><a href="{$file[uid]}">{$file["uid"]}</a></td>
  4. <td>{$file["fname"]}</td>
  5. <td>{$file["fkey"]}</td>
  6. <td>{$file["description"]}</td>
  7. <td>{$file["createTime"]}</td>
  8. <td><a class="del" href="" data-fid="{$file['id']}">删除</a></td>
  9. </tr>
  10. {/foreach}

移动端实现

本示例包含一个 Android 客户端的实现。因为本文档的重心是结合例子讲解 PHP SDK 的使用,因此这里就不详细讲解如何实现 Android 客户端了。您可以下载和安装移动客户端的安装包,或查看移动客户端的源代码

小结

您可以在 Android 手机或者模拟器上安装和运行本示例的移动端应用,上传一张图片,并查看图片列表和描述。这个示例的重点在于讲解一个推荐的产品架构,以及各个子系统如何协同工作。

接下来我们再围绕几个示例遍历七牛云提供的其他强大功能。接下来的示例都不会再像这个示例一样提供一个完整的移动互联网产品架构,而是把重点放在功能介绍上。您可以举一反三,快速的在本章介绍的示例上进行修改和加强,就可以快速开发出各种有趣的移动互联网应用。移动端安装包,或查看移动客户端的源代码admin管理界面

图片处理

我们将围绕一个功能相对完备的示例来讲解图片处理的主要用法,并顺便介绍 PHP SDK 的资源管理功能。

这个示例用户可以上传图片,选择图片处理模式,输入相应的处理参数,然后可以查看处理的结果。用户还可以点选不同的图片以显示图片的鉴黄信息和鉴别广告的信息, 以及获取图片的基本信息,平均色,exif信息等。

下面我们分步来实现这个示例。前端实现使用了Bootstrap和我们的js-sdk,后端使用 phpsdk 生成上传的 token 。

生成上传token

首先安装我们的 phpsdk,然后引入相应文件并调用接口生成上传token:


  1. require_once 'vendor/autoload.php';
  2. require_once 'config.php';
  3.  
  4. use Qiniu\Auth;
  5.  
  6. $bucket = Config::BUCKET_NAME;
  7. $accessKey = Config::ACCESS_KEY;
  8. $secretKey = Config::SECRET_KEY;
  9.  
  10. $auth = new Auth($accessKey, $secretKey);
  11. $upToken = $auth->uploadToken($bucket);
  12.  
  13. $ret = array('uptoken' => $upToken);
  14.  
  15. echo json_encode($ret);

上传部分相关的 html 代码:


  1. <div id="container">
  2. <button id="pickfiles" class="btn btn-primary btn-lg btn-block" type="submit">上传图片</button>
  3. </div>

上传对应的调用 jssdk 相关代码:


  1. var uploader = Qiniu.uploader({
  2. runtimes: 'html5,flash,html4', //上传模式,依次退化
  3. browse_button: 'pickfiles', //上传选择的点选按钮,**必需**
  4. uptoken_url: 'uptoken.php', //Ajax请求upToken的Url,**强烈建议设置**(服务端提供)
  5. domain: 'http://rwxf.qiniudn.com/', //bucket 域名,下载资源时用到,**必需**
  6. container: 'container', //上传区域DOM ID,默认是browser_button的父元素,
  7. max_file_size: '100mb', //最大文件体积限制
  8. flash_swf_url: 'plupload/Moxie.swf', //引入flash,相对路径
  9. max_retries: 3, //上传失败最大重试次数
  10. dragdrop: true, //开启可拖曳上传
  11. drop_element: 'container', //拖曳上传区域元素的ID,拖曳文件或文件夹后可触发上传
  12. chunk_size: '4mb', //分块上传时,每片的体积
  13. auto_start: true, //选择文件后自动上传,若关闭需要自己绑定事件触发上传
  14. init: {
  15. 'UploadProgress': function(up, file) {
  16. $('#pickfiles').prop('disabled', true).html('图片上传中...');
  17. },
  18. 'FileUploaded': function(up, file, info) {
  19.  
  20. $('#pickfiles').prop('disabled', false).html('上传图片');
  21. var res = JSON.parse(info);
  22. imgUrl = up.getOption('domain') + res.key;
  23. refresh(imgUrl);
  24. },
  25. 'Error': function(up, err, errTip) {
  26. $('#pickfiles').prop('disabled', false).html('上传图片');
  27. }
  28. }
  29. });

图片处理

图片处理的过程非常简单,就是将我们的图片处理 fop 以及对应的参数拼接在图片地址后面即可。基本不需要用到 SDK 的功能,当然你也可以使用我们的 jssdk 进行图片地址和处理参数的拼接。 比如一个图片:http://qiniuphotos.qiniudn.com/gogopher.jpg,现在我们对这个图片进行200x200的等比缩放,然后再进行居中剪裁,可以使用imageView2的模式1,最终得到的图片:http://qiniuphotos.qiniudn.com/gogopher.jpg?imageView2/1/w/200/h/200

更多处理规格请参考图片基本处理 (imageView2)文档。

图片信息


  1. {
  2. format: "jpeg",
  3. width: 640,
  4. height: 427,
  5. colorModel: "ycbcr",
  6. orientation: "Top-left"
  7. }

  1. {
  2. RGB: "0x85694d"
  3. }

  1. {
  2. ApertureValue: {
  3. val: "5.00 EV (f/5.7)",
  4. type: 5
  5. },
  6. ColorSpace: {
  7. val: "sRGB",
  8. type: 3
  9. },
  10. ComponentsConfiguration: {
  11. val: "- - - -",
  12. type: 7
  13. },
  14. ...
  15. }

自定义数据处理功能

除了我们官方提供的强大图片处理功能外,我们的自定义数据处理平台还提供了强大的第三方数据处理服务。在本例中我们就来尝试一下图片鉴黄服务(nrop) 。

要使用 NROP 功能,用户需要先在管理平台上的第三方数据处理开启本功能。开启后使用方式与一般的数据处理指令完全一致(比如获取 EXIF 信息的接口),仅需要使用带 nrop 参数的 GET 请求即可,返回的 HTTP 响应内容为一个包含鉴定结果的 JSON 字符串。示例代码如下:

http://qiniuphotos.qiniudn.com/gogopher.jpg?nrop


  1. {
  2. statistic: [
  3. 0,
  4. 0,
  5. 1
  6. ],
  7. reviewCount: 0,
  8. fileList: [{
  9. rate: 0.9946920275688171, // 介于0-1间的浮点数,表示该图像被识别为某个分类的概率值,概率越高、机器越肯定
  10. label: 2, // 0:色情; 1:性感; 2:正常
  11. name: "739a77baf4ff2d5eae5fe56602fc0cbe/gogopher.jpg",
  12. review: false //是否需要人工复审该图片,鉴黄服务是否对结果确定(true:不确定,false:确定)
  13. }],
  14. nonce: "0.5508577267173678",
  15. timestamp: 1437903830,
  16. code: 0,
  17. message: "success"
  18. }

我们提供的完整示例已经包含了对 NROP 的调用,以及对广告的鉴定,您可以体验一下效果。

小结

这个示例结束后,相信你已经比较了解我们的平台是如何支持图片内容的编辑,基本上这些动作都只是一个简单的 GET 请求即可完成,甚至都不需要依赖于 SDK。您可以查看本示例的在线演示,或查看和下载本示例的完整源代码

音视频处理

用一个示例详细讲解七牛云对音视频和流媒体格式的强大支持。该示例的目标为完成以下动作:

  1. 支持断点续传的大文件上传,因为视频文件通常比较大,难以用单次 POST 请求完成上传;
  2. 支持上传后异步执行的自动转码动作,生成若干不同规格的目标视频,分别适合在手机和电脑上播放;
  3. 将文件转换为 HLS 格式存放,以支持边下载边播放的效果;
  4. 为视频打上一个图片水印;
  5. 统一从每一个视频文件抽取一个固定时间点的画面作为预览图片;
  6. 在网页播放器中播放生成的视频文件;

我们选用 plupload 作为我们的上传控件,并使用 videojs 作为我们的网页播放器。其他采用的技术与之前的示例一致,主要是 Bootstrap 和 Smarty 。因为文件为客户端直传,因此我们也需要提供一个回调服务,以便于接收上传和转码这些异步任务的完成事件。为了简单起见,该示例就不再实现一个独立的业务数据库了,直接从目标存储空间获取文件信息。

大文件上传

因为大文件上传必须在浏览器端进行,因此我们就不演示如何用 PHP SDK 做断点续上传了。网页端的大文件上传我们可以用定制版本的 plupload 来支持。 具体可以查看我们的jssdk

上传后自动转码

我们可以通过设置上传策略来通知云存储服务在上传完成后自动发起一个异步的任务。上传策略在调用上传接口时作为参数传入。 这里的转码过程需要支持转为 HLS 格式,并且在转码后打上视频水印。具体生成上传策略的代码为:


  1. $bucket = Config::BUCKET_NAME;
  2. $auth = new Auth(Config::AK, Config::SK);
  3.  
  4. $wmImg = Qiniu\base64_urlSafeEncode('http://rwxf.qiniudn.com/logo-s.png');
  5. $pfopOps = "avthumb/m3u8/noDomain/1/wmImage/$wmImg";
  6. $policy = array(
  7. 'persistentOps' => $pfopOps,
  8. 'persistentNotifyUrl' => 'http://<your_notify_url>',
  9. );
  10.  
  11. $upToken = $auth->uploadToken($bucket, null, 3600, $policy);
  12.  
  13. echo json_encode(array('uptoken' => $upToken));

抽取视频截图

我们可以从上传视频中截取固定时间点的帧,以作为这些视频的封面图片。视频截图如下所示:


  1. http://<your_uploaded_video>?vframe/jpg/offset/5

视频浏览与播放

在完成以上工作后,接下来的工作就简单了。我们可以生成一个列表网页,每个列表项都是一张视频截图,点击视频截图会弹出一个播放面板。因为类似的前端代码已经在本文档展示过,这里就不再多展示一次。

小结

视频的示例就到这里完成了。您可以直接查看本示例的在线演示,或下载和查看本示例的完整源代码

需要注意的是,我们这边使用了videojs的开源播放器, 世面上还有其他比较优秀的播放器,具体你可以参考播放器推荐

另外,对于视频内容,CDN 的选择会是一个影响视频播放是否能够足够流畅的关键因素。在融合 CDN 管理平台会给列出的可用 CDN 线路标注是否适用于视频加速,请合理选择。

文件上传

上传流程

为了尽可能地改善终端用户的上传体验,七牛云存储首创了客户端直传功能。更多信息请参阅业务流程

上传代码:


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. // 引入鉴权类
  5. use Qiniu\Auth;
  6.  
  7. // 引入上传类
  8. use Qiniu\Storage\UploadManager;
  9.  
  10. // 需要填写你的 Access Key 和 Secret Key
  11. $accessKey = 'Access_Key';
  12. $secretKey = 'Secret_Key';
  13.  
  14. // 构建鉴权对象
  15. $auth = new Auth($accessKey, $secretKey);
  16.  
  17. // 要上传的空间
  18. $bucket = 'Bucket_Name';
  19.  
  20. // 生成上传 Token
  21. $token = $auth->uploadToken($bucket);
  22.  
  23. // 要上传文件的本地路径
  24. $filePath = './php-logo.png';
  25.  
  26. // 上传到七牛后保存的文件名
  27. $key = 'my-php-logo.png';
  28.  
  29. // 初始化 UploadManager 对象并进行文件的上传
  30. $uploadMgr = new UploadManager();
  31.  
  32. // 调用 UploadManager 的 putFile 方法进行文件的上传
  33. list($ret, $err) = $uploadMgr->putFile($token, $key, $filePath);
  34. echo "\n====> putFile result: \n";
  35. if ($err !== null) {
  36. var_dump($err);
  37. } else {
  38. var_dump($ret);
  39. }

上传&回调


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\UploadManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9. $auth = new Auth($accessKey, $secretKey);
  10.  
  11. $bucket = 'Bucket_Name';
  12. // 上传文件到七牛后, 七牛将文件名和文件大小回调给业务服务器
  13.  
  14. $policy = array(
  15. 'callbackUrl' => 'http://your.domain.com/callback.php',
  16. 'callbackBody' => 'filename=$(fname)&filesize=$(fsize)'
  17. );
  18. $uptoken = $auth->uploadToken($bucket, null, 3600, $policy);
  19.  
  20. //上传文件的本地路径
  21. $filePath = './php-logo.png';
  22.  
  23. $uploadMgr = new UploadManager();
  24.  
  25. list($ret, $err) = $uploadMgr->putFile($uptoken, null, $filePath);
  26. echo "\n====> putFile result: \n";
  27. if ($err !== null) {
  28. var_dump($err);
  29. } else {
  30. var_dump($ret);
  31. }

上传&预转持续化

以视频转码为例:


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\UploadManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9. $auth = new Auth($accessKey, $secretKey);
  10.  
  11. $bucket = 'Bucket_Name';
  12.  
  13. //转码时使用的队列名称
  14. $pipeline = 'abc';
  15.  
  16. //要进行转码的转码操作
  17. $fops = "avthumb/mp4/s/640x360/vb/1.25m";
  18.  
  19. //可以对转码后的文件进行使用saveas参数自定义命名,当然也可以不指定文件会默认命名并保存在当间
  20. $savekey = Qiniu\base64_urlSafeEncode('目标Bucket_Name:自定义文件key');
  21. $fops = $fops.'|saveas/'.$savekey;
  22.  
  23. $policy = array(
  24. 'persistentOps' => $fops,
  25. 'persistentPipeline' => $pipeline
  26. );
  27. $uptoken = $auth->uploadToken($bucket, null, 3600, $policy);
  28.  
  29. //上传文件的本地路径
  30. $filePath = './php-logo.png';
  31.  
  32. $uploadMgr = new UploadManager();
  33.  
  34. list($ret, $err) = $uploadMgr->putFile($uptoken, null, $filePath);
  35. echo "\n====> putFile result: \n";
  36. if ($err !== null) {
  37. var_dump($err);
  38. } else {
  39. var_dump($ret);
  40. }

队列 (pipeline) 请参阅[创建私有队列][mpsHref];转码操作具体参数请参阅音视频转码;saveas 请参阅处理结果另存

Tips:上面的 Demo 只是针对视频转码功能,如果您需要使用比如音视频切片、视频截图、视频拼接等功能只需要修改上面 fops 后面的参数即可,如:$fops = vframe/jpg/offset/1/w/480/h/360/rotate/90 就表示视频截图了。

可以看到上传成功后的行为主要是由上传凭证中的上传策略来指定。其中 上传策略可以指定的行为不止这些,具体请参阅上传策略。等文件上传成功后就会向你设置的 callbackUrl 发起回调,你的服务器要接受并处理这个回调信息,并返回合法json数据到七牛服务器,七牛将接收到的 json 数据返回给客户端。下面我们给一个例子来看怎么接收回调信息,并验证该回调是否来自七牛:


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5.  
  6. $accessKey = 'Access_Key';
  7. $secretKey = 'Secret_Key';
  8. $auth = new Auth($accessKey, $secretKey);
  9.  
  10. //获取回调的body信息
  11. $callbackBody = file_get_contents('php://input');
  12.  
  13. //回调的contentType
  14. $contentType = 'application/x-www-form-urlencoded';
  15.  
  16. //回调的签名信息,可以验证该回调是否来自七牛
  17. $authorization = $_SERVER['HTTP_AUTHORIZATION'];
  18.  
  19. //七牛回调的url,具体可以参考
  20. $url = 'http://your.domain.com/callback.php';
  21.  
  22. $isQiniuCallback = $auth->verifyCallback($contentType, $authorization, $url, $callbackBody);
  23.  
  24. if ($isQiniuCallback) {
  25. $resp = array('ret' => 'success');
  26. } else {
  27. $resp = array('ret' => 'failed');
  28. }
  29.  
  30. echo json_encode($resp);

文件下载


  1. <?php
  2. require 'path_to_sdk/vendor/autoload.php';
  3.  
  4. // 引入鉴权类
  5. use Qiniu\Auth;
  6.  
  7. // 需要填写你的 Access Key 和 Secret Key
  8. $accessKey = 'Access_Key';
  9. $secretKey = 'Secret_Key';
  10.  
  11. // 构建鉴权对象
  12. $auth = new Auth($accessKey, $secretKey);
  13.  
  14. //baseUrl构造成私有空间的域名/key的形式
  15. $baseUrl = 'http://domain/key';
  16. $authUrl = $auth->privateDownloadUrl($baseUrl);
  17. echo $authUrl;
  18. ?>

空间资源管理

获取文件信息


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\BucketManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9.  
  10. //初始化Auth状态
  11. $auth = new Auth($accessKey, $secretKey);
  12.  
  13. //初始化BucketManager
  14. $bucketMgr = new BucketManager($auth);
  15.  
  16. //你要测试的空间, 并且这个key在你空间中存在
  17. $bucket = 'Bucket_Name';
  18. $key = 'php-logo.png';
  19.  
  20. //获取文件的状态信息
  21. list($ret, $err) = $bucketMgr->stat($bucket, $key);
  22. echo "\n====> $key stat : \n";
  23. if ($err !== null) {
  24. var_dump($err);
  25. } else {
  26. var_dump($ret);
  27. }

移动单个文件


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\BucketManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9.  
  10. //初始化Auth状态
  11. $auth = new Auth($accessKey, $secretKey);
  12.  
  13. //初始化BucketManager
  14. $bucketMgr = new BucketManager($auth);
  15.  
  16. //你要测试的空间, 并且这个key在你空间中存在
  17. $bucket = 'Bucket_Name';
  18. $key = 'php-logo.png';
  19.  
  20. //将文件从文件$key移动到文件$key2。可以在不同bucket移动
  21. $key2 = 'php-logo2.png';
  22. $err = $bucketMgr->move($bucket, $key, $bucket, $key2);
  23. echo "\n====> move $key to $key2 : \n";
  24. if ($err !== null) {
  25. var_dump($err);
  26. } else {
  27. echo "Success!";
  28. }

复制单个文件


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\BucketManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9.  
  10. //初始化Auth状态
  11. $auth = new Auth($accessKey, $secretKey);
  12.  
  13. //初始化BucketManager
  14. $bucketMgr = new BucketManager($auth);
  15.  
  16. //你要测试的空间, 并且这个key在你空间中存在
  17. $bucket = 'Bucket_Name';
  18. $key = 'php-logo.png';
  19.  
  20. //将文件从文件$key复制到文件$key2。可以在不同bucket复制
  21. $key2 = 'php-logo2.png';
  22. $err = $bucketMgr->copy($bucket, $key, $bucket, $key2);
  23. echo "\n====> copy $key to $key2 : \n";
  24. if ($err !== null) {
  25. var_dump($err);
  26. } else {
  27. echo "Success!";
  28. }

删除单个文件


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\BucketManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9.  
  10. //初始化Auth状态
  11. $auth = new Auth($accessKey, $secretKey);
  12.  
  13. //初始化BucketManager
  14. $bucketMgr = new BucketManager($auth);
  15.  
  16. //你要测试的空间, 并且这个key在你空间中存在
  17. $bucket = 'Bucket_Name';
  18. $key = 'php-logo.png';
  19.  
  20. //删除$bucket 中的文件 $key
  21. $err = $bucketMgr->delete($bucket, $key);
  22. echo "\n====> delete $key : \n";
  23. if ($err !== null) {
  24. var_dump($err);
  25. } else {
  26. echo "Success!";
  27. }

列举空间中文件


  1. <?php
  2. require_once __DIR__ . '/../autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Storage\BucketManager;
  6.  
  7. $accessKey = 'Access_Key';
  8. $secretKey = 'Secret_Key';
  9. $auth = new Auth($accessKey, $secretKey);
  10. $bucketMgr = new BucketManager($auth);
  11.  
  12. // 要列取的空间名称
  13. $bucket = 'Bucket_Name';
  14.  
  15. // 要列取文件的公共前缀
  16. $prefix = '';
  17.  
  18. $marker = '';
  19. $limit = 3;
  20.  
  21. list($iterms, $marker, $err) = $bucketMgr->listFiles($bucket, $prefix, $marker, $limit);
  22. if ($err !== null) {
  23. echo "\n====> list file err: \n";
  24. var_dump($err);
  25. } else {
  26. echo "Marker: $marker\n";
  27. echo "\nList Iterms====>\n";
  28. var_dump($iterms);
  29. }

触发持久化操作

以视频转码为例:


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Auth;
  5. use Qiniu\Processing\PersistentFop;
  6.  
  7. //对已经上传到七牛的视频发起异步转码操作
  8.  
  9. $accessKey = 'Access_Key';
  10. $secretKey = 'Secret_Key';
  11. $auth = new Auth($accessKey, $secretKey);
  12.  
  13. //要转码的文件所在的空间和文件名
  14. $bucket = 'Bucket_Name';
  15. $key = '1.mp4';
  16.  
  17. //转码是使用的队列名称
  18. $pipeline = 'abc';
  19. $pfop = new PersistentFop($auth, $bucket, $pipeline);
  20.  
  21. //要进行转码的转码操作
  22. $fops = "avthumb/mp4/s/640x360/vb/1.25m";
  23.  
  24. list($id, $err) = $pfop->execute($key, $fops);
  25. echo "\n====> pfop avthumb result: \n";
  26. if ($err != null) {
  27. var_dump($err);
  28. } else {
  29. echo "PersistentFop Id: $id\n";
  30. }
  31.  
  32. //查询转码的进度和状态
  33. list($ret, $err) = $pfop->status($id);
  34. echo "\n====> pfop avthumb status: \n";
  35. if ($err != null) {
  36. var_dump($err);
  37. } else {
  38. var_dump($ret);
  39. }

Tips:上面的Demo只是针对视频转码功能,如果您需要使用比如音视频切片、视频截图、视频拼接等功能只需要修改上面 fops 后面的参数即可,如:$fops = vframe/jpg/offset/1/w/480/h/360/rotate/90 就表示视频截图了。

通过上面的代码我们就可以触发将存储在空间中的视频从 mp4 格式转换成 m3u8 格式,并设置分辨率和视频码率。 但这个只是将转码这个耗时的操作提交到队列中,要想知道转码操作现在的状态,需要根据返回的 persitentId 进行查询。


  1. <?php
  2. require_once 'path_to_sdk/vendor/autoload.php';
  3.  
  4. use Qiniu\Processing\PersistentFop;
  5.  
  6. // 触发持久化处理后返回的 Id
  7. $persistentId = 'z0.564d5f977823de48a85ece59';
  8.  
  9. // 通过persistentId查询该 触发持久化处理的状态
  10. $status = PersistentFop::status($persistentId);
  11.  
  12. var_dump($status);

如果您不方便持续轮询每个异步处理的进度和状态,七牛可以异步处理完成后通知您们的业务服务器。 这样就需要您在视频转码的例子中,初始化 PersistentFop 时添加上 notifyUrl 来通知您们的业务服务器:


  1. //你业务服务器的地址
  2. $notifyUrl = 'http://your.bizhost.com/notify.php';
  3. $pfop = new PersistentFop($auth, $bucket, $pipeline, $notifyUrl);

您的业务服务器需要接收来自七牛的通知:


  1. <?php
  2.  
  3. // 获取notify通知的body信息
  4. $notifyBody = file_get_contents('php://input');
  5.  
  6. // 业务服务器处理通知信息, 这里直接打印在log中
  7. error_log($notifyBody);

我们以视频转码为例子,完整介绍了触发持久化的整个流程。触发持久化本质上是:使用异步队列的方式来处理已上传到七牛的数据资源并将处理的结果持久化到七牛。虽然可以使用触发持久化的方式处理七牛所有的数据处理,但是图片处理等可以同步处理的,建议使用同步处理。关于音视频处理,比如音视频转码音视频切片音视频拼接等较耗时的操作必须使用触发持久化方式,或者在上传凭证中指定处理参数的预转持久化操作。

API参考手册

常见问题

  • $error 保留了请求响应的信息,失败情况下 ret 为 none , 将 $error 打印出来,提交给我们。
  • API 的使用 demo 可以参考 单元测试

相关资源

如果您有任何关于我们文档或产品的建议和想法,欢迎到我们的技术论坛参与讨论。

  • 技术论坛 - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
  • 提交工单 - 如果您的问题不适合在论坛讨论或得不到回答,您也可以提交一个工单,技术支持人员会尽快回复您
  • 博客 - 这里会持续发布市场活动和技术分享文章
  • 微博
  • 常见问题

其他对于 PHP 开发者有用的资源:

贡献代码

  1. Fork

  2. 创建您的特性分支 git checkout -b my-new-feature

  3. 提交您的改动 git commit -am 'Added some feature'

  4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature

  5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

许可证

Copyright (c) 2014 qiniu.com

基于 MIT 协议发布:

以上内容是否对您有帮助? 
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  

普通分类: