Manage a bucket

Last Updated: Apr 28, 2018

A bucket is a storage space on OSS and a management entity for billing, access control, logging, and other advanced features.

Note: Complete code for the following scenarios can be found at GitHub.

Create a bucket

You can use OssClient::createBucket to create a new bucket:

  1. <?php
  2. /**
  3. * Create a bucket
  4. * The ACL specifies the access permission on the bucket, which may be private, public-read, or public-read-write.
  5. * The private permission indicates that only the bucket owner or the authorized user has the permission to read and write the bucket.
  6. * The three permissions respectively correspond to "OSSClient::OSS_ACL_TYPE_PRIVATE",
  7. * OssClient::OSS_ACL_TYPE_PUBLIC_READ,
  8. * OssClient::OSS_ACL_TYPE_PUBLIC_READ_WRITE
  9. *The three storage types respectively correspond to "OssClient::OSS_STORAGE_STANDARD",
  10. * OssClient::OSS_STORAGE_IA,
  11. * OssClient::OSS_STORAGE_ARCHIVE
  12. * @param OssClient $ossClient OSSClient instance
  13. * @param string $bucket Name of the bucket to be created
  14. * @return null
  15. */
  16. function createBucket($ossClient, $bucket)
  17. {
  18. try {
  19. $options = array(
  20. OssClient::OSS_STORAGE => OssClient::OSS_STORAGE_STANDARD
  21. );
  22. $ossClient->createBucket($bucket, OssClient::OSS_ACL_TYPE_PRIVATE, $options);
  23. } catch (OssException $e) {
  24. printf(__FUNCTION__ . ": FAILED\n");
  25. printf($e->getMessage() . "\n");
  26. return;
  27. }
  28. print(__FUNCTION__ . ": OK" . "\n");
  29. }

Note:

  • For Bucket naming rules, see Basic OSS concepts in Basic Concepts.

  • This is because each bucket name must be globally unique, you must make sure that your bucket name is different from all others.

  • For more information about the bucket permissions, see Access Control.

  • The createBucket supports both Infrequent Access and Archive storage type. For more information about the storage types, see Storage Types.

  • The parameter Options within the creatBucket is optional. By default, it is not added.

Identify whether the bucket exists

You can determine whether a bucket exists using OssClient::doesBucketExist:

  1. /**
  2. * Determine whether the bucket exists
  3. *
  4. * @param OssClient $ossClient OssClient instance
  5. * @param string $bucket Bucket name
  6. */
  7. function doesBucketExist($ossClient, $bucket)
  8. {
  9. try {
  10. $res = $ossClient->doesBucketExist($bucket);
  11. } catch (OssException $e) {
  12. printf(__FUNCTION__ . ": FAILED\n");
  13. printf($e->getMessage() . "\n");
  14. return;
  15. }
  16. if ($res === true) {
  17. print(__FUNCTION__ . ": OK" . "\n");
  18. } else {
  19. print(__FUNCTION__ . ": FAILED" . "\n");
  20. }
  21. }

List all buckets of a user

You can use OssClient::listBuckets to list all the buckets of a user:

  1. <?php
  2. /**
  3. * List all buckets of a user
  4. *
  5. * @param OssClient $ossClient OssClient instance
  6. * @return null
  7. */
  8. function listBuckets($ossClient)
  9. {
  10. $bucketList = null;
  11. try{
  12. $bucketListInfo = $ossClient->listBuckets();
  13. } catch(OssException $e) {
  14. printf(__FUNCTION__ . ": FAILED\n");
  15. printf($e->getMessage() . "\n");
  16. return;
  17. }
  18. $bucketList = $bucketListInfo->getBucketList();
  19. foreach($bucketList as $bucket) {
  20. print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n");
  21. }
  22. }

Delete a bucket

You can use OssClient::deleteBucket to delete a bucket:

  1. <?php
  2. /**
  3. * Delete a bucket
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Name of the bucket to be deleted
  7. * @return null
  8. */
  9. function deleteBucket($ossClient, $bucket)
  10. {
  11. try{
  12. $ossClient->deleteBucket($bucket);
  13. } catch(OssException $e) {
  14. printf(__FUNCTION__ . ": FAILED\n");
  15. printf($e->getMessage() . "\n");
  16. return;
  17. }
  18. print(__FUNCTION__ . ": OK" . "\n");
  19. }

Note:

  • A non-empty bucket (which contains objects or data parts from multipart upload) cannot be deleted.
  • To delete a non-empty bucket, you must first delete all objects and parts in it.

Set the ACL of a bucket

You can set the bucket ACL when creating a bucket and also, modify the bucket ACL according to your service requirements. Only the creator of the bucket has the permission to perform this operation. For more information about bucket permissions, see Access Control.

Currently, three permissions are available for a bucket:

Permission PHP SDK value
Private-read-write OssClient::OSS_ACL_TYPE_PRIVATE
Public-read and private-write OssClient::OSS_ACL_TYPE_PUBLIC_READ
Public-read-write OssClient::OSS_ACL_TYPE_PUBLIC_READ_WRITE

You can set the bucket access permission using OssClient::putBucketAcl:

  1. <?php
  2. /**
  3. * Configure the bucket ACL
  4. *
  5. * @param OssClient $ossClient OssClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function putBucketAcl($ossClient, $bucket)
  10. {
  11. $acl = OssClient::OSS_ACL_TYPE_PRIVATE;
  12. try {
  13. $ossClient->putBucketAcl($bucket, $acl);
  14. } catch (OssException $e) {
  15. printf(__FUNCTION__ . ": FAILED\n");
  16. printf($e->getMessage() . "\n");
  17. return;
  18. }
  19. print(__FUNCTION__ . ": OK" . "\n");
  20. }

Get the ACL of a bucket

You can set the bucket access permission using OssClient::getBucketAcl:

  1. <?php
  2. /**
  3. * Obtain the bucket ACL configuration
  4. *
  5. * @param OssClient $ossClient OssClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function getBucketAcl($ossClient, $bucket)
  10. {
  11. try {
  12. $res = $ossClient->getBucketAcl($bucket);
  13. } catch (OssException $e) {
  14. printf(__FUNCTION__ . ": FAILED\n");
  15. printf($e->getMessage() . "\n");
  16. return;
  17. }
  18. print(__FUNCTION__ . ": OK" . "\n");
  19. print('acl: ' . $res);
  20. }

Get the Region of a bucket

Region indicates the geographic location of the OSS data center. The user can select the region of data storage based on the cost, request source, and other factors. In general, regions closer to the user are accessed faster. For more information, see the regions that OSS has opened or you can see Region.

You can useOssClient::getBucketLocationto get the Region of a bucket:

  1. /**
  2. * Get the Region of a bucket
  3. *
  4. * @param OssClient $ossClient OssClient examples
  5. * @param string $bucket name of a bucket
  6. * @return null
  7. */
  8. function getBucketLocation($ossClient, $bucket)
  9. {
  10. try {
  11. $Regions = $ossClient->getBucketLocation($bucket);
  12. } catch (OssException $e) {
  13. printf(__FUNCTION__ . ": FAILED\n");
  14. printf($e->getMessage() . "\n");
  15. return;
  16. }
  17. print(__FUNCTION__ . ": OK" . "\n");
  18. var_dump($Regions);
  19. }

Tips:

Get Meta information of a bucket

You can useOssClient::getBucketMetato get Meta information of a bucket:

  1. /**
  2. * get Meta information of a bucket
  3. *
  4. * @param OssClient $ossClient OssClient examples
  5. * @param string $bucket name of a bucket
  6. * @return null
  7. */
  8. function getBucketMeta($ossClient, $bucket)
  9. {
  10. try {
  11. $Metas = $ossClient->getBucketMeta($bucket);
  12. } catch (OssException $e) {
  13. printf(__FUNCTION__ . ": FAILED\n");
  14. printf($e->getMessage() . "\n");
  15. return;
  16. }
  17. print(__FUNCTION__ . ": OK" . "\n");
  18. var_dump($Metas);
  19. }
Thank you! We've received your feedback.