對象存儲 PHP SDK

安裝

SDK

GitHub 地址: https://github.com/NetEase-Object-Storage/nos-php-sdk

ChangLog: https://github.com/NetEase-Object-Storage/nos-php-sdk/blob/master/README.md

曆史版本: 無

環境要求

php5.3+ 使用以下命令顯示當前的 php 版本:

php -v

cURL 擴展使用以下命令查看 curl 擴展是否已經安裝好:

php -m

Windows下用戶，請參考 Windows下使用NOS PHP SDK

安裝

composer方式

如果您通過 composer 管理您的項目依賴，可以在你的項目根目錄運行:

composer require netease/nos-php-sdk

或者在你的 composer.json 中聲明對 NOS SDK for PHP 的依賴:

"require": {
"netease/nos-php-sdk": "1.0.0"
}

然後通過 conposer install 安裝依賴，安裝完成後形成如下目錄結構:

.
├── app.php
├── composer.json
├── composer.lock
└── vendor

其中 app.php 是用戶的應用程序，vendor/ 目錄下包含了所依賴的庫，用戶需要在 app.php 中引入如下依賴:

require_once __DIR__ . '/vendor/autoload.php';

1. 如果項目中已經引用過 autoload.php，則加入了 sdk 依賴之後，不需要再引入 autoload.php 了
2. 如果使用 composer 出現網絡錯誤，可以使用 composer 中國區的鏡像源，方法是在命令行執行: composer config -g repositories.packagist composer https://packagist.phpcomposer.com

phar 方式

使用 phar 單文件方式，可以在以下鏈接,下載已經打好包的 phar 文件，或者根據源文件自行編譯，然後在你的源代碼中引入 phar 文件:

require_once '/path/to/nos-sdk-php.phar';

源碼方式

使用 SDK 源碼，在發布頁麵，選擇相應的版本，下載打好包的 zip 文件，解壓後的根目錄中包含一個 autoload.php 文件，在您的代碼中引入這個文件:

require_once '/path/to/nos-sdk/autoload.php';

運行 Samples

解壓下載到的 sdk 包

修改samples目錄中的 Config.php 文件

1. 修改 NOS_ACCESS_ID, 您從 NOS 獲得的AccessKeyId

2. 修改 NOS_ACCESS_KEY, 您從 NOS 獲得的AccessKeySecret

3. 修改 NOS_ENDPOINT, 您選定的 NOS 數據中心訪問域名，例如: nos-eastchina1.126.net

4. 修改 NOS_TEST_BUCKET, 您要用來運行 sample 使用的 bucket，sample 程序會在這個bucket中創建一些文件,注意不能用生產環境的 bucket，以免汙染用戶數據

到 samples 目錄中執行 php RunAll.php，也可以單個運行某個 Sample 文件

初始化

確定 EndPoint

EndPoint 是 NOS 各個區域的地址，目前支持以下形式

EndPoint 類型	備注
NOS區域域名地址	使用桶所在的區域的NOS域名地址

NOS 區域域名地址

進入 NOS 控製台，在桶的屬性中可以查找到當前桶所在的區域及域名，桶的域名的後綴部分為該桶的公網域名，例如: test-logging.nos-eastchina1.126.net 中的 nos-eastchina1.126.net 為該桶的公網 EndPoint 。

配置秘鑰

要接入 NOS 服務，您需要一對有效的 AccessKey（包括 AccessKeyId 與 AccessKeySecret）來進行簽名驗證，開通服務與 AccessKey 請參考訪問控製

在獲取到 AccessKeyId 與 AccessKeySecret 之後，可以按照以下的步驟進行初始化

新建 NosClient

使用 NOS 地區域名創建 NosClient

初始化代碼如下所示:

<?php
use NOS\NosClient;
use NOS\Core\NosException;

$accessKeyId = "您的accessKeyId";
$accessKeySecret = "您的accessKeySecret";
$endPoint = "建桶時選擇的的區域域名";

try{
        $nosClient = new NosClient($accessKeyId,$accessKeySecret,$endPoint);
} catch(NosException e){
        print e->getMessage();
}

設置網絡參數

我們可以通過 Client 設置一些基本的網絡參數:

<?php
$nosClient->setTimeout(3600 /* seconds */);
$nosClient->setConnectTimeout(10 /* seconds */);

其中:

setTimeout 設置請求超時時間，單位秒，默認是 5184000 秒, 這裏建議不要設置太小，如果上傳文件很大，消耗的時間會比較長
setConnectTimeout 設置連接超時時間，單位秒，默認是10秒

快速入門

請確認您已經熟悉 NOS 的基本概念，如 Bucket、Object 、EndPoint 、AccessKeyId 和 AccessKeySecret 等。本節您將看到如何快速的使用 NOS PHP SDK ,完成常用的操作，創建桶、上傳文件、下載文件等。

常用類

常用類	備注
NOSNosClient	NOS 客戶端類，用戶通過NosClient調用服務
NOSCoreNosException	NOS異常，在調用過程中去捕獲這個異常，查看失敗原因

基本操作

創建桶

您可以使用以下代碼新建一個桶:

<?php
use NOS\NosClient;
use NOS\Core\NosException;

$accessKeyId = "您的accessKeyId";
$accessKeySecret = "您的accessKeySecret";
$endPoint = "建桶時選擇的的區域域名";
$bucket = "使用的桶名，注意命名規則";

try{
        $nosClient = new NosClient($accessKeyId,$accessKeySecret,$endPoint);
        $nosClient->createBucket($bucket);
} catch(NosException e){
        print e->getMessage();
}

Attention:

 桶名命名規則請參見 API 手冊桶命名規範

更多的關於bucket的操作的信息，請參見 NOS-PHP-SDK Bucket管理

上傳文件

對象（Object）是 NOS 中最基本的數據單元，您可以把它簡單的理解為文件，以下代碼可以實現簡單的對象上傳:

<?php
use NOS\NosClient;
use NOS\Core\NosException;

$accessKeyId = "您的accessKeyId";
$accessKeySecret = "您的accessKeySecret";
$endPoint = "建桶時選擇的的區域域名";
$bucket = "使用的桶名，注意命名規則";
$object = "使用的對象名，注意命名規則";
$content = "Hello NOS!";
try{
        $nosClient = new NosClient($accessKeyId,$accessKeySecret,$endPoint);
        $nosClient->putObject($bucket,$object,$content);
} catch(NosException e){
        print e->getMessage();
}

Attention: 對象命名規則請參見 API 手冊對象

更多的上傳文件信息，請參見 NOS-PHP-SDK 上傳文件

下載文件

上傳對象成功之後，您可以讀取它的內容，以下代碼可以實現文件的下載:

<?php
use NOS\NosClient;
use NOS\Core\NosException;

$accessKeyId = "您的accessKeyId";
$accessKeySecret = "您的accessKeySecret";
$endPoint = "建桶時選擇的的區域域名";
$bucket = "使用的桶名，注意命名規則";
$object = "使用的對象名，注意命名規則";

try{
        $nosClient = new NosClient($accessKeyId,$accessKeySecret,$endPoint);
        $content = $nosClient->getObject($bucket,$object);
        print("object content: " . $content);
} catch(NosException e){
        print e->getMessage();
}

列舉文件

當上傳文件成功之後，可以查看桶中包含的文件列表，以下代碼展示如何列舉桶內的文件:

<?php
use NOS\NosClient;
use NOS\Core\NosException;

$accessKeyId = "您的accessKeyId";
$accessKeySecret = "您的accessKeySecret";
$endPoint = "建桶時選擇的的區域域名";
$bucket = "使用的桶名，注意命名規則";

try{
        $nosClient = new NosClient($accessKeyId,$accessKeySecret,$endPoint);
        $listObjectInfo = $nosClient->listObjects($bucket);
        if (!empty($objectList)) {
                foreach ($objectList as $objectInfo) {
                        print($objectInfo->getKey() . "\t" . $objectInfo->getSize() . "\t" . $objectInfo->getLastModified() . "\n");
                }
        }
} catch(NosException e){
        print e->getMessage();
}

Note;

 上麵的代碼默認列舉100個object

更多的管理文件信息，請參見NOS-PHP-SDK 文件管理

刪除文件

文件上傳成功後，可以指定刪除桶中的文件，以下代碼實現桶中文件的刪除:

<?php
use NOS\NosClient;
use NOS\Core\NosException;

$accessKeyId = "您的accessKeyId";
$accessKeySecret = "您的accessKeySecret";
$endPoint = "建桶時選擇的的區域域名";
$bucket = "使用的桶名，注意命名規則";
$object = "使用的對象名，注意命名規則";

try{
        $nosClient = new NosClient($accessKeyId,$accessKeySecret,$endPoint);
        $content = $nosClient->deleteObject($bucket,$object);
} catch(NosException e){
        print e->getMessage();
}

返回結果處理

NosClient中的接口對應返回數據分為兩類:

Put，Delete 類接口返回 null，如果沒有 NosException，即可認為操作成功
Get，List 類接口返回對應的數據，如果沒有 NosException，即可認為操作成功

例如:

<?php
$bucketListInfo = $nosClient->listBuckets();
$bucketList = $bucketListInfo->getBucketList();
foreach($bucketList as $bucket) {
    print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n");
}

上麵代碼中的 $bucketListInfo 的數據類型是 NOS\Model\BucketListInfo

桶的管理

桶是 NOS 上的存儲空間，也是計費、權限控製、日誌記錄等高級功能的管理實體。

新建桶

您可以使用 NosClient::createBucket 新建桶：

<?php
/**
 * 創建一個桶
 * acl 指的是bucket的訪問控製權限，有兩種，私有讀寫，公共讀私有寫。
 * 私有讀寫就是隻有bucket的擁有者或授權用戶才有權限操作
 * 公共讀私有寫，任意用戶可以讀，隻有授權用戶才能寫
 * 兩種權限分別對應NosClient::NOS_ACL_TYPE_PRIVATE，
 *               NosClient::NOS_ACL_TYPE_PUBLIC_READ,
 *
 * @param NosClient $nosClient NosClient實例
 * @param string    $bucket 要創建的bucket名字
 * @return null
 */
function createBucket($nosClient, $bucket)
{
    try {
        $nosClient->createBucket($bucket, NosClient::NOS_ACL_TYPE_PRIVATE);
    } catch (NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

Attention：

 1. 桶的命名規範，請參見 基本概念 桶命名規範 

 2. 桶的名字全局唯一，不同用戶之間的桶名也不能重複

 3. 關於權限更加詳細的說明，請參見: 桶的屬性

判斷桶是否存在

您可以使用 NosClient::doesBucketExist 判斷桶是否存在:

<?php
/**
 *  判斷Bucket是否存在
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 桶名稱
 */
function doesBucketExist($nosClient, $bucket)
{
    try {
        $res = $nosClient->doesBucketExist($bucket);
    } catch (NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    if ($res === true) {
        print(__FUNCTION__ . ": OK" . "\n");
    } else {
        print(__FUNCTION__ . ": FAILED" . "\n");
    }
}

列出用戶所有的桶

您可以使用 NosClient::listBuckets 列出當前用戶所有的桶:

<?php
/**
 * 列出用戶所有的Bucket
 *
 * @param NosClient $nosClient NosClient實例
 * @return null
 */
function listBuckets($nosClient)
{
    $bucketList = null;
    try{
        $bucketListInfo = $nosClient->listBuckets();
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    $bucketList = $bucketListInfo->getBucketList();
    foreach($bucketList as $bucket) {
        print($bucket->getName() . "\t" . $bucket->getCreatedate() . "\n");
    }
}

刪除桶

您可以使用NosClient::deleteBucket 刪除空桶:

<?php
/**
 * 刪除存儲空間
 *
 * @param NosClient $nosClient NosClient實例
 * @param string    $bucket 待刪除的桶名稱
 * @return null
 */
function deleteBucket($nosClient, $bucket)
{
    try{
        $nosClient->deleteBucket($bucket);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

Attention:

 1. 如果存儲空間不為空（存儲空間中有文件或者分片上傳的分片），則存儲空間無法刪除；

 2. 必須先刪除存儲空間中的所有文件和分片後，存儲空間才能成功刪除。

設置桶的ACL屬性

除了在創建桶的時候可以指定桶的ACL屬性之外，也可以根據自己的業務需求對桶的ACL進行修改，這個操作隻有桶的擁有者有權限修改，關於桶的權限修改請參考: 桶的屬性修改
桶存在兩種權限：

權限	備注
私有讀寫	NosClient::NOS_ACL_TYPE_PRIVATE
公共讀私有寫	NosClient::NOS_ACL_TYPE_PUBLIC_READ

您可以使用 NosClient::putBucketAcl 設置桶的訪問權限:

<?php
/**
 * 設置bucket的acl配置
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 桶名稱
 * @return null
 */
function putBucketAcl($nosClient, $bucket)
{
    $acl = NosClient::NOS_ACL_TYPE_PRIVATE;
    try {
        $nosClient->putBucketAcl($bucket, $acl);
    } catch (NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

獲取桶的ACL屬性

您可以使用 NosClient::getBucketAcl 獲取桶的訪問權限:

<?php
/**
 * 獲取bucket的acl配置
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 桶名稱
 * @return null
 */
function getBucketAcl($nosClient, $bucket)
{
    try {
        $res = $nosClient->getBucketAcl($bucket);
    } catch (NosException $e) {

        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
    print('acl: ' . $res);
}

獲取桶所處的分區

您可以使用 NosClient::getBucketLocation 獲取桶所處的分區:

<?php
/**
 * 獲取bucket的location配置
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 桶名稱
 * @return null
 */
function getBucketAcl($nosClient, $bucket)
{
    try {
        $res = $nosClient->getLocation($bucket);
    } catch (NosException $e) {

        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
    print('location: ' . $res);
}

文件上傳

在 NOS 中用戶的基本操作單元是對象，亦可以理解為文件，NOS PHP SDK提供了豐富的上傳接口，可以通過以下的方式上傳文件:

字符串上傳
本地文件上傳
分片上傳

字符串上傳、本地文件上傳最大為100M，分片上傳沒有限製

字符串上傳

您可以使用 NosClient::putObject 上傳字符串內容到文件中，具體實現如下:

<?php
/**
 * 上傳字符串作為object的內容
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function putObject($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    $content = file_get_contents(__FILE__);
    try{
        $nosClient->putObject($bucket, $object, $content);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

本地文件上傳

您可以使用 NosClient::uploadFile 上傳文件內容，具體實現如下:

<?php
/**
 * 上傳指定的本地文件內容
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function uploadFile($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    $filePath = __FILE__;
    try{
        $nosClient->uploadFile($bucket, $object, $filePath);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

Attention:

 1. 上傳的文件內容不超過100M

分片上傳

除了通過putObject接口上傳文件到NOS之外，NOS還提供了另外一種上傳模式-分片上傳,用戶可以在如下應用場景內（但不限於此），使用分片上傳模式，如：

需支持斷點上傳
上傳超過100M的文件
網絡條件較差，經常和NOS服務器斷開連接
上傳文件之前無法確定文件的大小

分片上傳本地文件

您可以使用 NosClient::multiuploadFile 來上傳一個文件，該方法封裝了細節，會根據傳入的文件及分片的大小自動選擇上傳方式,對於分片大小小於文件大下的情況下會使用分片上傳:

<?php
/**
 * 通過multipart上傳文件
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function multiuploadFile($nosClient, $bucket)
{
    $object = "test/multipart-test.txt";
    $file = __FILE__;
    try{
        $nosClient->multiuploadFile($bucket, $object, $file);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ":  OK" . "\n");
}

Attention:

 1. 默認的分片大小為5M

原始接口分片上傳

您可以使用原始的分片上傳接口進行分片上傳，一般流程如下所示:

初始化一個分片上傳任務(InitiateMultipartUpload)
逐個或並行上傳分片(UploadPart)
完成分片上傳(CompleteMultipartUpload)或者取消分片上傳(AbortMultipartUpload)

下麵通過一個完整的示例說明了如何通過原始的api接口一步一步的進行分片上傳操作，如果用戶需要做斷點續傳等高級操作，可以參考下麵代碼:

<?php
/**
 * 使用基本的api分階段進行分片上傳
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @throws NosException
 */
function putObjectByRawApis($nosClient, $bucket)
{
    $object = "test/multipart-test.txt";
    /**
     *  step 1. 初始化一個分塊上傳事件, 也就是初始化上傳Multipart, 獲取upload id
     */
    try{
        $uploadId = $nosClient->initiateMultipartUpload($bucket, $object);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": initiateMultipartUpload FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": initiateMultipartUpload OK" . "\n");
    /*
     * step 2. 上傳分片
     */
    // 分片大小10M
    $partSize = 10 * 1024 * 1024;
    $uploadFile = __FILE__;
    $uploadFileSize = filesize($uploadFile);
    $pieces = $nosClient->generateMultiuploadParts($uploadFileSize, $partSize);
    $responseUploadPart = array();
    $uploadPosition = 0;
    $isCheckMd5 = true;
    foreach ($pieces as $i => $piece) {
        $fromPos = $uploadPosition + (integer)$piece[NosClient::NOS_SEEK_TO];
        $toPos = (integer)$piece[NosClient::NOS_LENGTH] + $fromPos - 1;
        $upOptions = array(
            $nosClient::NOS_FILE_UPLOAD => $uploadFile,
            $nosClient::NOS_PART_NUM => ($i + 1),
            $nosClient::NOS_SEEK_TO => $fromPos,
            $nosClient::NOS_LENGTH => $toPos - $fromPos + 1,
            $nosClient::NOS_CHECK_MD5 => $isCheckMd5,
        );
        if ($isCheckMd5) {
            $contentMd5 = NosUtil::getMd5SumForFile($uploadFile, $fromPos, $toPos);
            $upOptions[$nosClient::NOS_CONTENT_MD5] = $contentMd5;
        }
        //2. 將每一分片上傳到 NOS
        try {
            $responseUploadPart[] = $nosClient->uploadPart($bucket, $object, $uploadId, $upOptions);
        } catch(NosException $e) {
            printf(__FUNCTION__ . ": initiateMultipartUpload, uploadPart - part#{$i} FAILED\n");
            printf($e->getMessage() . "\n");
            return;
        }
        printf(__FUNCTION__ . ": initiateMultipartUpload, uploadPart - part#{$i} OK\n");
    }
    $uploadParts = array();
    foreach ($responseUploadPart as $i => $eTag) {
        $uploadParts[] = array(
            'PartNumber' => ($i + 1),
            'ETag' => $eTag,
        );
    }
    /**
     * step 3. 完成上傳
     */
    try {
        $nosClient->completeMultipartUpload($bucket, $object, $uploadId, $uploadParts);
    }  catch(NosException $e) {
        printf(__FUNCTION__ . ": completeMultipartUpload FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    printf(__FUNCTION__ . ": completeMultipartUpload OK\n");
}

Attention:
1. 上麵程序一共分為三個步驟：1. initiate 2. uploadPart 3. complete
2. UploadPart 方法要求除最後一個Part以外，其他的Part大小都要大於或等於5M。但是Upload Part接口並不會立即校驗上傳Part的大小（因為不知道是否為最後一塊）；隻有當Complete Multipart Upload的時候才會校驗。
3. Part號碼的範圍是1~10000。如果超出這個範圍，NOS 將返回InvalidArgument的錯誤碼。
4. 每次上傳Part時都要把流定位到此次上傳塊開頭所對應的位置。
5. 分片上傳任務初始化或上傳部分分片後，可以使用abortMultipartUpload接口中止分片上傳事件。當分片上傳事件被中止後，就不能再使用這個Upload ID做任何操作，已經上傳的分片數據也會被刪除。
6. 每次上傳Part之後，NOS 的返回結果會包含一個 PartETag 對象，它是上傳塊的ETag與塊編號（PartNumber）的組合。在後續完成分片上傳的步驟中會用到它，因此我們需要將其保存起來，然後在第三步complete的時候使用，具體操作參考上麵代碼。

查看已經上傳的分片

查看已經上傳的分片可以羅列出指定 Upload ID ( InitiateMultipartUpload 時獲取)所屬的所有已經上傳成功的分片，您可以通過 NosClient::listParts 接口獲取已經上傳的分片，可以參考以下代碼:

 /**
    * 查看已上傳的分片
    *
    * @param NosClient $nosClient NosClient實例
    * @param string $bucket 存儲空間名稱
    * @param string $uploadId  upload Id
    * @return null
    */
   function listParts($nosClient, $bucket, $uploadId)
   {
       $object = "nos-php-sdk-test/upload-test-object-name.txt";
       try{
           $options = array();
           $options['max-parts'] = 100;
           $optiosn['part-number-marker'] = '10';
           $listPartsInfo = $nosClient->listParts($bucket, $object, $upload_id,$options);
           foreach ($listPartsInfo->getListPart() as $partInfo) {
               print($partInfo->getPartNumber() . "\t" . $partInfo->getSize() . "\t" . $partInfo->getETag() . "\t" . $partInfo->getLastModified() . "\n");
           }
       } catch(NosException $e) {
           printf(__FUNCTION__ . ": FAILED\n");
           printf($e->getMessage() . "\n");
           return;
       }
       print(__FUNCTION__ . ": OK" . "\n");
   }

查看已經上傳的分片可以指定以下參數:

參數	描述
max-parts	響應中的limit個數類型：整型
part-number-marker	分塊號的界限，隻有更大的分塊號會被列出來。類型：字符串

查看當前正在進行的分片上傳任務

查看正在進行的分片上傳任務可以羅列出正在進行，還未完成的分片上傳任務，您可以通過 NosClient::listMultipartUploads 接口當前的上傳任務，可以參考以下代碼:

<?php
/**
 * 獲取當前未完成的分片上傳列表
 *
 * @param $nosClient NosClient
 * @param $bucket   string
 */
function listMultipartUploads($nosClient, $bucket) {
    $options = array(
                'max-uploads' => 100,
                'key-marker' => ''
            );
    try {
        $listMultipartUploadInfo = $nosClient->listMultipartUploads($bucket, $options);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": listMultipartUploads FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    printf(__FUNCTION__ . ": listMultipartUploads OK\n");
    $listUploadInfo = $listMultipartUploadInfo->getUploads();
    var_dump($listUploadInfo);
}

上述代碼中使用的options參數如下:

參數值	描述
key-marker	指定某一uploads key，隻有大於該key-marker的才會被列出
max-uploads	最多返回max-uploads條記錄,默認1000

設置文件元信息

文件元數據( object meta )，是上傳到 NOS 的文件屬性描述信息:分為 http 標準屬性和用戶自定義元數據。文件元信息可以在各種上傳方式(字符串上傳、文件上傳、分片上傳)或 copy 文件時進行設置，元數據大小寫不敏感。

設定http header NOS 允許用戶自定義http Header。http header相關信息請參考 RFC2616，幾個常用的header說明如下:

名稱	描述
Content-MD5	文件數據校驗，設置了該值後 NOS 會啟用文件內容MD5校驗，把您提供的MD5與文件的MD5比較，不一致會拋出錯誤
Content-Type	文件的MIME，定義文件的類型及網頁編碼，決定瀏覽器將以什麼形式、什麼編碼讀取文件。如果用戶沒有指定則根據Key或文件名的擴展名生成，如果沒有擴展名則填默認值
Content-Disposition	指示MINME用戶代理如何顯示附加的文件，打開或下載，及文件名稱
Content-Length	上傳的文件的長度，超過流/文件的長度會截斷，不足為實際值
Expires	緩存過期時間，NOS 未使用，格式是格林威治時間（GMT）
Cache-Control	指定該Object被下載時的網頁的緩存行為

下麵的源代碼實現了上傳文件時設置Http header:

/**
 * 上傳時設置文件的元數據
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function putObject($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    $content = file_get_contents(__FILE__);
    $options = array(
        NosClient::NOS_HEADERS => array(
            'Expires' => '2016-12-12 08:00:00',
            'Content-Disposition' => 'attachment; filename="xxxxxx"',
    ));
    try{
        $nosClient->putObject($bucket, $object, $content, $options);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

用戶自定義元數據

NOS 支持用戶自定義對象元數據，上傳時可以指定對象自定義元數據，數據放在http頭中傳輸，以 x-nos-meta-開頭，以下源代碼實現對象自定義元數據上傳:

<?php
/**
 * 上傳時設置文件的自定義元數據
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function putObject($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    $content = file_get_contents(__FILE__);
    $options = array(NosClient::NOS_HEADERS => array(
        'x-nos-meta-self-define-title' => 'user define meta info',
    ));
    try{
        $nosClient->putObject($bucket, $object, $content, $options);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

上傳時校驗MD5

為了確保 PHP SDK 發送的數 NOS 服務端接收到的數據一致，NOS 支持MD5校驗。文件上傳時（字符串上傳、文件上傳、分片上傳）默認關閉 MD5，如果您需要打開 MD5 校驗，請上傳文件的 options 設置。

下麵的代碼實現了上傳時開啟 MD5 校驗:

<?php
/**
 * 上傳時開啟MD5校驗
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function putObject($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    $options = array(NosClient::NOS_CHECK_MD5 => true);
    try{
        $nosClient->uploadFile($bucket, $object, __FILE__, $options);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

Attention:

 1. 校驗MD5會有一定的性能損失;

文件下載

NOS PHP SDK 提供了豐富的文件下載接口，用戶可以通過以下方式從 NOS 獲取文件:

下載文件到內存
下載到本地文件
分段下載
條件下載

下載文件到內存

以下源代碼實現下載文件到內存中:

<?php
/**
 * 獲取object的內容
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 桶名稱
 * @return null
 */
function getObject($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    try{
        $content = $nosClient->getObject($bucket, $object);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

下載文件到本地文件

<?php
/**
 * get_object_to_local_file
 *
 * 獲取object
 * 將object下載到指定的文件
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function getObjectToLocalFile($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/download-test-object-name.txt";
    $localfile = "download-test-object-name.txt";
    $options = array(
        NosClient::NOS_FILE_DOWNLOAD => $localfile,
    );
    try{
        $nosClient->getObject($bucket, $object, $options);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK, please check localfile: 'upload-test-object-name.txt'" . "\n");
}

範圍下載

如果存儲在NOS中的文件較大，並且您隻需要其中的一部分內容，您可以使用範圍下載，下載指定範圍的數據，如果指定的下載範圍為”0-100”，則返回結果為第0字節到第100字節的數據，返回的數據包含第100字節，即[0,100]，如果指定的範圍無效則下載整個文件，以下源代碼獲取[0,100]字節的內容:

<?php
/**
 * 獲取object的內容
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function getObject($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    try{
        $options = array(NosClient::NOS_RANGE => '0-100');
        $content = $nosClient->getObject($bucket, $object, $options);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

Attention:

 1. 下載內容也可以存儲到文件中
 2. 注意下載的區間為閉區間

條件下載

下載文件時，可以指定限定條件，滿足限定條件時下載，不滿足時報錯，不下載文件。可以使用的限定條件如下：

參數	說明	NosClient對應值
If-Modified-Since	如果指定的時間早於實際修改時間，則正常傳送。否則返回錯誤	NosClient::NOS_IF_MODIFIED_SINCE

<?php
/**
 * 如果文件在指定的時間之後修改過，則下載文件
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function getObject($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    try{
        $options = array(
            NosClient::NOS_HEADERS => array(
                NosClient::NOS_IF_MODIFIED_SINCE => "Fri, 13 Nov 2016 14:47:53 GMT"),
    );
        $content = $nosClient->getObject($bucket, $object， $options);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

Attention:

 1. 下載內容也可以存儲到文件中

文件管理

在NOS中，用戶可以通過一係列的接口管理桶(Bucket)中的文件(Object)，比如ListObjects，DeleteObject，CopyObject，DoesObjectExist等。

列出桶中的文件

您可以使用NosClient::listObjects列出存儲中間中的文件:

<?php
/**
 * 列出Bucket內所有目錄和文件， 根據返回的nextMarker循環調用listObjects接口得到所有文件
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function listAllObjects($nosClient, $bucket)
{
    for ($i = 0; $i < 100; $i += 1) {
        $nosClient->putObject($bucket, "dir/obj" . strval($i), "hi");
    }
    $prefix = 'dir/';
    $delimiter = '/';
    $nextMarker = '';
    $maxkeys = 30;
    while (true) {
        $options = array(
            'delimiter' => $delimiter,
            'prefix' => $prefix,
            'max-keys' => $maxkeys,
            'marker' => $nextMarker,
        );
        var_dump($options);
        try {
            $listObjectInfo = $nosClient->listObjects($bucket, $options);
        } catch (NosException $e) {
            printf(__FUNCTION__ . ": FAILED\n");
            printf($e->getMessage() . "\n");
            return;
        }
        var_dump($listObjectInfo);
        // 得到nextMarker，從上一次listObjects讀到的最後一個文件的下一個文件開始繼續獲取文件列表
        $nextMarker = $listObjectInfo->getNextMarker();
        $listObject = $listObjectInfo->getObjectList();
        var_dump($listObject);
        if ($nextMarker === '') {
            break;
        }
    }

}

上述代碼中的$options中的參數如下所示:

參數	說明
delimiter	用於對Object名字進行分組的字符。所有名字包含指定的前綴且第一次出現delimiter字符之間的object作為一組元素
prefix	限定返回的object key必須以prefix作為前綴。注意使用prefix查詢時，返回的key中仍會包含prefix
max-keys	限定此次返回object的最大數，如果不設定，默認為100
marker	設定結果從marker之後按字母排序的第一個開始返回

Note：

上述表中的參數都是可選參數

判斷文件是否存在

您可以使用NosClient::doesObjectExist判斷文件是否存在:

<?php
/**
 * 判斷object是否存在
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket bucket名字
 * @return null
 */
function doesObjectExist($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    try{
        $exist = $nosClient->doesObjectExist($bucket, $object);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
    var_dump($exist);
}

刪除單個文件

您可以使用NosClient::deleteObject刪除單個需要刪除的文件:

<?php
/**
 * 刪除object
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket bucket名字
 * @return null
 */
function deleteObject($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    try{
        $nosClient->deleteObject($bucket, $object);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

刪除多個文件

您可以使用NosClient::deleteObjects批量刪除文件:

<?php
/**
 * 批量刪除object
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket bucket名字
 * @return null
 */
function deleteObjects($nosClient, $bucket)
{
    $objects = array();
    $objects[] = "nos-php-sdk-test/upload-test-object-name.txt";
    $objects[] = "nos-php-sdk-test/upload-test-object-name.txt.copy";
    try{
        $nosClient->deleteObjects($bucket, $objects);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

拷貝文件

您可以使用NosClient::copyObject拷貝文件:

<?php
/**
 * 拷貝object
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket bucket名字
 * @return null
 */
function copyObject($nosClient, $bucket)
{
    $from_bucket = $bucket;
    $from_object = "nos-php-sdk-test/upload-test-object-name.txt";
    $to_bucket = $bucket;
    $to_object = $from_object . '.copy';
    try{
        $nosClient->copyObject($from_bucket, $from_object, $to_bucket, $to_object);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

Attention:

 1. 支持跨桶的文件copy

移動文件

您可以使用NosClient::moveObject移動文件:

<?php
/**
 * 移動Object
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket bucket名字
 * @return null
 */
function copyObject($nosClient, $bucket)
{
    $from_bucket = $bucket;
    $from_object = "nos-php-sdk-test/upload-test-object-name.txt";
    $to_bucket = $bucket;
    $to_object = $from_object . '.move';
    try{
        $nosClient->moveObject($from_bucket, $from_object, $to_bucket, $to_object);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

Attention:

 1. 暫時不支持跨桶的文件move

修改文件元信息

暫時不提供此類方法

獲取文件的文件元信息

您可以使用NosClient::getObjectMeta獲取對象的元數據信息:

<?php
/**
 * 獲取object meta, 也就是getObjectMeta接口
 *
 * @param NosClient $nosClient NosClient實例
 * @param string $bucket 存儲空間名稱
 * @return null
 */
function getObjectMeta($nosClient, $bucket)
{
    $object = "nos-php-sdk-test/upload-test-object-name.txt";
    try {
        $objectMeta = $nosClient->getObjectMeta($bucket, $object);
    } catch (NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
    if (isset($objectMeta[strtolower('Content-Disposition')]) &&
        'attachment; filename="xxxxxx"' === $objectMeta[strtolower('Content-Disposition')]
    ) {
        print(__FUNCTION__ . ": ObjectMeta checked OK" . "\n");
    } else {
        print(__FUNCTION__ . ": ObjectMeta checked FAILED" . "\n");
    }
}

Attention:

 1. 獲取的元數據通過一個array返回，返回值為HTTP頭類型的元數據與用戶自定義元數據
 2. 元數據名的大小均為小寫

授權訪問

通過生成簽名URL的形式提供給用戶一個臨時的訪問URL。在生成URL時，您可以指定URL過期的時間，從而限製用戶長時間訪問。

生成私有下載鏈接生成 GetObject 的簽名 url 示例如下:

<?php
/**
 * 生成GetObject的簽名url,主要用於私有權限下的讀訪問控製
 *
 * @param $nosClient NosClient NosClient實例
 * @param $bucket string bucket名稱
 * @return null
 */
function getSignedUrlForGettingObject($nosClient, $bucket)
{
    $object = "test/test-signature-test-upload-and-download.txt";
    $timeout = 3600; // URL的有效期是3600秒
    try{
        $signedUrl = $nosClient->signUrl($bucket, $object, $timeout);
    } catch(NosException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": signedUrl: " . $signedUrl. "\n");
    /**
     * 可以類似的代碼來訪問簽名的URL，也可以輸入到瀏覽器中去訪問
     */
    $request = new RequestCore($signedUrl);
    $request->set_method('GET');
    $request->send_request();
    $res = new ResponseCore($request->get_response_header(), $request->get_response_body(), $request->get_response_code());
    if ($res->isOK()) {
        print(__FUNCTION__ . ": OK" . "\n");
    } else {
        print(__FUNCTION__ . ": FAILED" . "\n");
    };
}

最後更新：2017-01-03 10:48:53

對象存儲 PHP SDK

目錄

安裝

初始化

快速入門

桶的管理

文件上傳

文件下載

文件管理

授權訪問

上一篇：新疆地區管局規則

下一篇： CLI控製台

相關內容

熱門內容

最新內容

對象存儲 PHP SDK

目錄

安裝

初始化

快速入門

桶的管理

文件上傳

文件下載

文件管理

授權訪問

上一篇： 新疆地區管局規則

下一篇： CLI控製台

相關內容

熱門內容

最新內容

上一篇：新疆地區管局規則