Usage examples

Install and configure osscmd

You can use osscmd by downloading and decompressing the software development kit (SDK) package on Linux or Windows.

To obtain instructions, run the Python osscmd command. Each command has two execution modes. The following example shows how to run the gs command to query the buckets that you created:

• Method 1: You do not specify the AccessKey ID and AccessKey secret. osscmd reads them from the default configuration file.

  $ python osscmd gs
  can't get accessid/accesskey, setup use : config --id=accessid --key=accesskey

  Note

  If this message appears, your AccessKey ID and AccessKey secret are not configured. For information about the configuration command, see Method 2.

  If the AccessKey ID and AccessKey secret are configured and valid, you can run the command.

  $ python osscmd gs
  2021-07-19 08:11 test-oss-sample
  Bucket Number is:  1

• Method 2: You can specify the AccessKey ID and AccessKey secret in the command. osscmd then reads them from the command line. If the AccessKey ID and AccessKey secret are valid, the command returns the following result.

  $ python osscmd gs --id=your_id --key=your_key --host=your_endpoint
  2021-07-19 08:11 test-oss-sample
  Bucket Number is:  1

  To save your AccessKey ID and AccessKey secret to the default configuration file, run the following command. The default OSS host is oss.aliyuncs.com.

  $python osscmd config --id=your_id --key=your_key --host=your_endpoint

  A message similar to "Your configuration is saved into" indicates that the AccessKey ID and AccessKey secret have been saved.

Basic operations

• List created buckets

  $python osscmd getallbucket

  If you are a new OSS user and have not created any buckets, the output is empty.

• Create a bucket

  Create a bucket named mybucketname.

  $python osscmd createbucket mybucketname

  The bucket creation may fail because bucket names must be globally unique in OSS. In this case, use a different bucket name, such as a name that includes a specific date.

• Verify that the creation succeeded.

  $python osscmd getallbucket

  If the operation fails, check the osscmd error message.

• View objects

  After you create a bucket, you can view the objects in it.

  $python osscmd list oss://mybucketname/

  Because the bucket contains no objects, the output is empty.

• Upload an object

  You can upload an object to the bucket. Assume that the local file is named local_existed_file and its MD5 hash is as follows.

  $ md5sum local_existed_file 7625e1adc3a4b129763d580ca0a78e44 local_existed_file
  $ python osscmd put local_existed_file oss://mybucketname/test_object

  Note

  md5sum is a Linux command and is not available on Windows.

• View the object again

  If the object is uploaded, you can view the objects in the bucket again.

  $python osscmd list oss://mybucketname/

• Downloading an object

  Download an object from the bucket to a local file and compare its MD5 hash.

  $ python osscmd get oss://mybucketname/test_object download_file
  $ md5sum download_file 
  7625e1adc3a4b129763d580ca0a78e44  download_file

  Note

  md5sum is a Linux command and is not available on Windows.

• Delete an object

  $ python osscmd delete oss://mybucketname/test_object

• Delete a bucket

  Note

  A bucket cannot be deleted if it contains objects.

  $ python osscmd deletebucket mybucketname

Using lifecycle

• Configure a lifecycle rule in an XML text file

  <LifecycleConfiguration>
      <Rule>
          <ID>1125</ID>
          <Prefix>log_backup/</Prefix>
          <Status>Enabled</Status>
          <Expiration>
              <Days>2</Days>
          </Expiration>
      </Rule>
  </LifecycleConfiguration>

  This rule deletes objects that have the prefix log_backup/ and are more than two days old. For more information about how to configure rules, see API Reference.

• Writing to the lifecycle

  python osscmd putlifecycle oss://mybucket lifecycle.xml
  0.150(s) elapsed

• Read a lifecycle rule

  python osscmd getlifecycle oss://mybucket
  <?xml version="1.0" encoding="UTF-8"?>
  <LifecycleConfiguration>
    <Rule>
      <ID>1125</ID>
      <Prefix>log_backup/</Prefix>
      <Status>Enabled</Status>
      <Expiration>
        <Days>2</Days>
      </Expiration>
    </Rule>
  </LifecycleConfiguration>
  0.027(s) elapsed

• Delete a lifecycle

  python osscmd deletelifecycle oss://mybucket
  0.139(s) elapsed

• Read the lifecycle rule

  python osscmd getlifecycle oss://mybucket
  Error Headers:
  [('content-length', '288'), ('server', 'AliyunOSS'), ('connection', 'close'), ('x-oss-request-id', '54C74FEE5D7F6B24E5042630'), ('date', 'Tue, 27 Jan 2015 08:44:30 GMT'), ('content-type', 'application/xml')]
  Error Body:
  <?xml version="1.0" encoding="UTF-8"?>
  <Error>
    <BucketName>mybucket</BucketName>
    <Code>NoSuchLifecycle</Code>
    <Message>No Row found in Lifecycle Table.</Message>
    <RequestId>54C74FEE5D7F6B24E5042630</RequestId>
    <HostId>mybucket.oss-maque-hz-a.alibaba.net</HostId>
  </Error>
  Error Status:
  404
  getlifecycle Failed!

Configure hotlink protection

• Allow requests with an empty Referer header

  $osscmd putreferer oss://test --allow_empty_referer=true
  0.004(s) elapsed

• Retrieve the Referer configuration

  $osscmd getreferer oss://test
  <?xml version="1.0" encoding="UTF-8"?>
  <RefererConfiguration>
    <AllowEmptyReferer>true</AllowEmptyReferer>
    <RefererList />
  </RefererConfiguration>

• Disallow requests with an empty Referer header and allow only requests from www.example.com

  $osscmd putreferer oss://test --allow_empty_referer=false --referer='www.example.com'
  0.092(s) elapsed

• Retrieve the Referer configuration

  $osscmd getreferer oss://test
  <?xml version="1.0" encoding="UTF-8"?>
  <RefererConfiguration>
    <AllowEmptyReferer>false</AllowEmptyReferer>
    <RefererList>
      <Referer>www.example.com</Referer>
    </RefererList>
  </RefererConfiguration>

• Disallow requests with an empty Referer header and allow only requests from www.example.com and www.example.org

  $osscmd putreferer oss://test --allow_empty_referer=false --referer='www.example.com,www.example.org'

• Retrieve the Referer configuration

  $osscmd getreferer oss://test
  <?xml version="1.0" encoding="UTF-8"?>
  <RefererConfiguration>
    <AllowEmptyReferer>false</AllowEmptyReferer>
    <RefererList>
      <Referer>www.example.com</Referer>
      <Referer>www.example.org</Referer>
    </RefererList>
  </RefererConfiguration>

Use logging

• Enable logging

  $osscmd putlogging oss://mybucket oss://myloggingbucket/mb

• Retrieve the logging configuration

  $osscmd getlogging oss://mybucket