Manage objects - SDK Reference| Alibaba Cloud Documentation Center

In OSS, you can manage the objects in a bucket using a series of interfaces, such as ListObjects, DeleteObject, CopyObject, and DoesObjectExist.

Note: For complete code, see GitHub.

List objects in a bucket

You can list objects in the bucket using OssClient::listObjects:

<?php
/**
 * List all directories and objects in a bucket. The listObjects interface is called recursive call according to the returned nextMarker until all objects and directories are listed.
 *
 * @param OssClient $ossClient OssClient instance
 * @param string $bucket Bucket name
 * @return null
 */
function listAllObjects($ossClient, $bucket)
{
    //Construct objects and virtual directories in the dir directory
    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;
        }
        // Obtain nextMarker. The remaining portion of the object list is always retrieved starting with the object next to the last object previously retrieved through the listObjects interface.
        $nextMarker = $listObjectInfo->getNextMarker();
        $listObject = $listObjectInfo->getObjectList();
        $listPrefix = $listObjectInfo->getPrefixList();
        var_dump(count($listObject));
        var_dump(count($listPrefix));
        if ($nextMarker === '') {
            break;
        }
    }
}

The parameters of $options in the preceding code are described as follows:

Key	Description
Delimiter	A character used to group object names. All the objects whose names contain the specified prefix and appear before the delimiter for the first time form a group of elements called CommonPrefixes.
Prefix	The keys of returned objects must use the prefix. Note that when you make a query using the prefix, the returned key still contains the prefix.
max-keys	Specify the maximum number of objects returned for one request. If this parameter is not specified, the default value 100 applies. The max-keys value cannot exceed 1,000.
Marker	Set the returned results to begin from the first entry after the Marker in the alphabetical order.

Note: The prefix, delimiter, marker, and max-keys are all optional parameters.

Identify whether an object exists

You can identify whether an object exists using OssClient::doesObjectExist:

<?php
/**
 * Identify whether an object exists
 *
 * @param OssClient $ossClient OSSClient instance
 * @param string $bucket Bucket name
 * @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);
}

Create a virtual directory

OSS does not use folders. All elements are stored as objects. So, if you create a folder, an object with a size of 0 gets created instead. This object can be uploaded and downloaded, but the OSS console displays the object ended with a slash as a folder.

<?php
/**
 * Create a virtual directory
 *
 * @param OssClient $ossClient OSSClient instance
 * @param string $bucket Bucket name
 * @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");
}

Delete a single object

You can use OssClient::deleteObjectto delete a single object:

<?php
/**
 * Delete an object
 *
 * @param OssClient $ossClient OSSClient instance
 * @param string $bucket Bucket name
 * @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");
}

Note: The object cannot be restored after deletion.

Delete multiple objects

You can use OssClient::deleteObjects to delete multiple objects:

<?php
/**
 * Delete multiple objects by batch
 *
 * @param OssClient $ossClient OSSClient instance
 * @param string $bucket Bucket name
 * @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");
}

Copy an object

You can use OssClient::copyObject to copy objects:

<?php
/**
 * Copy an object
 *
 * @param OssClient $ossClient OSSClient instance
 * @param string $bucket Bucket name
 * @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");
}

Note: You can copy an object smaller than 1 GB using OssClient::copyObject. When you copy an object larger than 1 GB, use OssClient::uploadPartCopy.

Modify object meta

Object Meta describes the attributes of objects uploaded on OSS. The attributes are of two types: HTTP standard attributes (HTTP Headers) and user-defined metainformation (User Meta). Object metadata can be configured when objects are uploaded or copied in various ways.

HTTP standard attributes, Cache-Control, Content-Disposition, Content-Encoding, Content-Language, Expires, Content-Length, Content-Type and Last-Modified.

This attribute is designed for you to enrich the descriptions of the objects. In OSS, all parameters prefixed with “x-oss-meta-“ are considered as User Meta, such as x-oss-meta-location. A single object can have multiple similar parameters, but the total size of all User Meta cannot exceed 8 KB. The User Meta information is returned when you download the object/get the object metadata.

For more information about object metadata, see Object Meta.

You can use the COPY operation to modify the metadata of an existing object. If the source object address and target object address of the COPY operation are the same, the source object metadata gets replaced directly.

/**
 * Modify the object metadata
 * If the target object is identical with the source object, the object metadata is modified. This is a feature of the copyObject interface.
 *
 * @param OssClient $ossClient OSSClient instance
 * @param string $bucket Bucket name
 * @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");
}

Note:

You can modify the object type by modifying the object Content-Type.

You can control object download behaviors by modifying the object Content-Disposition.

Get the object meta information (Object Meta)

You can get the object meta information using OssClient::getObjectMeta:

<?php
/**
 * Get the object meta through the getObjectMeta interface
 *
 * @param OssClient $ossClient OssClient instance
 * @param string $bucket Bucket name
 * @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");
    }
}

Set object access permissions

The object has four access ACLs: default (default value), private (private-read-write), public-read (public-read and private-write), and public-read-write (public-read-write), which are described as follows:

Permission	Description	PHP SDK value
Default	The object inherits the read-write permissions of the bucket. The object adopts the default ACL by default.	default
Private	The object is a private resource. Only the owner of the object has permission to read and write the object. Other users have no permission to operate the object.	private
PublicRead	The object can be read by the public. Only the owner of the object has permission to read and write the object. Other users only have permission to read the object.	public-read
PublicReadWrite	The object can be read and written by the public. That is, all users have permission to read and write the object.	public-read-write

The object ACL takes precedence over the bucket ACL. For example, if the bucket ACL is private and the object ACL is public-read-write, the system first checks the ACL of the object when a user accesses the object. As a result, all users can access this object even if the bucket is private.

If the ACL of an object has never been set, the ACL of this object is the same as that of the bucket where the object is located.

You can set the object access permission using OssClient::putObjectAcl:

<?php
/**
 * Get the object scope permission
 *
 * @param OssClient $ossClient OssClient instance
 * @param string $bucket Bucket name
 * @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");
}

Get the object access permission

You can get the object access permission using OssClient::getObjectAcl:

<?php
/**
 * Get the object access permission
 *
 * @param OssClient $ossClient OssClient instance
 * @param string $bucket Bucket name
 * @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);
}

Restore objects of the Archive storage class

The status of archived objects changes as follows:

Objects of the Archive storage class are frozen initially.
After a restoring request is submitted, the server restores the objects, which turns the objects into the restoring state.
It takes one minute to finish restoration by default.
Users can read the objects after the restoration is done.
By default, objects are frozen again one day after being restored. However, the period can be prolonged to seven days at most.

You can callOssClient::restoreObject method to restore the archived objects.

/**
 * Restore objects of the Archive storage class
 *
 * @param OssClient $ossClient OssClient instance
 * @param string $bucket Bucket name
 * @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");
}

Tips:

For more information, see Restore objects.

Create symbolic links

A symbolic link is a special object that points to a specific object, which is similar to the shortcuts used in windows.

You can call the OssClient::putSymlink method to create a symbolic link:

<?php
/**
 * Create symbolic links
 *
 * @param OssClient $ossClient OssClient instance
 * @param string $bucket Bucket name
 * @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");
}

Tips:

For more information, see PutSymlink.

Get object content that symbolic links point to

Getting a symbolic link requires that the user has read permission for the symbolic link.

You can call theOssClient::getSymlinkmethod to get object content that the symlink points to:

<?php
/**
 * get object content that symbolic links point to
 *
 * @param OssClient $ossClient OssClient instance
 * @param string $bucket Bucket name
 * @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);
}

Tips:

For more information, see GetSymlink.