創建桶

功能說明

桶（Bucket）是用于存儲對象（Object）的容器，所有的對象都必須隸屬于某個桶。您可以通過createBucket接口創建桶。

代碼示例

public void createBucket() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("createBucket");
    Bucket createdBucket = s3Client.createBucket(bucket);
    System.out.println("Bucket Name:" + createdBucket.getName());
}

請求參數

返回結果

關于Bucket一些說明

獲取桶列表

功能說明

桶（Bucket）是用于存儲對象（Object）的容器，所有的對象都必須隸屬于某個桶。您可以通過listBuckets接口獲取桶列表信息。

代碼示例

public void listBuckets() throws AmazonClientException {
    System.out.println("listBuckets");
    List<Bucket> buckets = s3Client.listBuckets();
    for (Bucket bucket : buckets) {
        System.out.println("Bucket Name:" + bucket.getName());
        System.out.println("Bucket Creation Date:" + bucket.getCreationDate());
        System.out.println("Bucket Owner:" + bucket.getOwner());
    }
}

返回結果

關于Bucket一些說明

判斷桶是否存在

功能說明

桶（Bucket）是用于存儲對象（Object）的容器，所有的對象都必須隸屬于某個桶。您可以使用 doesBucketExist 接口判斷桶是否存在。

代碼示例

public void doesBucketExist() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("doesBucketExist");
    boolean exists = s3Client.doesBucketExistV2(bucket);
    if (exists) {
        System.out.printf("Bucket %s already exists.\n", bucket);
    } else {
        System.out.printf("Bucket %s not exists.\n", bucket);
    }
}

請求參數

返回結果

刪除桶

功能說明

桶（Bucket）是用于存儲對象（Object）的容器，所有的對象都必須隸屬于某個桶。您可以通過deleteBucket 接口刪除桶。刪除一個桶前，需要先刪除該桶中的全部對象（包括對象版本）。

代碼示例

public void deleteBucket() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    s3Client.deleteBucket(bucket);
}

請求參數

設置桶訪問權限

功能說明

桶（Bucket）是用于存儲對象（Object）的容器，所有的對象都必須隸屬于某個桶。您可以通過setBucketAcl 接口設置桶的訪問權限。桶訪問權限包含了CannedAccesssControlList 與AccessControlList 兩種格式。CannedAccesssControlList 提供了預定義的權限控制，如私有讀寫，公共讀私有寫，公共讀寫，AccessControlList 提供了更細致的權限控制，可自定義更多權限控制。用戶在設置 bucket 的 ACL 之前需要具備 WRITE_ACP 權限。

代碼示例

• CannedAccesssControlList

public void setBucketAcl1() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("setBucketAcl");
    s3Client.setBucketAcl(bucket, CannedAccessControlList.PublicRead);
    System.out.println("setBucketAcl success");
}

• AccessControlList

public void setBucketAcl2() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("setBucketAcl");
    // 增加用戶exampleuser的Write權限
    AccessControlList controlList = s3Client.getBucketAcl(bucket);
    CanonicalGrantee canonicalGrantee = new CanonicalGrantee("exampleuser");//開啟用戶exampleuser的Write權限
    controlList.grantPermission(canonicalGrantee,Permission.Write);
?
    s3Client.setBucketAcl(bucket, controlList);
    System.out.println("setBucketAcl success");
}

請求參數

• CannedAccesssControlList

關于 CannedAccessControlList 的說明：

• AccessControlList

使用 AccessControlList 設置桶訪問權限時，可以設置特定用戶對桶的訪問權限。桶的 AccessControlList 權限如下表：

在 AccessControlList 中可通過 grantAllPermission 傳入 Grant 設置權限，Grant 中關于Permission說明如下：

獲取桶訪問權限

功能說明

桶（Bucket）是用于存儲對象（Object）的容器，所有的對象都必須隸屬于某個桶。您可以通過getBucketAcl接口獲取桶的訪問權限。

代碼示例

public void getBucketAcl() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("getBucketAcl");
    AccessControlList controlList = s3Client.getBucketAcl(bucket);
    List<Grant> grants = controlList.getGrantsAsList();
    System.out.println("getBucketAcl: owner=" + controlList.getOwner());
    for (Grant grant: grants){
        System.out.println("getBucketAcl: grantee=" + grant.getGrantee().getIdentifier()
                           + ", permission=" + grant.getPermission());
    }
}

請求參數

返回結果

返回的 AccessControlList 中包含的屬性：

關于 AccessControlList 中的訪問權限說明可參考 設置桶訪問權限 一節。

設置桶策略

功能說明

桶策略（Bucket Policy）可以靈活地配置用戶各種操作和訪問資源的權限。如果桶已經被設置了policy，則新的policy會覆蓋原有的policy。關于 policy 的具體說明請參考 桶策略說明 。

您可以使用 setBucketPolicy 接口設定桶策略，您可以執行以下操作：

• 使用 JSON 格式的文本字符串直接指定策略。

• 使用 Policy 類構建策略，再轉換為 JSON 格式的字符串。

您可以使用 Policy 類構建策略，免除設置文本字符串出現格式錯誤的麻煩，構建完成后使用 toJson 方法可以獲取 JSON 策略文本。

policy的示例如下：

{
    "Id":"PolicyId",
    "Version":"2012-10-17",
    "Statement":[
        {
            "Sid":"ExampleStatementID1",
            "Principal":{
                "AWS":[
                    "arn:aws:iam:::user/userId",
                    "arn:aws:iam:::user/userName"
                ]
            },
            "Effect":"Allow",
            "Action":[
                "s3:ListBucket",
                "s3:CreateBucket"
            ],
            "Resource":[
                "arn:aws:iam:::exampleBucket"
            ],
            "Condition":"some conditions"
        },
        ......
    ]
}

Statement的內容說明如下：

代碼示例

• 使用 JSON 格式的文本字符串直接指定策略。

public void setBucketPolicy1() throws AmazonClientException {
    // 以下示例策略允許exampleuser1, exampleuser2用戶可讀取桶內對象。
    String bucket = "<your-bucket-name>";
    System.out.println("setBucketPolicy");
    String bucketPolicy = "{\n" +
        "                \"Version\": \"2012-10-17\",\n" +
        "                \"Statement\": [{\n" +
        "                    \"Sid\": \"1\",\n" +
        "                    \"Effect\": \"Allow\",\n" +
        "                    \"Principal\": {\"AWS\": [\n" +
        "                                               \"arn:aws:iam:::user/exampleuser1\",\n" +
        "                                               \"arn:aws:iam:::user/exampleuser2\"\n" +
        "                                         ]},\n" +
        "                    \"Action\": [\"s3:GetObject\"],\n" +
        "                    \"Resource\": [\"arn:aws:s3:::" + bucket + "/*\"]\n" +
        "                }]\n" +
        "            }";
    s3Client.setBucketPolicy(bucket, bucketPolicy);
}

• 使用 Policy 類構建策略，再轉換為 JSON 格式的字符串。

public void setBucketPolicy2() throws AmazonClientException {
    // 以下示例策略允許exampleuser1, exampleuser2用戶可讀取桶內對象。
    String bucket = "<your-bucket-name>";
    System.out.println("setBucketPolicy");
    Policy bucketPolicy = new Policy().withStatements(
        new Statement(Statement.Effect.Allow)//指定本條桶策略描述的權限為允許請求
        .withPrincipals(Principal.AllUsers)
        .withPrincipals(new Principal("AWS", "arn:aws:iam:::user/exampleuser1"), //對exampleuser1用戶生效
                        new Principal("AWS", "arn:aws:iam:::user/exampleuser2"))//對exampleuser2用戶生效
        .withActions(S3Actions.GetObject)//操作為GetObject
        .withResources(new Resource("arn:aws:s3:::" + bucket + "/*")));//指定資源為桶內所有對象
    s3Client.setBucketPolicy(bucket, bucketPolicy.toJson());
}

參數說明

獲取桶策略

功能說明

桶策略（Bucket Policy）可以靈活地配置用戶各種操作和訪問資源的權限。您可以使用 getBucketPolicy 接口獲取桶策略。

代碼示例

public void getBucketPolicy() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("getBucketPolicy");
    BucketPolicy policy = s3Client.getBucketPolicy(bucket);
    System.out.println("getBucketPolicy success, " + policy.getPolicyText());
}

參數說明

返回結果

關于返回的 BucketPolicy 的具體說明請參考 桶策略說明 。

刪除桶策略

功能說明

桶策略（Bucket Policy）可以靈活地配置用戶各種操作和訪問資源的權限，您可以使用 deleteBucketPolicy 接口刪除桶策略。

代碼示例

public void deleteBucketPolicy() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("deleteBucketPolicy");
    s3Client.deleteBucketPolicy(bucket);
}

請求參數

設置桶生命周期配置

功能說明

生命周期管理可以通過設置規則實現自動清理過期的對象，優化存儲空間。本文介紹如何設置桶（Bucket）生命周期規則。您可以通過setBucketLifecycleConfiguration操作可以設置桶的生命周期規則，規則可以通過匹配對象key前綴、標簽的方法設置當前版本或者歷史版本對象的過期時間，對象過期后會被自動刪除。

桶的版本控制狀態必須處于Enabled或者Suspended，歷史版本對象過期時間配置才能生效。每次執行setBucketLifecycleConfiguration操作會覆蓋桶中已存在的生命周期規則。

代碼示例

public void setBucketLifecycleConfiguration() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("setBucketLifecycleConfiguration");
    BucketLifecycleConfiguration config = new BucketLifecycleConfiguration();
    List<BucketLifecycleConfiguration.Rule> rules = new ArrayList<BucketLifecycleConfiguration.Rule>();
    // mtime rule
    BucketLifecycleConfiguration.Transition transition = new BucketLifecycleConfiguration.Transition();
    transition.setDays(1);
    transition.setStorageClass(StorageClass.StandardInfrequentAccess);
?
    // atime rule
    BucketLifecycleConfiguration.AtimeTransition aTimeTransition = new BucketLifecycleConfiguration.AtimeTransition();
    aTimeTransition.setDays(3);
    aTimeTransition.setStorageClass(StorageClass.StandardInfrequentAccess);
    aTimeTransition.setTransToStandard(true);
    aTimeTransition.setNoTransMaxSize(1024*1024);
?
    // incomplete upload rule
    AbortIncompleteMultipartUpload abort = new AbortIncompleteMultipartUpload();
    abort.setDaysAfterInitiation(20);
?
    BucketLifecycleConfiguration.Rule rule = new BucketLifecycleConfiguration.Rule();
    rule.setId("haha");
    rule.setExpirationInDays(10);
    rule.setAbortIncompleteMultipartUpload(abort);
    rule.setStatus(BucketLifecycleConfiguration.ENABLED);
    // ncv過期時間
    rule.setNoncurrentVersionExpiration(new BucketLifecycleConfiguration.NoncurrentVersionExpiration().withDays(365));
    // 設置應用范圍，可以指定前綴或對象標簽
    LifecycleFilterPredicate predicate = new LifecyclePrefixPredicate("abc/");
    rule.setFilter(new LifecycleFilter(predicate));
    //LifecycleFilterPredicate predicate = new LifecycleTagPredicate(new Tag("your-key", "your-value"));
    //rule.setFilter(new LifecycleFilter(predicate));
    rule.addTransition(transition);
    rule.addAtimeTransition(aTimeTransition);
    rules.add(rule);
    config.setRules(rules);
    SetBucketLifecycleConfigurationRequest req = new SetBucketLifecycleConfigurationRequest(bucket, config);
    s3Client.setBucketLifecycleConfiguration(req);
    System.out.println("setBucketLifecycleConfiguration success");
}

請求參數

SetBucketLifecycleConfigurationRequest 的參數說明：

關于生命周期規則 Rule 的說明：

Transition：

AtimeTransition：

NoncurrentVersionExpiration：

注意：atime規則只在官網的sdk提供，AWS S3沒有atime規則。只有部分資源池支持atime規則。

獲取桶生命周期配置

功能說明

生命周期管理可以通過設置規則實現自動清理過期的對象，優化存儲空間。本文介紹如何查看桶（Bucket）的生命周期規則。

代碼示例

public void getBucketLifecycleConfiguration() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("getBucketLifecycleConfiguration");
    BucketLifecycleConfiguration config = s3Client.getBucketLifecycleConfiguration(bucket);
    List<BucketLifecycleConfiguration.Rule> rules = config.getRules();
    for (BucketLifecycleConfiguration.Rule rule: rules){
        System.out.println("getBucketLifecycleConfiguration: " + rule.getId());
        System.out.println("getBucketLifecycleConfiguration expire: " +
                rule.getExpirationInDays());
?
        if(rule.getAbortIncompleteMultipartUpload() != null){
            System.out.println("getBucketLifecycleConfiguration abort: " +
                    rule.getAbortIncompleteMultipartUpload().getDaysAfterInitiation());
        }
?
        if(rule.getNoncurrentVersionExpiration() != null) {
            System.out.println("getBucketLifecycleConfiguration ncv expire days: " +
                    rule.getNoncurrentVersionExpiration().getDays());
        }
?
        LifecycleFilterPredicate predicate = rule.getFilter().getPredicate();
        if (predicate instanceof LifecyclePrefixPredicate) {
            LifecyclePrefixPredicate prefixPredicate = (LifecyclePrefixPredicate)predicate;
            System.out.println("getBucketLifecycleConfiguration prefix filter: " +
                    prefixPredicate.getPrefix());
        }
?
        if (rule.getTransitions() != null) {
            for (BucketLifecycleConfiguration.Transition tran : rule.getTransitions()) {
                System.out.println("getBucketLifecycleConfiguration tran: " + tran.getStorageClassAsString() + "," +
                        tran.getDays());
            }
        }
        if (rule.getAtimeTransitions() != null) {
            for (BucketLifecycleConfiguration.AtimeTransition tran: rule.getAtimeTransitions()){
                System.out.println("getBucketLifecycleConfiguration atime tran: " + tran.getStorageClassAsString() + "," +
                        tran.getDays() + "," + tran.getTransToStandard() + "," + tran.getNoTransMaxSize());
            }
        }
    }
}

請求參數

GetBucketLifecycleConfigurationRequest 的參數說明：

返回參數

關于 BucketLifecycleConfiguration 的生命周期說明可參考 設置桶生命周期 一節。

刪除桶生命周期配置

功能說明

生命周期管理可以通過設置規則實現自動清理過期的對象，優化存儲空間。本文介紹如何刪除桶（Bucket）生命周期規則。

代碼示例

public void deleteBucketLifecycleConfiguration() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("deleteBucketLifecycleConfiguration");
    s3Client.deleteBucketLifecycleConfiguration(bucket);
    System.out.println("deleteBucketLifecycleConfiguration success");
}

請求參數

設置桶跨域訪問配置

功能說明

跨域資源共享 (CORS) 定義了在一個域中加載的客戶端 Web 應用程序與另一個域中的資源交互的方式。利用 CORS 支持，您可以構建豐富的客戶端 Web 應用程序，同時可以選擇性地允許跨源訪問您的資源。您可以通過setBucketCrossOriginConfiguration接口設置桶的跨域訪問配置。

示例代碼

public void setBucketCrossOriginConfiguration() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("setBucketCrossOriginConfiguration");
    List<CORSRule.AllowedMethods> rule2AM = new ArrayList<>();
    rule2AM.add(CORSRule.AllowedMethods.PUT);
    rule2AM.add(CORSRule.AllowedMethods.GET);
    rule2AM.add(CORSRule.AllowedMethods.HEAD);
    rule2AM.add(CORSRule.AllowedMethods.POST);
    rule2AM.add(CORSRule.AllowedMethods.DELETE);
    CORSRule rule = new CORSRule().withId("CORSRule").withAllowedMethods(rule2AM)
        .withAllowedOrigins(Arrays.asList("*"))
        .withExposedHeaders(Arrays.asList("x-amz-server-side-encryption", "ETag", "x-amz-request-id", "Date",
                                          "Content-Length", "Accept-Ranges", "Access-Control-Allow-Origin"))
        .withAllowedHeaders(Arrays.asList("*"))
        .withMaxAgeSeconds(600);
    List<CORSRule> rules = new ArrayList<>();
    rules.add(rule);
    BucketCrossOriginConfiguration config = new BucketCrossOriginConfiguration();
    config.setRules(rules);
?
    s3Client.setBucketCrossOriginConfiguration(bucket, config);
    System.out.println("setBucketCrossOriginConfiguration success");
}

請求參數

關于BucketCrossOriginConfiguration一些說明

獲取桶跨域訪問配置

功能說明

跨域資源共享 (CORS) 定義了在一個域中加載的客戶端 Web 應用程序與另一個域中的資源交互的方式。利用 CORS 支持，您可以構建豐富的客戶端 Web 應用程序，同時可以選擇性地允許跨源訪問您的資源。您可以通過getBucketCrossOriginConfiguration接口獲取桶跨域訪問配置。

代碼示例

public void getBucketCrossOriginConfiguration() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("getBucketCrossOriginConfiguration");
    BucketCrossOriginConfiguration config = s3Client.getBucketCrossOriginConfiguration(bucket);
    List<CORSRule> rules = config.getRules();
    for (CORSRule rule: rules){
        System.out.println("getBucketCrossOriginConfiguration: " + rule.getAllowedHeaders());
        System.out.println("getBucketCrossOriginConfiguration: " + rule.getAllowedOrigins());
        System.out.println("getBucketCrossOriginConfiguration: " + rule.getAllowedMethods());
        System.out.println("getBucketCrossOriginConfiguration: " + rule.getExposedHeaders());
        System.out.println("getBucketCrossOriginConfiguration: " + rule.getMaxAgeSeconds());
    }
}

請求參數

返回結果

關于BucketCrossOriginConfiguration一些說明

刪除桶跨域訪問配置

功能說明

跨域資源共享 (CORS) 定義了在一個域中加載的客戶端 Web 應用程序與另一個域中的資源交互的方式。利用 CORS 支持，您可以構建豐富的客戶端 Web 應用程序，同時可以選擇性地允許跨源訪問您的資源。您可以通過deleteBucketCrossOriginConfiguration接口刪除桶跨域訪問配置。

代碼示例

public void deleteBucketCrossOriginConfiguration() throws AmazonClientException{
    String bucket = "<your-bucket-name>";
    System.out.println("deleteBucketCrossOriginConfiguration");
    s3Client.deleteBucketCrossOriginConfiguration(bucket);
    System.out.println("deleteBucketCrossOriginConfiguration success");
}

請求參數

設置桶版本控制狀態

功能說明

通過媒體存儲提供的版本控制，您可以在一個桶中保留多個對象版本。例如，image.jpg(版本1)和image.jpg(版本2)。如果您希望防止自己意外覆蓋和刪除版本，或存檔對象，以便您可以檢索早期版本的對象，您可以開啟版本控制功能。

• 開啟版本控制

  對桶中的所有對象啟用版本控制，之后每個添加到桶中的對象都會被設置一個唯一的version id。

• 暫停版本控制

  對桶中的所有對象暫停版本控制，之后每個添加到桶中的對象的version ID會被設置為null。桶開啟版本控制功能之后，無法再關閉該功能，只能暫停。

您可以使用 setBucketVersioningConfiguration 接口開啟或暫停版本控制。

代碼示例

public void setBucketVersioningConfiguration() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("setBucketVersioningConfiguration");
    BucketVersioningConfiguration config = new BucketVersioningConfiguration();
    config.setStatus(BucketVersioningConfiguration.ENABLED);
    SetBucketVersioningConfigurationRequest request = new SetBucketVersioningConfigurationRequest(bucket, config);
    s3Client.setBucketVersioningConfiguration(request);
    System.out.println("setBucketVersioningConfiguration success");
}

請求參數

SetBucketVersioningConfigurationRequest 的參數說明：

關于BucketVersioningConfiguration一些說明

獲取桶版本控制狀態

功能說明

通過媒體存儲提供的版本控制，您可以在一個桶中保留多個對象版本。您可以使用 getBucketVersioningConfiguration接口獲取版本控制配置。

代碼示例

public void getBucketVersioningConfiguration() throws AmazonClientException {
    String bucket = "<your-bucket-name>";
    System.out.println("getBucketVersioningConfiguration");
    BucketVersioningConfiguration config = s3Client.getBucketVersioningConfiguration(bucket);
    System.out.println("getBucketVersioningConfiguration success, " + config.getStatus());
}

參數說明

返回結果

關于BucketVersioningConfiguration一些說明。