管理文件_PHP-SDK_SDK 参考_对象存储 OSS-阿里云

在OSS中，用户可以通过一系列的接口管理存储空间(Bucket)中的文件(Object)，比如ListObjects，DeleteObject，CopyObject，DoesObjectExist等。

提示：

以下场景的完整代码路径：GitHub

列出存储空间中的文件

您可以使用OssClient::listObjects列出存储中间中的文件:

<?php
/**
 * 列出Bucket内所有目录和文件， 根据返回的nextMarker循环调用listObjects接口得到所有文件和目录
 *
 * @param OssClient $ossClient OssClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function listAllObjects($ossClient, $bucket)
{
    //构造dir下的文件和虚拟目录
    for ($i = 0; $i < 100; $i += 1) {
        $ossClient->putObject($bucket, "dir/obj" . strval($i), "hi");
        $ossClient->createObjectDir($bucket, "dir/obj" . strval($i));
    }
    $prefix = 'dir/';
    $delimiter = '/';
    $nextMarker = '';
    $maxkeys = 30;
    while (true) {
        $options = array(
            'delimiter' => $delimiter,
            'prefix' => $prefix,
            'max-keys' => $maxkeys,
            'marker' => $nextMarker,
        );
        var_dump($options);
        try {
            $listObjectInfo = $ossClient->listObjects($bucket, $options);
        } catch (OssException $e) {
            printf(__FUNCTION__ . ": FAILED\n");
            printf($e->getMessage() . "\n");
            return;
        }
        // 得到nextMarker，从上一次listObjects读到的最后一个文件的下一个文件开始继续获取文件列表
        $nextMarker = $listObjectInfo->getNextMarker();
        $listObject = $listObjectInfo->getObjectList();
        $listPrefix = $listObjectInfo->getPrefixList();
        var_dump(count($listObject));
        var_dump(count($listPrefix));
        if ($nextMarker === '') {
            break;
        }
    }
}

上述例子中提到的$options参数说明:

key	说明
delimiter	用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes
prefix	限定返回的object key必须以prefix作为前缀。注意使用prefix查询时，返回的key中仍会包含prefix
max-keys	限定此次返回object的最大数，如果不设定，默认为100，max-keys取值不能大于1000
marker	设定结果从marker之后按字母排序的第一个开始返回

提示：

prefix/delimiter/marker/max-keys都是可选参数。

判断文件是否存在

您可以使用OssClient::doesObjectExist判断文件是否存在：

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

创建虚拟目录

OSS是没有文件夹这个概念的，所有元素都是以Object来存储。创建文件夹本质上来说是创建了一个size为0的Object。对于这个Object可以上传下载，只是控制台会对以”/“结尾的Object以文件夹的方式展示。

<?php
/**
 * 创建虚拟目录
 *
 * @param OssClient $ossClient OSSClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function createObjectDir($ossClient, $bucket) {
    try{
        $ossClient->createObjectDir($bucket, "dir");
    } catch(OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

删除单个文件

您可以使用OssClient::deleteObject删除单个文件：

<?php
/**
 * 删除object
 *
 * @param OssClient $ossClient OSSClient实例
 * @param string $bucket bucket名字
 * @return null
 */
function deleteObject($ossClient, $bucket)
{
    $object = "oss-php-sdk-test/upload-test-object-name.txt";
    try{
        $ossClient->deleteObject($bucket, $object);
    } catch(OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

注意：

文件删除后将无法恢复。

删除多个文件

您可以使用OssClient::deleteObjects批量删除多个文件：

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

拷贝文件

您可以使用OssClient::copyObject拷贝文件：

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

注意：

OssClient::copyObject可以拷贝小于1GB的文件。拷贝一个大于1GB的文件时，请使用OssClient::uploadPartCopy。

修改文件元信息(Object Meta)

文件元信息(Object Meta)，是对用户上传到OSS的文件的属性描述，分为两种：HTTP标准属性（HTTP Headers）和User Meta（用户自定义元信息）。文件元信息可以在各种方式上传或者拷贝文件时进行设置。

HTTP标准属性，Cache-Control、Content-Disposition、Content-Encoding、Content-Language、Expires、Content-Length、Content-Type、Last-Modified等。

为了便于用户对Object进行更多描述。OSS中规定所有以x-oss-meta-为前缀的参数，则视为User Meta比如x-oss-meta-location。一个Object可以有多个类似的参数，但所有的User Meta总大小不能超过8k。这些User Meta信息会在下载文件/获取文件元数据时返回。

更多文件元信息的介绍，请参看文件元信息。

可以通过拷贝操作来实现修改已有文件元信息。如果拷贝操作的源文件地址和目标文件地址相同，都会直接替换源文件的文件元信息。

/**
 * 修改文件元信息
 * 利用copyObject接口的特性：当目的object和源object完全相同时，表示修改object的文件元信息
 *
 * @param OssClient $ossClient OSSClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function modifyMetaForObject($ossClient, $bucket)
{
    $fromBucket = $bucket;
    $fromObject = "oss-php-sdk-test/upload-test-object-name.txt";
    $toBucket = $bucket;
    $toObject = $fromObject;
    $copyOptions = array(
        OssClient::OSS_HEADERS => array(
            'Expires' => '2018-10-01 08:00:00',
            'Content-Disposition' => 'attachment; filename="xxxxxx"',
            'x-oss-meta-location' => 'location',
        ),
    );
    try{
        $ossClient->copyObject($fromBucket, $fromObject, $toBucket, $toObject, $copyOptions);
    } catch(OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

提示：

通过修改文件的Content-Type，可以修改文件的类型。
通过修改文件的Content-Disposition，可以控制文件的下载行为。

获取文件的文件元信息(Object Meta)

您可以使用OssClient::getObjectMeta获取文件的文件元信息：

<?php
/**
 * 获取object meta, 也就是getObjectMeta接口
 *
 * @param OssClient $ossClient OssClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function getObjectMeta($ossClient, $bucket)
{
    $object = "oss-php-sdk-test/upload-test-object-name.txt";
    try {
        $objectMeta = $ossClient->getObjectMeta($bucket, $object);
    } catch (OssException $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");
    }
}

设置文件访问权限

Object有四种访问权限：default（默认），private（私有读写）, public-read（公共读私有写）, public-read-write（公共读写），含义如下：

权限	描述	PHP SDK对应值
默认	Objec是遵循Bucket的读写权限，即Bucket是什么权限，Object就是什么权限，Object的默认权限	default
私有读写	Object是私有资源，即只有该Object的Owner拥有该Object的读写权限，其他的用户没有权限操作该Object	private
公共读私有写	Object是公共读资源，即非Object Owner只有Object的读权限，而Object Owner拥有该Object的读写权限	public-read
公共读写	Object是公共读写资源，即所有用户拥有对该Object的读写权限	public-read-write

Object的权限优先级高于Bucket。例如Bucket是private的，而Object ACL是公共读写，则访问这个Object时，先判断Object的ACL，所有用户都拥有这个Object的访问权限，即使这个Bucket是private。如果某个Object从来没设置过ACL，则访问权限遵循Bucket ACL。

您可以使用OssClient::putObjectAcl设置文件的访问权限：

<?php
/**
 * 获取文件范围权限
 *
 * @param OssClient $ossClient OssClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function putObjectAcl($ossClient, $bucket)
{
    $object = "oss-php-sdk-test/upload-test-object-name.txt";
    $acl = "public-read";
    try {
        $ossClient->putObjectAcl($bucket, $object, $acl);
    } catch (OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

获取文件访问权限

您可以使用OssClient::getObjectAcl获取文件的访问权限：

<?php
/**
 * 获取object的访问权限
 *
 * @param OssClient $ossClient OssClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function getObjectMeta($ossClient, $bucket)
{
    $object = "oss-php-sdk-test/upload-test-object-name.txt";
    try {
        $objectAcl = $ossClient->getObjectAcl($bucket, $object);
    } catch (OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
    var_dump($objectAcl);
}

解冻归档存储类型文件

归档object的状态变换过程如下：

归档类型的object初始时处于冷冻状态。
提交解冻（restore）操作后，服务端执行解冻，object处于解冻中状态。
解冻默认时间需要一分钟。
完成解冻后，可以读取文件。
解冻状态默认持续1天，最多延长7天，之后object又回到冷冻状态。

您可以调用OssClient::restoreObject方法进行归档object解冻：

/**
 * 解冻归档类型object
 *
 * @param OssClient $ossClient OssClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function restoreObject($ossClient, $bucket)
{
    $object = "oss-php-sdk-test/archive-test-object-name.txt";
    try {
        $ossClient->restoreObject($bucket, $object);
    } catch (OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

提示：

更详细解释请参看api接口Restore Object。

创建符号链接

符号链接是一种特殊的object，它指向具体的某个object,类似于windows上使用的快捷方式。

您可以调用OssClient::putSymlink方法创建符号链接：

<?php
/**
 * 创建符号链接
 *
 * @param OssClient $ossClient OssClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function putSymlink($ossClient, $bucket)
{
    $symlink = "test-symlink";
    $object = "oss-php-sdk-test/symlink-test-object-name.txt";
    try {
        $ossClient->putSymlink($bucket, $symlink, $object);
    } catch (OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
}

提示：

更详细解释请参看api接口PutSymlink。

获取符号链接所指向的文件内容

用于获取符号链接，此操作要求用户对该符号链接有读权限。

您可以调用OssClient::getSymlink方法获取symlink所指向的的object内容：

<?php
/**
 * 获取符号链接所指向的object内容
 *
 * @param OssClient $ossClient OssClient实例
 * @param string $bucket 存储空间名称
 * @return null
 */
function getSymlink($ossClient, $bucket)
{
    $symlink = "test-symlink";
    try {
        $Symlinks = $ossClient->getSymlink($bucket, $symlink);
    } catch (OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    print(__FUNCTION__ . ": OK" . "\n");
    var_dump($Symlinks);
}

提示：

更详细解释请参看api接口 GetSymlink。