Object

在OSS中，用户操作的基本数据单元是Object。单个Object最大允许存储5TB的数据。Object包含key、meta和data。其中，key是Object的名字；meta是用户对该object的描述，由一系列name-value对组成；data是Object的数据。

命名规范

Object的命名规范如下：

• 使用UTF-8编码
• 长度必须在1-1023字节之间
• 不能以“/”或者“\”字符开头
• 不能含有“\r”或者“\n”的换行符

上传Object

简单的上传

我们可以把字符串或者resource类型的对象传到指定Bucket中：

<?php

$client->putObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
    'Content' => 'This is my content',
));

或者：

<?php

$client->putObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
    'Content' => fopen('/path/to/file', 'r'),
    'ContentLength' => filesize('/path/to/file'),
));

Content 指定了Object的具体内容。值得注意的是，当 Content 为resource类型时，你必须显示地指定 ContentLength 参数（Object的长度，以byte为单位）。

用户自定义元数据

用户可以自定义Object的元数据（userMetadata），比如下面的代码：

<?php

$client->putObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
    'Content' => 'This is my content',
    'UserMetadata' => array(
        'key1' => 'abc',
        'key2' => 'def',
    ),
));

上面代码为Object定义了2个元数据， key1 以及 key2 ; 一个Object可以有多个元数据，但所有的user Metadata总大小不能超过2k。

定义HTTP属性

由于Object以Http协议的方式提供下载，我们可以在上传时设置Object的HTTP属性。下面代码为Object设置了过期时间：

<?php

$client->putObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
    'Content' => 'This is my content',
    'Expires' => new \DateTime("+5 minutes"),
));

上面代码设置了Object在5分钟之后过期。OSS支持以下几种HTTP头信息，它们是 Content-Type 、 Cache-Control 、 Content-Disposition 、Content-Encoding 、 Expires 。它们的相关介绍见 RFC2616 。下面是HTTP头信息与SDK参数的对应关系：

分块上传

OSS允许用户将一个Object分成多个请求上传到后台服务器中，关于分块上传的内容，我们将在 Object的分块上传 这一章中做介绍。

获取Object列表

<?php

$objectListing = $client->listObjects(array(
    'Bucket' => 'your-bucket-name',
));

foreach ($objectListing->getObjectSummarys() as $objectSummary) {
    echo $objectSummary->getKey();
}

listObjects方法会返回 ObjectListing 对象，ObjectListing 对象包含了此次listObject请求的返回结果。其中我们可以通过 ObjetListing 中的 getObjectSummaries 方法获取所有Object的描述信息（包含了OSSObjectSummary的array）。

Note

默认情况下，如果Bucket中的Object数量大于100，则只会返回100个Object， 且返回结果中 IsTruncated 为 false，并返回 NextMarker 作为下此读取的起点。若想增大返回Object数目，可以修改 MaxKeys 参数，或者使用 Marker 参数分次读取。

扩展参数

可以在请求中设置以下参数：

在上面参数中，我们可以通过 MaxKeys 控制每次返回的Object数目，并使用 Marker 参数设置开始读取的位置, 另外我们可以通过设置 Prefix 和 Delimiter 参数来模拟文件夹功能:

假设Bucket中有4个文件： oss.jpg ， fun/test.jpg ， fun/movie/001.avi ， fun/movie/007.avi ，我们把 “/” 符号作为文件夹的分隔符。

遍历所有Object

<?php

$objectListing = $client->listObjects(array(
    'Bucket' => 'your-bucket-name',
));

echo "Objects:\n";
foreach ($objectListing->getObjectSummarys() as $objectSummary) {
    echo $objectSummary->getKey() . "\n";
}

echo "\nCommonPrefixs:\n";
foreach ($objectListing->getCommonPrefixes() as $commonPrefix) {
    echo $commonPrefix . "\n";
}

以上代码输出:

Objects:
fun/movie/001.avi
fun/movie/007.avi
fun/test.jpg
oss.jpg

CommonPrefixs:

我们没有指定 Prefix 和 Delimiter ，于是获得了所有的Object的信息。可以看到返回的 CommonPrefixs 为空。

列出指定目录下的所有Object

当指定了 Prefix 参数后，会列出指定目录下的所有Object（包括子目录）：

<?php

$objectListing = $client->listObjects(array(
    'Bucket' => 'your-bucket-name',
    'Prefix' => 'fun/'
));

echo "Objects:\n";
foreach ($objectListing->getObjectSummarys() as $objectSummary) {
    echo $objectSummary->getKey() . "\n";
}

echo "\nCommonPrefixs:\n";
foreach ($objectListing->getCommonPrefixes() as $commonPrefix) {
    echo $commonPrefix . "\n";
}

以上代码输出:

Objects:
fun/movie/001.avi
fun/movie/007.avi
fun/test.jpg

CommonPrefixs:

列出指定目录下的Object以及子目录

我们可以继续设置 Delimiter 参数：

<?php

$objectListing = $client->listObjects(array(
    'Bucket' => 'your-bucket-name',
    'Prefix' => 'fun/',
    'Delimiter' => '/',
));

echo "Objects:\n";
foreach ($objectListing->getObjectSummarys() as $objectSummary) {
    echo $objectSummary->getKey() . "\n";
}

echo "\nCommonPrefixs:\n";
foreach ($objectListing->getCommonPrefixes() as $commonPrefix) {
    echo $commonPrefix . "\n";
}

以上代码输出:

Objects:
fun/test.jpg

CommonPrefixs:
fun/movie/

可以看到，在Objects列表中，只有 fun/test.jpg 文件被列了出来，也就是直接在 fun/ 文件夹下的文件。而CommonPrefix列表则输出 fun/movie/ , 也就是在 fun/ 目录下的子目录。

获取Object

通过 getObject 方法可以将Object的信息以及内容获取下来：

<?php

$object = $client->getObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
));

echo "Key: " . $object->getKey() . "\n";
echo "Update Date: " . $object->getLastModified()->getTimestamp() . "\n";
echo "Content: \n";
echo stream_get_contents($object->getObjectContent());

getObject 接口会返回 \Aliyun\OSS\Model\OSSObject 对象，其中含有了Object的一些信息以及表示Object内容的resource。

我们也可以通过以下方式直接获取到Object内容的string:

<?php

$object = $client->getObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
));

echo (string) $object;

Note

\Aliyun\OSS\Model\OSSObject 对象析构时会自动关闭流，请不要在 OSSObject 对象销毁后使用流。

直接下载Object到文件

通过指定 SaveAs 参数可以直接下载Object到文件，比如：

<?php

$object = $client->getObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
    'SaveAs' => '/tmp/my-file.txt',
));

Note

当启用 SaveAs 参数时 OSSObject 的 getObjectContent 方法会返回空，请不要通过OSSObject获取Object的内容。

获取Object的部分内容

我们可以通过 Range 参数来获取Object的部分数据：

<?php

$object = $client->getObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
    'Range' => array(0, 3),
));

echo (string) $object;

Range 参数可以指定一个array，其中两个元素分别指定了读取的起点和终点。比如上面的代码则读取了Object从0到3位置的4个字节的数据。

GetObject请求参数

可以在请求中设置以下参数：

删除Object

下面代码会删除指定Object。

<?php

$client->deleteObject(array(
    'Bucket' => 'your-bucket-name',
    'Key' => 'your-object-key',
));

拷贝Object

使用 copyObject 方法可以拷贝一个Object。

<?php

$client->copyObject(array(
    'SourceBucket' => 'your-source-bucket-name',
    'SourceKey' => 'your-source-object-key',
    'DestBucket' => 'your-dest-bucket-name',
    'DestKey' => 'your-dest-object-key',
));

在 copyObject 中也可以使用 ModifiedSinceConstraint 、UnmodifiedSinceConstraint 、 MatchingETagConstraints 、 NoMatchingETagConstraints 参数， 用法与 getObject 接口相似。

同时在copyObject中也可以使用可以设置Metadata和 HTTP头的参数 。当使用这些参数时，原来Object所有元信息都会被忽略。