Use BOS Service via CLI

Users can access BOS services to manage buckets and objects using bos commands. If operations are attempted when the BOS service balance is insufficient, an "Access Denied" error will be displayed.

Upgrade instructions

The BOS command line interface has been fully upgraded from BOS CLI to BOS CMD. The BOS CLI tool has stopped function iterations, and it is recommended that you replace it with BOS CMD.

CLI uses a multi-layer command structure. All commands start with bce, where [options] represents the options supported by BCE CLI, and <service> represents the services supported by CLI (such as BOS). Each service has multiple specific sub-commands.

1$ bce [options] [<service> <command> [parameters [options]]]

Parameter explanation

General options for CLI

• View help: Add -h or --help after any command to view help information for that command.

  Plain Text Copy

  1$ bce -h
  2$ bce bos -h
  3$ bce bos ls --help

• View/set configuration information (AK, SK, etc.): -c/--configure

  Plain Text Copy

  1$ bce -c [<conf-path>]

• View version information: -v/--version

  Plain Text Copy

  1$ bce -v

• View debug information: -d/--debug

  Plain Text Copy

  1$ bce -d bos ls bos:/bce-test/pre/

This -d/--debug command cannot be used independently and must be combined with the bos command.

• Use a specified configuration file: --conf-path

  Plain Text Copy

  1$ bce --conf-path ./conf-sample/ bos ls bos:/bce-test/pre/

  If --conf-path command is not used, the configuration in the user’s home directory ~/.bce is used by default.

Bucket management

Create bucket

Description:Create a null bucket.

Command format: $ bce bos mb bos:/<bucket-name> [--region REGION]

Note:

• You can specify the bucket's region only after enabling the "automatic domain name switching" feature.
• If you do not specify the region to which the bucket belongs, we will use the default region you configured in the CLI (i.e The default region configured by bce -c, if you have not configured a default region, the default region for CLI will be bj).

Example:

• Do not specify the region to which the bucket belongs for creation

  Example:

  Plain Text Copy

  1$ bce bos mb bos:/mybucket

  Response example:

  Plain Text Copy

  1Make bucket: mybucket

• Specify the region to which the bucket belongs for creation

  Example:

  Plain Text Copy

  1$ bce bos mb bos:/mybucket -r bj

  Response example:

  Plain Text Copy

  1Make bucket: mybucket

Delete bucket

Description:Delete a bucket, and require that there are no objects or unfinished three-step upload parts in the bucket.

Command format: $ bce bos rb bos:/<bucket-name> [-y, --yes] [-f, --force]

Note:

• -y, --yes: Use this option to skip the confirmation step by default.
• -f. -- force: If you need to delete non-null buckets, you can use -f/--force option to force deletion. When using this option, the bucket cannot be null and all objects inside it can be deleted together.

Example: $ bce bos rb bos:/mybucket --force

Response example:

1Do you really want to REMOVE bucket bos:/bce-test and all objects in it? (Y/N) **Y**
2Delete object: bos:/mybucket/test1.txt
3Delete object: bos:/mybucket/test2.txt
4Remove bucket: mybucket

List buckets

Description:List all buckets.

Command format: $ bce bos ls [bos:/]

Example: $ bce bos ls

Response example:

1  2015-08-12 10:20:58       bj  bce-doc
2  2015-08-12 10:21:09       bj  bce-sdk
3  2016-07-19 11:11:41       bj  bce-temp
4  2016-07-19 10:53:37       bj  bce-test

Note: The first column in the output shows the bucket creation date, the second column shows the creation time, the third column displays the bucket's region, and the fourth column lists the bucket name.

Object management

Upload Object

Description:BOS CLI supports four upload modes: synchronous upload, single-file upload, batch upload and streaming upload. During upload, you can specify the object storage class as standard storage, [Infrequent Access Storage](BOS/Product Description/Tiered Storage Introduction/Introduction to storage classes.md), [Cold Storage](BOS/Product Description/Tiered Storage Introduction/Introduction to storage classes.md) or [ Archive Storage](BOS/Product Description/Tiered Storage Introduction/Introduction to storage classes.md). In addition, BOS CLI also supports:

• Automatically resumable upload
• For files larger than 32 MB, automatically split and upload them in parallel, configuring the number of concurrent upload connections.

When you need to upload data between your local system and BOS, synchronous upload (sync) is the most convenient upload command. Synchronous upload supports batch operations by default, and can synchronize local directories to BOS. If there is a file with the same name on the BOS, synchronous upload will ignore these files and only synchronize new or modified files. The sync command will list both local and BOS files, and perform the following actions for different situations:

• For added files (exist locally but not on BOS): Upload
• For files that have been uploaded but have been modified (the update time of local files is later than the creation time of BOS files (accurate to seconds); or the update time of the local file is the same as the creation time of the BOS file (accurate to seconds), but the size of the local file is different from that of BOS): Overwrite the upload
• For files that have been uploaded and have not been modified: Skip without processing
• For files that have already been uploaded but are not present locally, process them differently based on the --delete parameter.

Command format:

• Synchronous upload: $ bce bos sync <local_dir> bos:/<bucket_name>/[prefix] [--delete] [--yes] [--exclude] [--quiet] [--dryrun] [--storage-class [STORAGE_CLASS]] [--exclude-time TIME_RANGE] [--include-time TIME_RANGE]

  Note:

  • --dryrun: Display the operations to be executed without actually carrying them out.
  • --quiet: Perform uploads in synchronization mode without displaying intermediate processes.
  • --delete: Remove files present in BOS but not locally to fully synchronize BOS and local data. By default, a confirmation prompt will appear before executing deletions.
  • --yes: Delete files without requiring confirmation.
  • --exclude: When executing local to boss sync, the files that need to be skipped support wildcard * and multiple configurations, for example, skip the tmp file and the svn directory under all subdirectories of the current directory: --exclude ./*.tmp --exclude */.svn
  • --storage-class [STORAGE_CLASS]: Specify the storage class of the synchronously uploaded object through the storage-class parameter. When specifying storage-class as STANDARD_IA, COLD or ARCHIVE, the storage is of infrequent access storage, cold storage or archive storage class, and the specified storage-class is STANDARD or standard storage when storage-class is not specified.
  • local_dir must be a local directory and cannot be a single file. It also does not support the syntax of wildcard matching, such as <local_dir>/* and <local_dir>/prefix*.
  • --exclude-time: When executing sync, skip files created or modified within the specified range. TIME-RANGE represents the time interval you specify, in the format of '[start, end)’. The time interval must be enclosed by '[' and ')' (the time interval is closed on the left and open on the right, so it includes the left boundary time but not the right boundary time). Example: If you do not want to synchronize generated or modified files between 03:04:05 on January 2, 2017 and 03:04:05 on January 3, 2017, you can use -- --exclude-time '[2017-01-02 03:04:05, 2017-01-03 03:04:05)'.
  • --include-time: When performing sync, only files created or modified within a specified time range will be synchronized. Its usage is similar to --exclude-time.
  • --exclude-time and --include-time cannot be used at the same time.

  Note of time interval format:

  The format for specifying the time range is '[start, end)'. The start and end times can be relative, absolute, or null, but they cannot be both relative and null simultaneously. The detailed format of the time range is as follows:

  Time format	Description
  The start or end time is null	If the start time is null, the start time is infinitely small. If the end time is null, the end time is infinitely large. Example: '[, end]' indicates that the start time is infinitely small; '[start,]' indicates that the end time is infinitely large.
  'now'	This variable is a special indicator defined by the CLI that represents the current time. Example: If the current local time is 14:23:35 on October 18, 2017 (Beijing Time), the interval '[2017-10-01 00:00:00, now)' represents the period from 00:00:00 on October 1, 2017, to 14:23:35 on October 18, 2017 (excluding the current time, as the interval is left-closed and right-open).
  'midnight'	Similar to 'now', this variable is another magic variable defined in the CLI, representing 24:00:00 (midnight) of the current day.
  Local time	The local time format is 'YYYY-mm-DD HH:MM:SS', such as 2017-10-01 00:00:00.
  UTC time	The UTC time format is 'YYYY-mm-DDTHH:MM:SSZ', such as 2017-01-02T23:04:54Z.
  Timestamp	The start or end time can also be represented as a timestamp.
  Relative time	It uses the ISO8601 time period standard, formatted as 'PnnYnnMnnWnnDTnnHnnMnnS' (Note: Not all units are mandatory; for example, 'P1D' represents one day. For more details, refer to ISO8601). Relative times can be combined with 'now' and 'midnight' to create absolute times. For example, 'midnight-P1D' refers to 24:00:00 of the previous day. If the start time is given as a relative time (e.g., when specifying the range as [duration, end), where 'duration' represents the relative time and 'end' is the absolute end time of the range), the start time will be calculated as start = end - duration, and the end time will remain as 'end'. Similarly, if the end time is a relative time, and the start is given as an absolute time, the end will be calculated as end = start + duration.

• Single-file upload: $ bce bos cp <local-path> <bos-path> [--storage-class [STORAGE_CLASS]]
• Batch upload: $ bce bos cp <local-path> <bos-path> --recursive [--storage-class [STORAGE_CLASS]]
• Streaming upload: $ bce bos cp - <bos-path> [--storage-class [STORAGE_CLASS]]

All four upload methods in BOS support resumable upload functions for large files. The detailed operation for resuming large file uploads is as follows:

1. Set the validity period of resumable upload:

   Plain Text Copy

   1$ bce -c
   2
   3$ Default breakpoint_file_expiration [7] days: Enter the period of keep breakpoint file

   Note: The resumable validity period must be set to an integer greater than or equal to 0. Set it to -1 for permanent validity.

2. After a transfer interruption, re-execute the upload command to resume the resumable upload. To ignore resumable upload and restart the file upload from scratch, add the --restartparameter to the command.

Note:

• When executing the command bce bos cp /tmp/file1 bos:/bucket/file2, the file2 destination can be identical to the file1 source. If file2 already exists in the bucket, it will be overwritten.
• When executing the command bce bos cp /tmp/file bos:/bucket/, the local file name will automatically be used as the BOS file name. If a file with the same name already exists, it will be overwritten.
• When executing the bce bos cp/tmp/file bos:/bucket/prefix [/] -r command, if the local file is a file, it will degenerate into a single file upload. If the bos path ends with "/", the prefix is treated as the directory, and new files will be saved at the next level of the prefix; if the BOS path does not end with "/", the prefix is treated as the object name and uploaded directly.
• When executing the command bce bos cp /tmp/dir/ bos:/bucket/prefix[/] -r, if the local is a directory, the end of the BOS path will create a new directory on BOS with prefix as the directory name, regardless of whether there is a "/" or not; and copy all objects in dir to the prefix directory.
• When <local-path> is "-", the data can be read from or written to the stream, and can be connected using pipelines. Stream operations in cp are only supported in the Linux environment, not in Windows. When uploading objects from a stream, the maximum size of the object is limited to 5 G.
• For batch uploads, local-path must be a local directory ending with "/", and bos-path must follow the format bucket/prefix.
• During object upload, the storage-class parameter can be used to specify the storage class of the object. When storage-class is STANDARD by default, that is, standard storage, with storage-class being STANDARD_IA, COLD or ARCHIVE, the storage is of infrequent access storage, cold storage or archive storage class. If the storage-class input parameters are incorrect, it will be stored by following STANDARD, without any error message.

Example:

• Synchronize the sample directory in the current directory to bos:/bce test/test

  Example: bce bos sync ./sample/ bos:/bce-test/test

  Response example:

  Plain Text Copy

  1Upload: sample/BOS_Batch_Delete.png to bos:/bce-test/test/BOS_Batch_Delete.png
  2Upload: sample/sample.log to bos:/bce-test/test/sample.log          

• List the synchronization operations that will be executed without actually performing them

  Example: bce bos sync ./sample/ bos:/bce-test/test --dryrun

  Response example:

  Plain Text Copy

  1Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png

• Synchronize upload without outputting any intermediate processes

  Operation example: bce bos sync ./sample/ bos:/bce-test/test --quiet

  Response example: No return

• Synchronize the sample directory to boss:/bce test/test and delete files that BOS has but do not have locally

  Operation example: bce bos sync ./sample/ bos:/bce-test/test --delete

  Response example:

  Plain Text Copy

  1Delete object: bos:/bce-test/test/sample.log

• Synchronize the sample directory to bos:/bce test/test and store it as an infrequent access storage class

  Example: bce bos sync ./sample/ bos:/bce-test/test --storage-class STANDARD_IA

  Response example:

  Plain Text Copy

  1Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png

• Synchronize the sample directory to bos:/bce test/test and store it as a cold storage class

  Example: bce bos sync ./sample/ bos:/bce-test/test --storage-class COLD

  Response example:

  Plain Text Copy

  1Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png

  Note:When no file triggers the sync operation, there is no return. On both Windows and Linux systems, hard-linked files are processed in the same way as regular files; soft-linked folders are processed in the same way as regular folders, but soft-linked files (sylinks pointing to files) are processed differently from regular files. On Windows systems, when sync contains the directory of the soft-linked file, it will trigger sync to execute the upload every time. On Linux systems, sync is only triggered when the file pointed to by the soft-linked file is modified or the soft-linked file is deleted.

• Synchronize the sample directory in the current directory to bos:/bce test/test, but only synchronize files generated or modified today

  Example: bce bos sync ./sample/ bos:/bce-test/test --include-time '[P1D, midnight)'

  Note:

  • This time range spans from 00:00:00 at the start of the day to 23:59:59 at the end of the same day (including 23:59:59).
  • As the time range is left-closed and right-open, the right boundary time 'midnight' is excluded from the interval.

• Synchronize the sample directory in the current directory to bos:/bce test/test, but only synchronize files generated or modified last day

  Example: bce bos sync ./sample/ bos:/bce-test/test --include-time '[P1D, midnight-P1D)'

• Synchronize the sample directory in the current directory to bos:/bce test/test, but only synchronize files generated or modified within the past 24 hours

  Example: bce bos sync ./sample/ bos:/bce-test/test --include-time '[P1D, now)'

• Synchronize the sample directory in the current directory to bos:/bce test/test, but only synchronize files generated or modified the day before yesterday and today

  Example: bce bos sync ./sample/ bos:/bce-test/test --include-time '[PT24H, midnight)' --include-time '[P1D, midnight-P2D)'

  Note:--include-time can be used multiple times.

• Synchronize the sample directory in the current directory to bos:/bce test/test, but only synchronize files that were modified or generated within 03:04:05 am local time on January 2, 2017 to 03:04:05 pm on January 3, 2017

  Example: bce bos sync ./sample/ bos:/bce-test/test --include-time '[2017-01-02 03:04:05, 2017-01-03 03:04:05)'

  Note: Since the time interval is close at left and open at right, the above time interval excludes the time 03:04:05 on January 3, 2017. If you need to include this time, increment it by 1 second, expressed as '[2017-01-02 03:04:05, 2017-01-03 03:04:06)'.**

• Synchronize the sample directory in the current directory to bos:/bce test/test, but do not synchronize files generated or modified the day before yesterday and today

  Example: bce bos sync ./sample/ bos:/bce-test/test --exclude-time '[PT24H, midnight)' --exclude-time '[P1D, midnight-P2D)'

  Note:--exclude-time can be used multiple times.

• Single file upload

  Example:

  Plain Text Copy

  1$ bce bos cp text.txt bos:/mybucket/test.txt

  Response example:

  Plain Text Copy

  1Upload: test.txt to bos:/mybucket/test.txt

• Batch upload

  Example:

  Plain Text Copy

  1$ bce bos cp ./temp/ bos:/bce-test -r

  Response example:

  Plain Text Copy

  1Upload: /home/users/username/temp/BAE.png to bos:/bce-test/BAE.png
  2Upload: /home/users/username/tem/CreatePolicy.png to bos:/bce-test/CreatePolicy.png
  3Upload: /home/users/username/tem/BAE_Pro.png to bos:/bce-test/BAE_Pro.png
  4Upload: /home/users/username/tem/BCD.png to bos:/bce-test/BCD.png
  5Upload: /home/users/username/tem/04Eng.png to bos:/bce-test/04Eng.png
  6[5] object uploaded.

• Compress a file and output it to a pipeline, then read data from the pipeline and upload the object

  Example:

  Plain Text Copy

  1$ tar -cz test.txt | bce bos cp - bos:/mybucket/test.txt.tar

  Response example:

  Plain Text Copy

  1$ Upload: stream to bos:/mybucket/test.txt.tar

• Upload an object and store it as an infrequent access storage class

  Example:

  Plain Text Copy

  1$ bce bos cp text.txt bos:/mybucket/test.txt --storage-class STANDARD_IA

  Response example:

  Plain Text Copy

  1Upload: test.txt to bos:/mybucket/test.txt

• Upload an object and store it as a cold storage class

  Example:

  Plain Text Copy

  1$ bce bos cp text.txt bos:/mybucket/test.txt --storage-class COLD

  Response example:

  Plain Text Copy

  1Upload: test.txt to bos:/mybucket/test.txt

Download object

Description:BOS CLI supports synchronous download, single-file download, streaming download and batch file download.

Synchronous download supports batch operations by default, allowing synchronization of BOS data to a local directory. If a local file with the same name already exists, the synchronization process will skip those files and only transfer new or modified files.

The sync command will list both local and BOS files, and perform the following actions for different situations:

• For added files (a file on BOS is not locally available): Download
• For downloaded but modified files (the creation time of the BOS-side file is later than the update time of the local file, or the size of the BOS-side file differs from the local file): Overwrite and download
• For files that have been downloaded and have not been modified: Skip without processing
• For files that have been downloaded locally but no longer exist on BOS: The processing varies based on the --delete parameter.

Command format:

• Synchronous object downloads: $ bce bos sync [--delete] [--yes] [--quiet] [--exclude] [--dryrun] <bos-dir> <local-dir> [--exclude-time TIME_RANGE] [--include-time TIME_RANGE]
• Download a single object: $ bce bos cp <bos-path> <local-path>
• Copy objects in batch: $ bce bos cp <bos-path> <local-path> --recursive
• Download an object through stream operation: $ bce bos cp <bos-path> -

Note:

• When executing the command bce bos cp bos:/bucket/file /tmp/file, the local file name can be set freely. If the specified local file already exists, a prompt will be displayed asking whether to overwrite it.
• When executing the command bce bos cp bos:/bucket/file /tmp/, the local file name will automatically match the name of the file on BOS. If the local file already exists, a prompt will be displayed asking whether to overwrite it.
• When executing the command bce bos cp bos:/bucket/file /tmp/ -r, if the source is a single file on BOS, the operation will automatically degrade to downloading that single file. If the local file already exists, a prompt will be displayed asking whether to overwrite it.
• When executing the command "bce bos cp bos:/bucket/prefix/ /tmp/ -r," an error will occur if the local path is an existing file. If the local directory does not exist, it will be created.
• When <local-path> is "-", the data can be read from or written to the stream, and can be connected using pipelines.
• Stream operations with "cp" are only supported in Linux environments and not compatible with Windows.
• For batch downloads, "local-path" can only be a local directory, and "bos-path" must follow the "bucket/prefix" format. If the BOS path points to an object, it will be downloaded as a single object.
• During downloads, whether or not the "storage-class" parameter is specified, it will have no impact on the operation. This parameter is automatically ignored.
• In synchronous downloads, both "local-dir" and "bos-dir" must be directories and cannot be single files.
• --dryrun: Display the operations to be executed without actually carrying them out.
• --quiet: Executes a synchronous download without displaying any intermediate processes.
• --delete: Removes files that exist locally but not on BOS, ensuring the local data aligns completely with BOS. By default, the user will be prompted before deletion is carried out.
• --yes: Delete files without requiring confirmation.
• --exclude: Specify files to be skipped during a BOS-to-local synchronization. Support wildcards and multiple configurations. Example: --exclude 'bos:/mybucket/.tmp' --exclude 'bos:/mybucket/.svn' --exclude 'bos:/mybucket/test'.
• --exclude-time and --include-time: Their usage is identical to how they are used when synchronizing file uploads.

Example:

• Synchronize downloading of files from bos:/mybucket/pres/to the temp directory in the current directory

  Example:

  Plain Text Copy

  1$ bce bos sync bos:/mybucket/pre/ ./temp/

  Response example:

  Plain Text Copy

  1Download: bos:/mybucket/pre/sts1.png to /home/users/username/temp/sts1.png
  2Download: bos:/mybucket/pre/sts2.png to /home/users/username/temp/sts2.png
  3Sync done: bos:/mybucket/pre/ to ./temp/, [2] success [0] failure

• Download object

  Example:

  Plain Text Copy

  1$ bce bos cp bos:/mybucket/test.txt text.txt

  Response example:

  Plain Text Copy

  1Download: bos:/mybucket/test.txt to test.txt

• Download object in batch

  Example:

  Plain Text Copy

  1$ bce bos cp bos:/mybucket/pre/ temp -r

  Response example:

  Plain Text Copy

  1Download: bos:/mybucket/pre/sts1.png to /home/users/username/tmp/sts1.png
  2Download: bos:/mybucket/pre/sts2.png to /home/users/username/tmp/sts2.png
  3[2] objects downloaded.

• Download an object to pipeline, read data from pipeline and decompress it

  Example:

  Plain Text Copy

  1$ bce bos cp bos:/mybucket/test.txt.tar - | tar -xz

  No return

Copy Object

Description:BOS CLI supports copying files between buckets, including synchronous copy, single-file copy and batch file copy.

Synchronous copying supports batch operations by default. If the destination bucket already contains files with the same names, the operation will skip these files and synchronize only new or modified ones.

The sync command will list the files of both the source and destination buckets, and perform the following actions for different situations:

• For added files (a file in the source bucket does not exist in the destination bucket): Copy
• For files that have been copied but have been modified (the creation time of the source bucket file is later than the update time of the destination bucket file, or the size of the source bucket side file is not consistent with the destination bucket): Overwrite and copy
• For files that have been copied and have not been modified: Skip without processing
• For files in the destination bucket that were copied but do not exist in the source bucket, processing varies depending on the "--delete" parameter.

Command format:

• Synchronously copy object:$ bce bos sync [--delete] [--yes] [--quiet] [--exclude] [--dryrun] <bos-dir> <bos-dir> [--exclude-time TIME_RANGE] [--include-time TIME_RANGE]
• Copy a single object: $ bce bos cp <bos-path> <bos-path>
• Copy objects in batch: $ bce bos cp <bos-path> <bos-path> --recursive

Note:

• When executing the command "bce bos cp bos:/bucket/obj1 bos:/bucket/obj2," an error will occur if the source and destination paths are identical. If the destination path exists, it will be overwritten.
• When executing the command "bce bos cp bos:/bucket/obj1 bos:/bucket/prefix/," obj1 will be copied to the prefix directory. The destination path must end with "/", otherwise, it will be treated as a new filename for creating a new file.
• When executing the command "bce bos cp bos:/bucket/obj1 bos:/bucket/prefix/ -r," if the source path is a single file, the operation will default to a single-file copy, placing obj1 in the prefix directory.
• When executing the command "bce bos cp bos:/bucket/prefix1/ bos:/bucket/prefix2/ -r" to copy one directory to another, both paths must end with "/". If the destination path does not end with "/", it will be treated as a single file, resulting in an error.
• For batch copy operations, the bos path must adhere to the "bucket/prefix" format.
• Users must hold appropriate permissions, including read access for the source bucket and write access for the destination bucket.
• For synchronous copying, "bos-dir" must represent a directory and cannot be a single file.
• --dryrun: Display the operations to be executed without actually carrying them out.
• --quiet: Perform uploads in synchronization mode without displaying intermediate processes.
• --delete: Removes files present in the source bucket but missing in the destination bucket, ensuring complete consistency between source and destination bucket data. The user will be prompted before any action is performed.
• --yes: Delete files without requiring confirmation.
• --exclude: Specify files to be skipped during a BOS-to-BOS synchronization. Support wildcards and multiple configurations. Example: --exclude 'bos:/mybucket/.tmp' --exclude 'bos:/mybucket/.svn' --exclude 'bos:/mybucket/test'.
• --exclude-time and --include-time: Their usage is identical to how they are used when synchronizing file uploads.

Example:

• Synchronize copying of files from bos:/mybucket/pres/to bos:/mybucket2/pre/

  Example:

  Plain Text Copy

  1$ bce bos sync bos:/mybucket/pre/ bos:/mybucket2/pre/

  Response example:

  Plain Text Copy

  1Copy: bos:/mybucket/pre/sts1.png to bos:/mybucket2/pre/sts1.png     
  2Copy: bos:/mybucket/pre/sts2.png to bos:/mybucket2/pre/sts2.png
  3Sync done: bos:/mybucket/pre/ to bos:/mybucket2/pre/, [2] success [0] failure

• Copy a single object

  Example:

  Plain Text Copy

  1$ bce bos cp bos:/mybucket/test.txt bos:/mybucket2/test.txt

  Response example:

  Plain Text Copy

  1Copy: bos:/mybucket/test.txt to bos:/mybucket2/test.txt

• Delete objects in batch

  Example:

  Plain Text Copy

  1$ bce bos cp bos:/mybucket/pre1/ bos:/bce-test/pre/ -r

  Response example:

  Plain Text Copy

  1Copy: bos:/mybucket/pre1/s1.png to bos:/bce-test/pre/s1.png
  2Copy: bos:/mybucket/pre1/s2.png to bos:/bce-test/pre/s2.png
  3[2] objects remote copied.

List objects

Description: The ls command can list up to 1,000 objects in a bucket. You can filter results by specifying a prefix.ls automatically uses "/" as a delimiter to achieve the effect of simulating a folder.

Command format: $ bce bos ls bos:/<bucket-name>/[prefix]

Operation example: bce bos ls bos:/mybucket/web

Response example:

1                                             PRE  pre/
22016-04-01 16:43:01            8698     STANDARD  web_bos.png
32016-04-01 16:41:49           17188     STANDARD  web_server_bos.png
42016-04-01 16:43:53           24620  STANDARD_IA  webtobos_cors.png
52016-04-01 16:45:53           24623         COLD  cold_abc.png

Note

• -a, --all: Displays all objects when the total count exceeds 1,000.
• -r, --recursive: Hides directory structures and directly displays underlying objects.
• -s, --summarize: Show statistical details like the number of objects and the total size.
• Example: The first column shows the object's creation date, the second column indicates the creation time, the third column specifies the object's size (in bytes), the fourth column highlights the storage class, and the fifth column contains the object's name.
• pre/ signifies a folder and does not display information about creation time or size.

Get object URL

Description: The gen_signed_url command can obtain a URL for a specified object, which can be used to download the object.

Command format $ bce bos gen_signed_url bos:/<bucket-name>/<object-key> [--expires TIME]

Note:

• The generated URL can be entered into a browser to directly download the object. Before creating the URL, ensure the configured AK/SK matches the AK/SK of the account associated with the bucket; otherwise, the URL will be invalid and cannot be used to download the object.
• --expires: Sets the URL's expiration time (in seconds). The value must be -1 or greater, where -1 indicates the URL is permanently valid.
• If no expiration time is set, the URL will default to an expiration time of 1,800 seconds.

Example:

• No specify the expiration time

  Example:

  Plain Text Copy

  1$ bce bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png

  Response example:

  Plain Text Copy

  1http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2Fd35a0b8750114e49b3567e0b0542c2f1%2F2016-08-25T02%3A03%3A57Z%2F1800%2F%2F96d77180ec2cb7e8de522c15ca42bf67c30bae0edb47bad495fe8e7953794a4f

• Specify the expiration time

  Example:

  Plain Text Copy

  1$ bce bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png -e 100

  Response example:

  Plain Text Copy

  1http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2F637986f41b0046248e3a333817371502%2F2017-08-31T03%3A19%3A42Z%2F100%2F%2F3e77accca7f0206460c662b0a9596b7ec353599214d42b124bb797a48da7359a

Delete Object

Command format:

• Delete a single object: $ bce bos rm [-y, --yes] bos:/<bucket-name>/<object-key>
• Batch deletion of objects: $ bce bos rm [-y, --yes] [-r, --recursive] bos:/<bucket-name>/<prefix>

Note:

• -y, --yes: Skip the confirmation step when this option is used.
• -r, --recursive: Delete multiple objects in batches.

Example:

• Delete a single object

  Example:

  Plain Text Copy

  1$ bce bos rm bos:/bce-temp/s1.png

  Response example:

  Plain Text Copy

  1Do you really want to REMOVE object bos:/bce-temp/s1.png? (Y/N) **Y**
  2Delete object: bos:/bce-temp/s1.png

• Delete objects in batches

  Example:

  Plain Text Copy

  1$ bce bos rm bos:/bce-test/pre/ -r

  Response example:

  Plain Text Copy

  1Delete object: bos:/bce-test/pre/s1.png
  2Delete object: bos:/bce-test/pre/s2.png
  3[2] objects removed on remote.

BOSAPI management

BOSAPI management includes lifecycle management and logging. The general command line format is bce bosapi [-h]

Set lifecycle

Description:Set [lifecycle management rules](BOS/Developer Guide/Data lifecycle management/Intelligent Business Analysis.md) for a specified bucket according to the provided lifecycle management file, or generate a lifecycle management file template.

Command format:

• Generate a transition configuration template: bce bosapi put-lifecycle --template
• Set lifecycle management rules for a bucket using a specified configuration file: bce bosapi put-lifecycle --lifecycle-config-file LIFECYCLE_CONFIG_FILE --bucket-name BUCKET_NAME

Example:

• Generate a transition configuration template

  Example:

  Plain Text Copy

  1$ bce bosapi put-lifecycle --template

  Response example:

  Plain Text Copy

  1{
  2  "rule": [
  3    {
  4      "action": {
  5      "name": "Transition",
  6      "storageClass": "STANDARD_IA"
  7    },
  8	"status": "enabled",
  9	"resource": [
  10	"${bucket_name}/${prefix}/*"
  11	 ],
  12	"id": "sample-id",
  13	"condition": {
  14	"time:": {
  15	   "dateGreaterThan": "$(lastModified)+P30D"
  16	  }
  17   }
  18  }
  19 ]
  20}

• Set lifecycle management rules for bucket1 using the configuration file 1.txt

  Example:

  Plain Text Copy

  1bce bosapi put-lifecycle --lifecycle-config-file lifecycle_bj.json --bucket-name bucket1

  Response example:

  Note:After successful setting, the lifecycle configuration file will be returned; otherwise, an error will be reported.

Get lifecycle configuration

Description:Get the lifecycle configuration of a specified bucket.

Command format: bce bosapi get-lifecycle --bucket-name BUCKET_NAME

Operation example: bce bosapi get-lifecycle --bucket-name bucket1

Response example:

1{
2  "rule": [
3    {
4      "action": {
5        "name": "Transition",
6        "storageClass": "STANDARD_IA"
7      },
8      "status": "enabled",
9      "resource": [
10        "bucket1/prefix1/*"
11      ],
12      "id": "sample-id",
13      "condition": {
14        "time:": {
15          "dateGreaterThan": "$(lastModified)+P30D"
16        }
17      }
18    }
19  ]
20}

Delete lifecycle configuration

Description:Delete the lifecycle configuration of a specified bucket.

Command format: bce bosapi delete-lifecycle --bucket-name BUCKET_NAME

Operation example: bce bosapi delete-lifecycle --bucket-name bucket1

Response example: None

Set logging rules

Description:Enable [access logging function](BOS/Developer Guide/Bucket Basic Operations/Set access logs.md) for a bucket and save logs to the specified prefix in a target bucket.

Command format: bce bosapi put-logging --target-bucket TARGET_BUCKET --target-prefix TARGET_PREFIX --bucket-name BUCKET_NAME

Operation example: bce bosapi put-logging --target-bucket bucket2 --target-prefix log --bucket-name bucket1

Response example: None

Get logging rules

Description:Get the access logging configuration of a specified bucket.

Command format: bce bosapi get-logging --bucket-name BUCKET_NAME

Operation example: bce bosapi get-logging --bucket-name bucket1

Response example:

1$ bce bosapi get-logging --bucket-name bucket1
2{
3  "status": "enabled",
4  "targetPrefix": "loggin/",
5  "targetBucket": "bucket1"
6}

Delete logging rules

Description:Delete the access log settings of a specified bucket.

Command format: bce bosapi delete-logging --bucket-name BUCKET_NAME

Operation example: bce bosapi delete-logging --bucket-name b1

Response example: None

Set default bucket storage class

Description:Set the default storage class for a specified bucket.

If the object uploaded via API, CLI, or SDK does not have a specified storage class, it follows the default storage class of the bucket. If the specified storage class of the uploaded object differs from the default storage class of the bucket, the storage class of the object shall apply. Storage classes include four types: standard storage (STANDARD), infrequent access storage (STANDARD_IA), cold storage (COLD), and archive storage (ARCHIVE). For specific usage scenarios and performance details, please refer to [Hierarchical Storage](BOS/Product Description/Tiered Storage Introduction/Introduction to storage classes.md). For setting the default storage class of a bucket via the console, please refer to [Create a Bucket](BOS/Console Operation Guide/Managing Bucket/Create bucket.md).

Command format:

1bce bosapi put-bucket-storage-class --bucket-name BUCKET_NAME --storage-class STORAGE_CLASS

Operation example:

1bce bosapi put-bucket-storage-class --bucket-name bucket1 --storage-class COLD`

Response example: None

Query the default bucket storage class

Description:This command is used to query the default storage class of a bucket. The default storage classes of a bucket include standard Storage, infrequent access storage and cold storage.

Command format:

1bce bosapi get-bucket-storage-class --bucket-name BUCKET_NAME

Operation example:

1bce bosapi get-bucket-storage-class --bucket-name bucket1

Response example:

1{"storageClass":"COLD"}

Get file meta information

Description:This command can be used to check whether an object exists and to get the object’s meta information. Specific rules are as follows:

1. If the specified object exists, bce will output the object’s meta information (including object name, object size, last modification time, and object storage class), and will exit with a status code of 0;
2. If the specified object does not exist, bce will print "Failed: The specified object does not exist" and exit with a status code of 2;
3. If an error occurs during bce execution, bce will print the error message and exit with a status code of 1.

Command format:

1bce bosapi get-object-meta --bucket-name BUCKET_NAME --object-name OBJECT_NAME [--schema SCHEMA | --quiet]

Note:

• If the file exists, the default output meta information includes the object's name, size, last modification time, and storage class. You can also customize the meta information to be displayed using --schema.
• --schema: You can specify the meta information to output. Currently supported values are "object_name", "content_length", "last_modified", and "bce_storage_class" (corresponding to object name, object size, last modification time and object storage class respectively). You can also specify multiple attributes of the object, with attribute names separated by commas. For example: Use --schema "object_name,content_length" to specify output of the object name and size; use --schema "last_modified" to specify output of only the object's modification time.
• --quiet: bce suppresses displaying intermediate processes (but will print error messages if an issue arises).

Operation example:

Get all meta information of an object:

Example:

1bce bosapi get-object-meta --bucket-name mybucket --object-name myobject

Response example:

1Success: {"object_name": "myobject", "content_length": "37", "last_modified": "Fri, 26 Jan 2018 08:51:38 GMT", "bce_storage_class": "STANDARD"}

Get size and storage class information of an object:

1bce bosapi get-object-meta --bucket-name mybucket --object-name myobject  --schema "content_length,bce_storage_class"

Response example:

1Success: {"content_length": "37", "bce_storage_class": "STANDARD"}

Get meta information of a non-existent object:

Example:

1bce bosapi get-object-meta --bucket-name mybucket --object-name noexist

Response example:

1Failed: The specified object does not exist

Image review service

Description:Audit the specified image on BOS and output the text recognition results and the probability of the image category attribution.

Command format: bce bos process img-censor bos:/<bucket-name>/<object-key> --parameter <local json file>

Note:

• bos://: The image file to be audited.
• --parameter: A local JSON file containing parameters related to image auditing. The JSON file should be UTF-8 encoded without BOM, structured as follows:

Plain Text Copy

1   {
2     "antiporn" : {},
3     "terror" : {},
4     "ocr" : {
5         "detect_direction" : "false",
6         "language_type" : "CHN_ENG",
7         "recognize_granularity" : "big"
8     }
9   }

• Parameters can include one or multiple sub-services as needed or a single sub-service like "pornographic content detection." The image review service supports the following sub-services:

  • ocr: General optical character recognition
  • face: Face detection
  • antiporn: Pornography recognition
  • politician: Politician recognition
  • terror: Violent terrorism recognition
  • public: Public figure recognition
  • webimage: Web image OCR recognition
  • disgust: Disgusting image recognition
  • watermark: Watermark QR code recognition
  • Quality: Image quality recognition values correspond to underlying service parameters. Refer to the input parameters of the Hetu general optical character recognition (OCR) service.

Operation example:

1. Create an image audit parameter file, assuming that it is stored in ~/param.txt, with the following content:

   Plain Text Copy

   1  {
   2    "ocr" : {
   3      "detect_direction" : "false",
   4      "language_type" : "CHN_ENG",
   5      "recognize_granularity" : "big"
   6    },
   7    "antiporn" : {}
   8  }

2. Call cli

bce bos process img-censor bos:/mybucket/img.jpg --parameter ~/param.txt

Response example:

1{
2	"result" : {
3		"antiporn" : {
4			"result" : [{
5					"probability" : 0.000071,
6 "class_name": "Pornography"
7				}, {
8					"probability" : 0.000291,
9 "class_name": "Sexy"
10				}, {
11					"probability" : 0.999638,
12 "class_name": "Normal"
13				}
14			],
15			"log_id" : 3066483724,
16			"result_num" : 3
17		},
18		"ocr" : {
19			"log_id" : 2471272194,
20			"words_result_num" : 2,
21			"words_result" : [{
22					"words" : " TSINGTAO"
23				}, {
24 "words": "Tsingtao Beer"
25				}
26			]
27		}
28	},
29	"log_id" : 149803506446902
30}

Android batch packaging

Description:Batch packaging the APK master pack according to the channel configuration file on BOS to generate multiple channel packs.

Command format:

• Batch packaging:bce bos process apk-pack bos:// --parameter `
• Batch packaging and return notification: bce bos process apk-pack bos:/<bucket-name>/<object-key> --parameter <local json file> --url <notify url>

Note:

• bos://: The APK file to be packaged.

• --parameter: A local json file containing parameters related to packaging. The parameter is the description of json, encoded in utf-8 without BOM. As follows: { "algorithm" : "v1", "channelFile" : "", "targetPrefix" : "" }

  • algorithm: packaging algorithm; currently only "v1" is supported.
  • channelFile: The channel file for packaging, which must be uploaded to bos and can be a prefix or a direct file name. The channel file must be a TSV (tab separated values) file. The first line must be insertedFileName and distributedPackageName, with the two columns representing the null file name and the channel package name respectively, and the two fields must be separated by a tab (not spaces). Example is as follows: insertedFileName distributionPackageName file_123 my_123.apk file_222 bbb_222.apk
• targetPrefix: The prefix where the packaged output APKs are stored
• --url: Provide the post with the packaging result after packaging is complete

Operation example:

Suppose the bucket storing the file to be packaged is named mybucket, the file to be packaged is located at /pre/mygame.apk, the channel file is pre2/channelFile.tsv, and the packaged APK output files are stored in mybucket under p1/p2/. The content of channelFile.tsv is as follows:

1insertedFileName	distributionPackageName
2file_123	my_123.apk
3file_222	bbb_222.apk

1. Create a packaging parameter file, assuming that it is stored in ~/param.txt, with the following content:

   Plain Text Copy

   1  {
   2  		"algorithm" : "v1",
   3  		"channelFile" : "pre2/channelFile.tsv",
   4  		"targetPrefix" : "p1/p2/"
   5  }

2. Call the cli and return the callback API

bce bos process apk-pack bos:/mybucket/pre/mygame.apk --parameter ~/param.txt --url http://myserver.com

Response example:

1{
2    "code": 66,
3    "requestId": "71a95440-c7b9-4503-b41a-a7644863d7dc",
4    "jobIds": [
5        "342-172707368",
6        "341-172707368"
7    ]
8}

• 342-172707368: packaged jobid;
• 341-172707368: The callback parameter job ID.

When the packaging ends normally, http://myserver.comyou will receive a result request: code=success&jobId=342-172707368. At this time, the packaged files my_123.apk and bbb_222.apk will be stored under p1/p2/ in mybucket.