Compatible Tools

Updated at：2025-11-03

Compatibility notes

Most tools developed for AWS S3 can be adapted to configure the access address. You can use these tools to access BOS by setting their access address to the AWS S3 Service Domain of BOS. Below are examples using common SDKs and tools to demonstrate how to connect to BOS.

Description:

String Meaning

$ACCESS_KEY Baidu AI Cloud account Access key

$SECRET_KEY Baidu AI Cloud Account Secret key

String	Meaning
$ACCESS_KEY	Baidu AI Cloud account Access key
$SECRET_KEY	Baidu AI Cloud Account Secret key

AWS SDK for Python

Install Boto library:
Plain Text
```
1pip install boto3
```

Access BOS using AWS SDK for python

Plain Text

1import boto3
2from botocore.client import Config
3s3 = boto3.client(
4        's3',
5        aws_access_key_id=$ACCESS_KEY,
6        aws_secret_access_key=$SECRET_KEY,
7        endpoint_url='http://s3.bj.bcebos.com',
8        region_name='bj',
9        config = Config(
10            signature_version='s3v4',
11        )
12     )
13# Use S3 client
14s3.create_bucket(...)

AWS SDK for Java

Add dependency package to pom.xml

Plain Text

1// Add the following AWS Java SDK dependency package to pom.xml
2<dependency>
3  <groupId>com.amazonaws</groupId>
4  <artifactId>aws-java-sdk</artifactId>
5  <version>1.11.82</version>
6</dependency>

Access BOS using AWS SDK for java

Plain Text

1import java.io.IOException;
2import com.amazonaws.services.s3.AmazonS3;
3import com.amazonaws.services.s3.AmazonS3Client;
4import com.amazonaws.services.s3.model.*;
5import com.amazonaws.services.s3.S3ClientOptions;
6import com.amazonaws.auth.BasicAWSCredentials;
7import com.amazonaws.SDKGlobalConfiguration;
8
9public class S3Sample {
10    public static void main(String[] args) throws IOException {
11        System.setProperty(SDKGlobalConfiguration.ENABLE_S3_SIGV4_SYSTEM_PROPERTY, "true");
12        AmazonS3 s3 = new AmazonS3Client(new BasicAWSCredentials($ACCESS_KEY,$SECRET_KEY));
13        s3.setEndpoint("s3.bj.bcebos.com");
14        S3ClientOptions options = new S3ClientOptions();
15        options.withChunkedEncodingDisabled(true);
16        s3.setS3ClientOptions(options);
17
18        // Use S3 Client
19        s3.createBucket(...);
20    }
21
22}

Compile code
Plain Text
```
1mvn package
```

AWS PHP SDK

Installation: Download aws.phar. For more installation methods, see AWS PHP SDK Installation Method.

Access BOS using AWS SDK for PHP

Plain Text

1<?php    
2require 'aws.phar';                  
3use Aws\S3\S3Client;
4use Aws\Exception\AwsException;     
5
6$s3Client = new S3Client([          
7    'version'     => 'latest',
8    'region'      => 'bj',
9    'credentials' => [
10        'key'    => $ACCESS_KEY,
11        'secret' => $SECRET_KEY,
12    ],
13    'endpoint' => 'https://s3.bj.bcebos.com',
14    'signature_version' => 'v4',
15]);
16
17$buckets = $s3Client->listBuckets();
18foreach ($buckets['Buckets'] as $bucket){
19    echo $bucket['Name']."\n";
20}

AWS Golang SDK

Install
Plain Text
```
1go get -u github.com/aws/aws-sdk-go
```

Access Bos using AWS SDK for Golang

Plain Text

1import (
2    "github.com/aws/aws-sdk-go/aws"                                            
3    "github.com/aws/aws-sdk-go/aws/session"
4    "github.com/aws/aws-sdk-go/service/s3"
5    "github.com/aws/aws-sdk-go/aws/credentials"
6)
7conf := &aws.Config{
8        Region:           aws.String("bj"),
9        Endpoint:         aws.String("s3.bj.bcebos.com"),
10        Credentials:      credentials.NewStaticCredentials($ACCESS_KEY, $SECRET_KEY,, ""),
11    }
12sess := session.Must(session.NewSessionWithOptions(session.Options{Config:*conf}))
13svc := s3.New(sess)
14getObjectParams := &s3.GetObjectInput{
15        Bucket:             aws.String("my-bucket"),
16        Key:                aws.String("my-object"),
17}
18getObjectResp, err := svc.GetObject(getObjectParams)
19if err != nil {
20    fmt.Println(err.Error())
21    return
22}

AWS JavaScript SDK

1. Installation and pre-dependency

Environmental requirements

npm or yarn package manager
Node.js environment: Node.js 14.x or higher versions
Browser environment
- Modern browser environments (supporting ES6+)
- Support ES Modules or use packaging tools (e.g., Webpack, Vite, etc.)

Install dependency packages

                Bash
                
            

                # Install the core S3 client
npm install @aws-sdk/client-s3
# Install multipart upload tool
npm install @aws-sdk/lib-storage
# Install STS client (for temporary credentials)
npm install @aws-sdk/client-sts
# Install credential provider (browser environment)
npm install @aws-sdk/credential-providers
            

Browser environment CDN

Online ES modules can be imported via CDN services like skypack, jsdelivr, etc.

                HTML
                
                <script type="module">
  import {S3Client, CreateBucketCommand, PutObjectCommand, GetObjectCommand, DeleteObjectCommand} from 'https://cdn.skypack.dev/@aws-sdk/client-s3@3.826.0';
  import {Upload} from 'https://cdn.skypack.dev/@aws-sdk/lib-storage@3.826.0';
</script>

Service domain

For example, Beijing: https://s3.bj.bcebos.com
For all compatible domain names, refer to: https://cloud.baidu.com/doc/BOS/s/xjwvyq9l4

2. Initialize configuration

2.1 Node.js server-side access mode (fixed AK/SK)

                Javascript
                
            

                import { S3Client } from '@aws-sdk/client-s3';
const s3Client = new S3Client({
    region: 'bj',
    endpoint: 'https://s3.bj.bcebos.com',
    credentials: {
        accessKeyId: '<your-access-key>',
        secretAccessKey: '<your-secret-access-key>'
    }
});
            

2.2 Browser STS access mode

                Javascript
                
            

                import {S3Client} from '@aws-sdk/client-s3';
const s3Client = new S3Client({
    region: 'bj',
    endpoint: 'https://s3.bj.bcebos.com',
    credentials: {
        accessKeyId: '<your-access-key>',
        secretAccessKey: '<your-secret-access-key>'
 /** Temporary credentials, optional, obtained via Baidu AI Cloud STS service*/
        sessionToken: '<your-session-token>'
    }
});
            

3. Common mode examples

3.1 Create a bucket

                Javascript
                
            

                import { CreateBucketCommand } from '@aws-sdk/client-s3';
/**
 * Create a bucket
 *
 * @param {string} bucketName Bucket name
 */
async function createBucket(bucketName) {
  try {
    const command = new CreateBucketCommand({
 /** Bucket name */
      Bucket: bucketName,
 /** Bucket configuration */
      CreateBucketConfiguration: {
 /** Bucket region */
        LocationConstraint: 'bj'
      }
    });
    const response = await s3Client.send(command);
 console.log ('Bucket created successfully:', response);
    return response;
  } catch (error) {
 console.error ('Failed to create bucket:', error);
    throw error;
  }
}
 // Usage example
await createBucket('my-test-bucket-beijing-2024');
            

3.2 Simple upload (PutObject)

Node.js environment

                Javascript
                
            

                import fs from 'fs';
import {PutObjectCommand} from '@aws-sdk/client-s3';
/**
 * Upload files in Node.js environment
 *
 * @param {string} bucketName Bucket name
 * @param {string} key Object name
 * @param {string} filePath Local file path
 * @returns
 */
async function uploadFile(bucketName, key, filePath) {
  try {
    const fileContent = fs.readFileSync(filePath);
    const command = new PutObjectCommand({
      Bucket: bucketName,
      Key: key,
      Body: fileContent,
      ContentType: 'application/octet-stream',
      Metadata: {
        'uploaded-by': 'aws-sdk-v3',
        'upload-time': new Date().toISOString()
      }
    });
    const response = await s3Client.send(command);
 console.log('File uploaded successfully:', response);
    return response;
  } catch (error) {
 console.error('File upload failed:', error);
    throw error;
  }
}
 // Usage example
await uploadFile('my-test-bucket', 'documents/test.pdf', './local-file.pdf');
            

Browser environment

                Javascript
                
            

                import {PutObjectCommand} from '@aws-sdk/client-s3';
/**
 * Upload files in browser environment
 *
 * @param {string} bucketName Bucket name
 * @param {string} key Object name
 * @param {File} file File object
 * @returns
 */
async function uploadFileFromBrowser(bucketName, key, file) {
  try {
    const command = new PutObjectCommand({
      Bucket: bucketName,
      Key: key,
      Body: file,
      ContentType: file.type || 'application/octet-stream'
    });
    
    const response = await s3Client.send(command);
 console.log('File uploaded successfully:', response);
    return response;
  } catch (error) {
 console.error('File upload failed:', error);
    throw error;
  }
}
 // Usage example
 // Assume the page contains an upload control: <input type="file" id="fileUpload">
const fileInput = document.getElementById('fileUpload');
const file = fileInput.files[0];
await uploadFileFromBrowser('my-test-bucket', 'documents/test.pdf', file);
            

3.3 Multipart upload

Node.js environment

                Javascript
                
            

                import fs from 'fs';
import {Upload} from '@aws-sdk/lib-storage';
/**
 * Upload files in Node.js environment shard
 *
 * @param {string} bucketName Bucket name
 * @param {string} key Object name
 * @param {string} filePath Local file path
 */
async function multipartUpload(bucketName, key, filePath) {
  try {
    const fileStream = fs.createReadStream(filePath);
    const upload = new Upload({
      client: s3Client,
      params: {
        Bucket: bucketName,
        Key: key,
        Body: fileStream,
        ContentType: 'application/octet-stream'
      },
 /** Concurrent upload count, optional parameter*/
      queueSize: 4,
 /** Shard size, optional parameter, minimum 5MB*/
      partSize: 5 * 1024 * 1024,
 /** Whether to retain uploaded multipart upon failure, optional parameter*/
      leavePartsOnError: false
    });
 /** Monitor upload progress*/
    upload.on('httpUploadProgress', (progress) => {
 console.log (`Upload progress: ${Math.round(progress.loaded / progress.total * 100)}%`);
    });
    const response = await upload.done();
 console.log ('Multipart upload completed:', response);
    return response;
  } catch (error) {
 console.error('Shard upload failed:', error);
    throw error;
  }
}
 // Usage example
await multipartUpload('my-test-bucket', 'large-files/video.mp4', './large-video.mp4');
            

Browser environment

                Javascript
                
            

                import {Upload} from '@aws-sdk/lib-storage';
/**
 * Upload files in browser environment shard
 *
 * @param {string} bucketName Bucket name
 * @param {string} key Object name
 * @param {File} file File object
 */
async function multipartUploadBrowser(bucketName, key, file) {
  try {
    const upload = new Upload({
      client: s3Client,
      params: {
        Bucket: bucketName,
        Key: key,
        Body: file,
        ContentType: file.type || 'application/octet-stream'
      },
 /** Concurrent upload count, optional parameter*/
      queueSize: 4,
 /** Shard size, optional parameter, minimum 5MB*/
      partSize: 5 * 1024 * 1024,
 /** Whether to retain uploaded multipart upon failure, optional parameter*/
      leavePartsOnError: false
    });
    upload.on('httpUploadProgress', (progress) => {
      const percent = Math.round(progress.loaded / progress.total * 100);
 console.log (`Upload progress: ${percent}%`);
 // Update progress bar UI
    });
    const response = await upload.done();
 console.log ('Multipart upload completed:', response);
    return response;
  } catch (error) {
 console.error('Shard upload failed:', error);
    throw error;
  }
}
 // Usage example
 // Assume the page contains an upload control: <input type="file" id="fileUpload">
const fileInput = document.getElementById('fileUpload');
const file = fileInput.files[0];
await multipartUploadBrowser('my-test-bucket', 'large-files/video.mp4', file);
            

3.4 Download file

Node.js environment

                Javascript
                
            

                import fs from 'node:fs';
import {pipeline} from 'node:stream/promises';
import {GetObjectCommand} from '@aws-sdk/client-s3';
/**
 * Download files in Node.js environment
 *
 * @param {string} bucketName Bucket name
 * @param {string} key Object name
 * @param {string} downloadPath Local download path
 */
async function downloadFile(bucketName, key, downloadPath) {
  try {
    const command = new GetObjectCommand({
      Bucket: bucketName,
      Key: key
    });
    const response = await s3Client.send(command);
    const writeStream = fs.createWriteStream(downloadPath);
    await pipeline(response.Body, writeStream);
 console.log ('File downloaded successfully:', downloadPath);
    return downloadPath;
  } catch (error) {
 console.error('File download failed:', error);
    throw error;
  }
}
 // Usage example
await downloadFile('my-test-bucket', 'documents/test.pdf', './downloaded-file.pdf');
            

Browser environment

                Javascript
                
            

                import {GetObjectCommand} from '@aws-sdk/client-s3';
/**
 * Download files in browser environment
 *
 * @param {string} bucketName Bucket name
 * @param {string} key Object name
 */
async function downloadFileInBrowser(bucketName, key) {
  try {
    const command = new GetObjectCommand({
      Bucket: bucketName,
      Key: key
    });
    
    const response = await s3Client.send(command);
    
    const blob = await response.Body.transformToByteArray();
    const file = new Blob([blob], {
      type: response.ContentType || 'application/octet-stream'
    });
    
    const url = URL.createObjectURL(file);
    const downloadLink = document.createElement('a');
    downloadLink.href = url;
    downloadLink.download = key.split('/').pop();
    downloadLink.click();
    URL.revokeObjectURL(url);
   
    
 console.log (`File downloaded successfully: ${key}`);
    return blob;
  } catch (error) {
 console.error('File download failed:', error);
    throw error;
  }
}
 // Usage example
await downloadFileInBrowser('my-test-bucket', 'documents/test.pdf');
            

3.5 Obtain file download link

                Javascript
                
            

                import {GetObjectCommand} from '@aws-sdk/client-s3';
import {getSignedUrl} from '@aws-sdk/s3-request-presigner';
/**
 * Obtain object download link URL
 *
 * @param {string} bucketName Bucket name
 * @param {string} key Object name
 * @param {number} expiresIn Expiration time, in seconds
 * @returns
 */
async function getDownloadUrl(bucketName, key, expiresIn = 3600) {
  try {
    const command = new GetObjectCommand({
      Bucket: bucketName,
      Key: key
    });
    const url = await getSignedUrl(s3Client, command, {expiresIn});
 console.log ('Presigned download URL:', url);
    return url;
  } catch (error) {
 console.error ('Failed to generate download:', error);
    throw error;
  }
}
 // Usage example
const downloadUrl = await getDownloadUrl('my-test-bucket', 'documents/test.pdf', 7200);
            

3.6 Delete files

                Javascript
                
            

                import {DeleteObjectCommand, DeleteObjectsCommand } from '@aws-sdk/client-s3';
/**
 * Delete single file
 *
 * @param {string} bucketName Bucket name
 * @param {string} key Object name
 */
async function deleteFile(bucketName, key) {
  try {
    const command = new DeleteObjectCommand({
      Bucket: bucketName,
      Key: key
    });
    const response = await s3Client.send(command);
 console.log('File deletion successful:', response);
    return response;
  } catch (error) {
 console.error('File deletion failed:', error);
    throw error;
  }
}
/**
 * Delete files in batch
 *
 * @param {string} bucketName Bucket name
 * @param {string[]} keys object name array
 */
async function deleteMultipleFiles(bucketName, keys) {
  try {
    const command = new DeleteObjectsCommand({
      Bucket: bucketName,
      Delete: {
 /** Object name list*/
        Objects: keys.map(key => ({Key: key})),
 /** Whether to enable silent deletion*/
        Quiet: false
      }
    });
    const response = await s3Client.send(command);
 console.log('File batch deletion successful:', response);
    return response;
  } catch (error) {
 console.error('File batch deletion failed:', error);
    throw error;
  }
}
 // Usage example
await deleteFile('my-test-bucket', 'documents/test.pdf');
await deleteMultipleFiles('my-test-bucket', ['file1.txt', 'file2.txt', 'folder/file3.jpg']);
            

4. Common error descriptions

4.1 Server-side errors

For common errors and corresponding descriptions, refer to: https://cloud.baidu.com/doc/BOS/s/Ajwvysfpl

                Javascript
                
            

                // Error handling example
async function handleS3Errors() {
  try {
 // Your S3 operation code
  } catch (error) {
 console.error ('S3 operation failed:', error);
 /** Error codes */
    console.log(error.Code);
 /** Error message*/
    console.log(error.message);
 /** HTTP status code*/
    console.log(error.$metadata.httpStatusCode);
 /** Request ID */
    console.log(error.RequestId);
    console.log(error.$metadata.requestId);
    /** x-bce-debug-id */
    console.log(error.$metadata.extendedRequestId);
  }
}
            

4.2 Common issues and solutions

Plain Text

1Issue 1: Insufficient permissions
2 Error: AccessDenied: User is not authorized to perform: s3:PutObject
3 Solution: Verify if the IAM policy includes required permissions

Plain Text

1Issue 2: CORS Configuration issue (browser environment)
2 Error: Access to XMLHttpRequest blocked by CORS policy
3 Solution: Configure CORS in the bucket

4.3 Debugging suggestions

1. Enable detailed logs:

                Javascript
                
            

                import { S3Client } from '@aws-sdk/client-s3';
const s3Client = new S3Client({
    region: 'bj',
    endpoint: 'https://s3.bj.bcebos.com',
    credentials: {
        accessKeyId: '<your-access-key>',
        secretAccessKey: '<your-secret-access-key>'
    }
 /* Enable detailed logs:*/
    logger: console,
 /* Request settings*/
    requestHandler: {
        connectionTimeout: 5000,
        socketTimeout: 10000
    }
});
            

2. Check network connection:

Bash

1# Test Endpoint connection
2curl -I https://s3.bj.bcebos.com

AWS CLI tools

Install AWS CLI tools
Plain Text
```
1pip install awscli
```
Access BOS using AWS CLI

Edit configuration files

Plain Text

1$ aws configure
2AWS Access Key ID [Nonel: <access_key_id>
3AWS Secret Access Key [Nonel: <access_key_secret>
4Default region name [None]: auto
5Default output format [Nonel: json

Execute command example

Plain Text

1aws s3api list-buckets --endpoint-url https://s3.bj.bcebos.com
2aws s3api list-objects --bucket bucketname --endpoint-url https://s3.bj.bcebos.com

Reference documentation

https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html

Hadoop S3A tool

S3A is the official Hadoop toolkit for using S3 in Hadoop systems. With S3A, you can operate S3 storage like hdfs. Currently, BOS supports most commonly used S3A.functions. For more detailed introductions to S3A, please refer to: S3 Support in Apache Hadoop and Hadoop-AWS module: Integration with Amazon Web Services.

Download dependency packages
- Ensure the following dependency packages exist in the Hadoop system:
- Use the BOS-compatible JAR package: Since BOS currently has limited support for some S3 functions, it is recommended to use this customized toolkit for the best experience.
BOS-compatible Jar package MD5 code

hadoop-aws-2.8.0.jar 6ffbdc9352b9399e169005aeeb09ee98

BOS-compatible Jar package	MD5 code
hadoop-aws-2.8.0.jar	6ffbdc9352b9399e169005aeeb09ee98

Modify the relevant S3A configurations

Plain Text

1<property>
2	<name>fs.s3a.endpoint</name>
3	<value>http://s3.bj.bcebos.com</value>
4</property>
5<property>
6	<name>fs.s3a.signing-algorithm</name>
7	<value>AWSS3V4SignerType</value>
8</property>	
9 <!-- Enable BOS backend API-->
10<property>
11    <name>fs.s3a.bos.compat.access</name>
12	<value>true</value>
13</property>
14<property>
15<name>fs.s3a.access.key</name>
16<value>$ACCESS_KEY</value>
17</property>
18<property>
19<name>fs.s3a.secret.key</name>
20<value>$SECRET_KEY</value>
21</property>

Use S3A to experience BOS Service in a Hadoop environment, and execute the command
Plain Text
```
1hadoop fs -ls s3a://$YOUR_BUCKET_NAME
```
How to modify Hadoop-AWS independently

(1). Download Hadoop source code (2). Modify the hadoop-2.8.0-src/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3ClientFactory.java file. Since BOS does not yet support Chunked Upload, and the Java SDK uses this method by default for write operations, this operation of SDK must be disabled in the code.
Plain Text
```
1// Locate the AWS Client used by S3A, e.g.:
2 // Under the createAmazonS3Client function
3// AmazonS3 s3 = new AmazonS3Client(credentials, awsConf);
4 // Add disable-chunkedencoding to the AWS Client
5s3.setS3ClientOptions(new S3ClientOptions().withChunkedEncodingDisabled(true));
```
(3). Compile to obtain the JAR package
Plain Text
```
1cd hadoop-2.8.0-src/hadoop-tools/hadoop-aws
2mvn package
```

CloudBerry Explorer for Amazon S3

CloudBerry Explorer for Amazon S3 is an S3 graphical data management software provided by CloudBerry Lab. Its graphical interface is highly powerful, supporting management operations such as data upload, download, synchronization and deletion from the local to the cloud.

Baidu AI Cloud now also supports managing BOS resources via CloudBerry Explorer!

Download the software version matching your operating system, install it, and proceed with the setup.

Note: This software supports both free and paid versions. You can directly use the free version.
After installation, configure the cloud storage first and select "S3 Compatible":
Add a new S3 Compatible account. Enter BOS as the display name, the BOS service domain as the service point, and [Baidu AI Cloud AK/SK](Reference/Retrieve AK and SK/How to Obtain AKSK.md) as the access key and secret key. AWS S3-compatible service domain currently does not support HTTPS. Please uncheck "Use SSL" and select Signature Version 4.
Click "Test Connection" to confirm connectivity. A message saying "Connection success" will indicate a successful connection.
Now you can use CloudBerry Explorer for various data management tasks!

Compatible Common Headers

Security and compliance