对象存储

  • PHP SDK历史文档

    最近更新时间:2017-01-23 10:32:48

    此 SDK 适用于 PHP 5.1.0 及其以上版本。

    SDK源码地址:https://github.com/qiniu/php-sdk/tags

    安装

    获取Access Key 和 Secret Key

    要接入七牛云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

    1. 开通七牛开发者帐号
    2. 登录七牛开发者自助平台,查看 Access Key 和 Secret Key

    空间资源管理

    查看单个文件属性信息

    示例代码如下:

    require_once("qiniu/rs.php");
    
    $bucket = "phpsdk";
    $key = "pic.jpg";
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
    	
    Qiniu_SetKeys($accessKey, $secretKey);
    $client = new Qiniu_MacHttpClient(null);
    
    list($ret, $err) = Qiniu_RS_Stat($client, $bucket, $key);
    echo "Qiniu_RS_Stat result: \n";
    if ($err !== null) {
    	var_dump($err);
    } else {
    	var_dump($ret);
    }
    

    复制单个文件

    示例代码如下:

    require_once("qiniu/rs.php");
    
    $bucket = "phpsdk";
    $key = "pic.jpg";
    $key1 = "file_name1";
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
    	
    Qiniu_SetKeys($accessKey, $secretKey);
    $client = new Qiniu_MacHttpClient(null);
    	
    $err = Qiniu_RS_Copy($client, $bucket, $key, $bucket, $key1);
    echo "====> Qiniu_RS_Copy result: \n";
    if ($err !== null) {
    	var_dump($err);
    } else {
    	echo "Success!";
    }
    

    移动单个文件

    示例代码如下:

    require_once("qiniu/rs.php");
    
    $bucket = "phpsdk";
    $key = "pic.jpg";
    $key1 = "file_name1";
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
    	
    Qiniu_SetKeys($accessKey, $secretKey);
    $client = new Qiniu_MacHttpClient(null);
    	
    $err = Qiniu_RS_Move($client, $bucket, $key, $bucket, $key1);
    echo "====> Qiniu_RS_Move result: \n";
    if ($err !== null) {
    	var_dump($err);
    } else {
    	echo "Success!";
    }
    

    删除单个文件

    示例代码如下:

    require_once("qiniu/rs.php");
        
    $bucket = "phpsdk";
    $key1 = "file_name1";
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
        
    Qiniu_SetKeys($accessKey, $secretKey);
    $client = new Qiniu_MacHttpClient(null);
        
    $err = Qiniu_RS_Delete($client, $bucket, $key1);
    echo "====> Qiniu_RS_Delete result: \n";
    if ($err !== null) {
        var_dump($err);
    } else {
        echo "Success!";
    }
    

    上传下载接口

    文件上传

    为了尽可能地改善终端用户的上传体验,七牛云存储首创了客户端直传功能。一般云存储的上传流程是:

    客户端(终端用户) => 业务服务器 => 云存储服务
    

    这样多了一次上传的流程,和本地存储相比,会相对慢一些。但七牛引入了客户端直传,将整个上传过程调整为:

    客户端(终端用户) => 七牛 => 业务服务器
    

    客户端(终端用户)直接上传到七牛的服务器,通过DNS智能解析,七牛会选择到离终端用户最近的ISP服务商节点,速度会比本地存储快很多。文件上传成功以后,七牛的服务器使用回调功能,只需要将非常少的数据(比如Key)传给应用服务器,应用服务器进行保存即可。

    上传流程

    在七牛云存储中,整个上传流程大体分为这样几步:

    1. 业务服务器颁发上传凭证给客户端(终端用户)
    2. 客户端凭借上传凭证上传文件到七牛
    3. 在七牛获得完整数据后,发起一个 HTTP 请求回调到业务服务器
    4. 业务服务器保存相关信息,并返回一些信息给七牛
    5. 七牛原封不动地将这些信息转发给客户端(终端用户)

    注意:回调到业务服务器的过程是可选的,它取决于业务服务器颁发的上传凭证。

    如果没有回调,七牛会返回一些标准的信息(比如文件的 hash)给客户端。如果上传发生在业务服务器,以上流程可以自然简化为:

    1. 业务服务器生成 uptoken(不设置回调,自己回调到自己这里没有意义)
    2. 凭借上传凭证上传文件到七牛
    3. 善后工作,比如保存相关的一些信息

    服务端生成 上传凭证代码如下:

    require_once("qiniu/rs.php");
        
    $bucket = 'phpsdk';
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
        
    Qiniu_SetKeys($accessKey, $secretKey);
    $putPolicy = new Qiniu_RS_PutPolicy($bucket);
    $upToken = $putPolicy->Token(null);
    

    上传文件到七牛(通常是客户端完成,但也可以发生在服务端):

    上传字符串

    require_once("qiniu/io.php");
    require_once("qiniu/rs.php");
    	
    $bucket = "phpsdk";
    $key1 = "file_name1";
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
    	
    Qiniu_SetKeys($accessKey, $secretKey);
    $putPolicy = new Qiniu_RS_PutPolicy($bucket);
    $upToken = $putPolicy->Token(null);
    list($ret, $err) = Qiniu_Put($upToken, $key1, "Qiniu Storage!", null);
    echo "====> Qiniu_Put result: \n";
    if ($err !== null) {
    	var_dump($err);
    } else {
    	var_dump($ret);
    }
    

    上传本地文件

    require_once("qiniu/io.php");
    require_once("qiniu/rs.php");
    	
    $bucket = "phpsdk";
    $key1 = "file_name1";
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
    	
    Qiniu_SetKeys($accessKey, $secretKey);
    $putPolicy = new Qiniu_RS_PutPolicy($bucket);
    $upToken = $putPolicy->Token(null);
    $putExtra = new Qiniu_PutExtra();
    $putExtra->Crc32 = 1;
    list($ret, $err) = Qiniu_PutFile($upToken, $key1, __file__, $putExtra);
    echo "====> Qiniu_PutFile result: \n";
    if ($err !== null) {
    	var_dump($err);
    } else {
    	var_dump($ret);
    }
    

    上传策略

    上传凭证实际上是用 AccessKey/SecretKey 进行数字签名的上传策略(Qiniu_RS_PutPolicy),它控制则整个上传流程的行为。让我们快速过一遍你都能够决策啥:

    class Qiniu_RS_PutPolicy
    {
    	public $Scope;				// 必选项。可以是 bucketName 或者 bucketName:key
    	public $CallbackUrl;		// 可选
    	public $CallbackBody;		// 可选
    	public $ReturnUrl;			// 可选, 更贴切的名字是 redirectUrl。
    	public $ReturnBody;			// 可选
    	public $AsyncOps;			// 可选
    	public $EndUser;			// 可选
    	public $Expires;			// 可选。默认是 3600 秒
    	public $PersistentOps;		// 可选。
    	public $PersistentNotifyUrl;	// 如果设置了PersistentOps,必须同时设置此项。
    }
    
    • scope 限定客户端的权限。如果 scope 是 bucket,则客户端只能新增文件到指定的 bucket,不能修改文件。如果 scope 为 bucket:key,则客户端可以修改指定的文件。注意: key必须采用utf8编码,如使用非utf8编码访问七牛云存储将反馈错误
    • callbackUrl 设定业务服务器的回调地址,这样业务服务器才能感知到上传行为的发生。
    • callbackBody 设定业务服务器的回调信息。文件上传成功后,七牛向业务服务器的callbackUrl发送的POST请求携带的数据。支持 魔法变量自定义变量
    • returnUrl 设置用于浏览器端文件上传成功后,浏览器执行303跳转的URL,一般为 HTML Form 上传时使用。文件上传成功后浏览器会自动跳转到 returnUrl?upload_ret=returnBody
    • returnBody 可调整返回给客户端的数据包,支持魔法变量和自定义变量。returnBody 只在没有 callbackUrl 时有效(否则直接返回 callbackUrl 返回的结果)。不同情形下默认返回的 returnBody 并不相同。在一般情况下返回的是文件内容的 hash,也就是下载该文件时的 etag;但指定 returnUrl 时默认的 returnBody 会带上更多的信息。
    • asyncOps 可指定上传完成后,需要自动执行哪些数据处理。这是因为有些数据处理操作(比如音视频转码)比较慢,如果不进行预转可能第一次访问的时候效果不理想,预转可以很大程度改善这一点。
    • persistentOps 可指定音视频文件上传完成后,需要进行的转码持久化操作。asyncOps的处理结果保存在缓存当中,有可能失效。而persistentOps的处理结果以文件形式保存在bucket中,体验更佳。
    • persistentNotifyUrl 音视频转码持久化完成后,七牛的服务器会向用户发送处理结果通知。这里指定的url就是用于接收通知的接口。设置了persistentOps,则需要同时设置此字段。

    关于上传策略更完整的说明,请参考上传凭证。

    文件下载

    七牛云存储上的资源下载分为 公有资源下载 和 私有资源下载 。

    私有(private)是 Bucket(空间)的一个属性,一个私有 Bucket 中的资源为私有资源,私有资源不可匿名下载。

    新创建的空间(Bucket)缺省为私有,也可以将某个 Bucket 设为公有,公有 Bucket 中的资源为公有资源,公有资源可以匿名下载。

    公有资源下载 如果在给bucket绑定了域名的话,可以通过以下地址访问。

    [GET] http://<domain>/<key>
    

    示例代码:

    $key = 'pic.jpg';
    $domain = '7j1xlg.com2.z0.glb.qiniucdn.com';
    //$baseUrl 就是您要访问资源的地址
    $baseUrl = Qiniu_RS_MakeBaseUrl($domain, $key);
    

    其中<domain>是bucket所对应的域名。七牛云存储为每一个bucket提供一个默认域名。默认域名可以到七牛开发者平台中,空间设置的域名设置一节查询。用户也可以将自有的域名绑定到bucket上,通过自有域名访问七牛云存储。

    注意:key必须采用utf8编码,如使用非utf8编码访问七牛云存储将反馈错误

    私有资源下载 私有资源必须通过临时下载授权凭证(downloadToken)下载,如下:

    [GET] http://<domain>/<key>?e=<deadline>&token=<downloadToken>
    

    注意:尖括号不是必需,代表替换项。

    私有下载链接可以使用 SDK 提供的如下方法生成:

    require_once("qiniu/rs.php");
    
    $key = 'pic.jpg';
    $domain = '7j1xlg.com2.z0.glb.qiniucdn.com';
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
        
    Qiniu_SetKeys($accessKey, $secretKey);  
    $baseUrl = Qiniu_RS_MakeBaseUrl($domain, $key);
    $getPolicy = new Qiniu_RS_GetPolicy();
    $privateUrl = $getPolicy->MakeRequest($baseUrl, null);
    echo "====> getPolicy result: \n";
    echo $privateUrl . "\n";
    

    数据处理接口

    七牛支持在云端对图像, 视频, 音频等富媒体进行个性化处理

    图像

    查看图像属性

    require_once("qiniu/rs.php");
    require_once("qiniu/fop.php");
    
    $key = 'pic.jpg';
    $domain = '7j1xlg.com2.z0.glb.qiniucdn.com';
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
    	
    Qiniu_SetKeys($accessKey, $secretKey);	
    //生成baseUrl
    $baseUrl = Qiniu_RS_MakeBaseUrl($domain, $key);
    
    //生成fopUrl
     $imgInfo = new Qiniu_ImageInfo;
     $imgInfoUrl = $imgInfo->MakeRequest($baseUrl);
     	
     //对fopUrl 进行签名,生成privateUrl。 公有bucket 此步可以省去。
     $getPolicy = new Qiniu_RS_GetPolicy();
     $imgInfoPrivateUrl = $getPolicy->MakeRequest($imgInfoUrl, null);
    echo "====> imageInfo privateUrl: \n";
    echo $imgInfoPrivateUrl . "\n";
    

    $imgInfoPrivateUrl粘贴到浏览器地址栏中就可以查看该图像的信息了。

    查看图片EXIF信息

    require_once("qiniu/rs.php");
    require_once("qiniu/fop.php");
    
    $key = 'pic.jpg';
    $domain = '7j1xlg.com2.z0.glb.qiniucdn.com';
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
    	
    Qiniu_SetKeys($accessKey, $secretKey);	
    //生成baseUrl
    $baseUrl = Qiniu_RS_MakeBaseUrl($domain, $key);
    	
    //生成fopUrl
    $imgExif = new Qiniu_Exif;
    $imgExifUrl = $imgExif->MakeRequest($baseUrl);
     	
    //对fopUrl 进行签名,生成privateUrl。 公有bucket 此步可以省去。
     $getPolicy = new Qiniu_RS_GetPolicy();
     $imgExifPrivateUrl = $getPolicy->MakeRequest($imgExifUrl, null);
    echo "====> imageView privateUrl: \n";
    echo $imgExifPrivateUrl . "\n";
    

    生成图片预览

    require_once("qiniu/rs.php");
    require_once("qiniu/fop.php");
    
    $key = 'pic.jpg';
    $domain = '7j1xlg.com2.z0.glb.qiniucdn.com';
    $accessKey = '<YOUR_APP_ACCESS_KEY>';
    $secretKey = '<YOUR_APP_SECRET_KEY>';
    	
    Qiniu_SetKeys($accessKey, $secretKey);	
    //生成baseUrl
    $baseUrl = Qiniu_RS_MakeBaseUrl($domain, $key);
    	
    //生成fopUrl
    $imgView = new Qiniu_ImageView;
    $imgView->Mode = 1;
    $imgView->Width = 60;
    $imgView->Height = 120;
    $imgViewUrl = $imgView->MakeRequest($baseUrl);
     	
    //对fopUrl 进行签名,生成privateUrl。 公有bucket 此步可以省去。
    $getPolicy = new Qiniu_RS_GetPolicy();
    $imgViewPrivateUrl = $getPolicy->MakeRequest($imgViewUrl, null);
    echo "====> imageView privateUrl: \n";
    echo $imgViewPrivateUrl . "\n";
    

    贡献代码

    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 © 2014 qiniu.com

    基于 MIT 协议发布:

    以上内容是否对您有帮助?
  • 提交工单