3. 快速入门¶

请确认您已经熟悉NOS的基本概念，如Bucket、Object、EndPoint、AccessKeyId和AccessKeySecret等。本节您将看到如何快速的使用NOS PHP SDK,完成常用的操作，创建桶、上传文件、下载文件等。

3.1. 常用类¶

常用类	备注
S3Client	S3 客户端类，用户通过NosClient调用服务
AwsException	S3异常，在调用过程中去捕获这个异常，查看失败原因

3.2. 基本操作¶

3.2.1. 创建桶¶

您可以使用以下代码新建一个桶:

<?php
/**
 * 创建一个桶
 * acl 指的是bucket的访问控制权限，有两种，私有读写，公共读私有写。
 * 私有读写就是只有bucket的拥有者或授权用户才有权限操作
 * 公共读私有写，任意用户可以读，只有授权用户才能写
 *
 * @param S3Client  $S3Client S3Client实例
 * @param string    $bucketName 要创建的bucket名字
 * @param string    $Acl,有效的值为private-->write,public-read-->read
 */

function createBucket($s3Client,$bucketName,$Acl){
    try {
        $result = $s3Client->createBucket([
            'Bucket' => $bucketName,
            'ACL' => $Acl
        ]);
    }catch (AwsException $e) {
        // output error message if fails
        echo $e->getMessage() + "\n";
    }
}

Attention

桶名命名规则请参见 API 手册桶命名规范

更多的关于bucket的操作的信息，请参见 S3-PHP-SDK Bucket管理

3.2.2. 上传文件¶

对象（Object）是NOS中最基本的数据单元，您可以把它简单的理解为文件，以下代码可以实现简单的对象上传:

    <?php
/**
* @param $s3Client S3Client实例
* @param $bucketName 桶名
* @param $objectName 对象名
* @param $Body 'mixed type: string|resource|\Guzzle\Http\EntityBodyInterface'
*/
function putObject($s3Client,$bucketName,$objectName,$Body){//Body中传入字符串即可
    try{
        $result = $s3Client->putObject(['Bucket'=>$bucketName,
            'Key'=>$objectName,
            'Body'=>$Body]);
        echo $result;
    } catch (\Aws\Exception\AwsException $exception){
        echo $exception->getMessage();
    }
}

Attention

对象命名规则请参见 API 手册对象

更多的上传文件信息，请参见 S3-PHP-SDK 上传文件

3.2.3. 下载文件¶

上传对象成功之后，您可以读取它的内容，以下代码可以实现文件的下载:

    <?php
/**
* 获取对象
* @param $s3Client S3Client实例
* @param $bucketName 桶名
* @param $objectName 对象名
*/
function getObject($s3Client,$bucketName,$objectName){
    try{
        $result = $s3Client->getObject(['Bucket'=>$bucketName,
            'Key'=>$objectName]);
        // The 'Body' value of the result is an EntityBody object
        echo get_class($result['Body']) . "\n";
        // > Guzzle\Http\EntityBody

        // The 'Body' value can be cast to a string
        echo $result['Body'] . "\n";
        // > Hello!
    } catch (\Aws\Exception\AwsException $e){
        echo $e->getMessage();
    }
}

更多的下载文件信息，请参见 S3-PHP-SDK 下载文件

3.2.4. 列举文件¶

当上传文件成功之后，可以查看桶中包含的文件列表，以下代码展示如何列举桶内的文件:

    <?php
/**
* @param $s3Client S3Client实例
* @param $bucket 桶名
*/
function listAllObjects($s3Client, $bucket){

            try {
                    $listObjectInfo = $s3Client->listObjects(['Bucket'=>$bucket]);
            } catch (AwsException $e) {
                    printf(__FUNCTION__ . ": FAILED\n");
                    printf($e->getMessage() . "\n");
                    return;
            }
            var_dump($listObjectInfo);
            //得到nextMarker，从上一次listObjects读到的最后一个文件的下一个文件开始继续获取文件列表
            $nextMarker = $listObjectInfo['NextMarker'];
            echo "nextMarker" . $nextMarker . "\n";

    }

}

Note

上面的代码默认列举100个object

更多的管理文件信息，请参见 S3-PHP-SDK 文件管理

3.2.5. 删除文件¶

文件上传成功后，可以指定删除桶中的文件，以下代码实现桶中文件的删除:

     <?php
/**
 * @param $nosClient S3Client实例
 * @param $bucketName 桶名
 * @param $objectName 对象名
 */
 function deleteObject($s3Client, $bucketName,$objectName)
 {
     try{
         $s3Client->deleteObject(['Bucket'=>$bucketName, 'Key'=>$objectName]);
     } catch(AwsException $e) {
         printf(__FUNCTION__ . ": FAILED\n");
         printf($e->getMessage() . "\n");
         return;
     }
     print(__FUNCTION__ . ": OK" . "\n");
 }

3.2.6. 返回结果处理¶

NosClient中的接口对应返回数据分为两类:

Put，Delete类接口返回相应的响应，如果没有AwsException，即可认为操作成功
Get，List类接口返回对应的数据，如果没有AwsException，即可认为操作成功