Todos os produtos
Search

Este produto

    Object Storage Service:Bucket ACL

    Central de documentação

    Object Storage Service:Bucket ACL

    Última atualização: Jul 03, 2026

    A ACL (lista de controle de acesso) de bucket controla o acesso no nível do bucket no OSS ao defini-lo como público ou privado. Objetos enviados sem uma ACL específica herdam a ACL do bucket.

    Como funciona

    As ACLs de bucket usam valores predefinidos para controlar o acesso ao bucket.

    Valor

    Descrição

    private (padrão)

    Privado. Somente o proprietário do bucket ou usuários autorizados podem ler e gravar objetos no bucket.

    public-read

    Leitura pública. Apenas o proprietário do bucket ou usuários autorizados podem gravar objetos, mas qualquer pessoa, incluindo usuários anônimos, pode lê-los.

    public-read-write

    Leitura e gravação públicas. Qualquer pessoa, inclusive usuários anônimos, pode ler e gravar objetos no bucket.
    Importante

    • public-read-write: Permite que qualquer pessoa na internet leia e grave objetos no bucket. Isso pode causar exposição de dados, cobranças inesperadas ou uploads maliciosos. Evite essa configuração, a menos que seja estritamente necessária.

    • public-read: Libera a leitura de objetos no bucket para qualquer pessoa na internet, o que pode resultar em exposição de dados e custos imprevistos. Use com cautela.

    Definir uma ACL de bucket

    Ao criar um bucket, o recurso Block Public Access vem ativado por padrão e a ACL é definida como privada. Para usar public-read ou public-read-write, desative primeiro o Block Public Access.

    Console

    1. Acesse a lista de Buckets e clique no bucket desejado.

    2. No painel de navegação à esquerda, escolha Permission Control > ACL (Access Control List).

    3. Clique em Configure e modifique a ACL do bucket conforme necessário.

    4. Clique em Save.

    ossutil CLI

    Execute o comando put-bucket-acl no ossutil 2.0 para definir a ACL do bucket.

    ossutil api put-bucket-acl --bucket example-bucket --acl private

    SDK

    Os exemplos a seguir mostram como definir uma ACL de bucket com SDKs comuns. Mais amostras estão disponíveis na referência do SDK.

    // This sample code shows how to set the access control list (ACL) for a bucket.
// Before you run the sample code, configure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.StaticCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class SetBucketAcl {

    public static void main(String[] args) {
        String bucketName = "example-bucket";

        String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
        CredentialsProvider provider = new StaticCredentialsProvider(accessKeyId, accessKeySecret);

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region("<region-id>")
                .build()) {

            // Set the bucket ACL to private.
            // Valid values: "private", "public-read", and "public-read-write".
            PutBucketAclRequest putRequest = PutBucketAclRequest.newBuilder()
                    .bucket(bucketName)
                    .acl("private")
                    .build();
            PutBucketAclResult putResult = client.putBucketAcl(putRequest);
            System.out.println("Bucket ACL set successfully. RequestId: " + putResult.requestId());

            // Get the bucket ACL.
            GetBucketAclRequest getRequest = GetBucketAclRequest.newBuilder()
                    .bucket(bucketName)
                    .build();
            GetBucketAclResult getResult = client.getBucketAcl(getRequest);
            System.out.println("Current bucket ACL: " + getResult.accessControlPolicy().accessControlList().grant());

        } catch (Exception e) {
            System.err.println("Operation failed: " + e.getMessage());
        }
    }
}

    #!/usr/bin/env python3
# -*- coding: utf-8 -*-
# This sample code shows how to set the access control list (ACL) for a bucket.
# Before you run the sample code, configure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.

import alibabacloud_oss_v2 as oss

def main() -> None:
    bucket_name = "example-bucket"

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = "<region-id>"

    client = oss.Client(cfg)

    # Set the bucket ACL to private.
    # Valid values: "private", "public-read", and "public-read-write".
    put_result = client.put_bucket_acl(oss.PutBucketAclRequest(
        bucket=bucket_name,
        acl="private"
    ))
    print(f"Bucket ACL set successfully. RequestId: {put_result.request_id}")

    # Get the bucket ACL.
    get_result = client.get_bucket_acl(oss.GetBucketAclRequest(
        bucket=bucket_name
    ))
    print(f"Current bucket ACL: {get_result.acl}")

if __name__ == "__main__":
    main()

    // This sample code shows how to set the access control list (ACL) for a bucket.
// Before you run the sample code, configure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	bucketName := "example-bucket"

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("<region-id>")

	client := oss.NewClient(cfg)

	// Set the bucket ACL to private.
	// Valid values: oss.BucketACLPrivate, oss.BucketACLPublicRead, and oss.BucketACLPublicReadWrite.
	putResult, err := client.PutBucketAcl(context.TODO(), &oss.PutBucketAclRequest{
		Bucket: oss.Ptr(bucketName),
		Acl:    oss.BucketACLPrivate,
	})
	if err != nil {
		log.Fatalf("Failed to set bucket ACL: %v", err)
	}
	log.Printf("Bucket ACL set successfully. RequestId: %s", putResult.Headers.Get("X-Oss-Request-Id"))

	// Get the bucket ACL.
	getResult, err := client.GetBucketAcl(context.TODO(), &oss.GetBucketAclRequest{
		Bucket: oss.Ptr(bucketName),
	})
	if err != nil {
		log.Fatalf("Failed to get bucket ACL: %v", err)
	}
	log.Printf("Current bucket ACL: %s", *getResult.ACL)
}

    <?php
// This sample code shows how to set the access control list (ACL) for a bucket.
// Before you run the sample code, configure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.

require_once __DIR__ . '/vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

$bucketName = 'example-bucket';

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('<region-id>');

$client = new Oss\Client($cfg);

try {
    // Set the bucket ACL to private.
    // Valid values: BucketACLType::PRIVATE, BucketACLType::PUBLIC_READ, and BucketACLType::PUBLIC_READ_WRITE.
    $putResult = $client->putBucketAcl(new Oss\Models\PutBucketAclRequest(
        bucket: $bucketName,
        acl: Oss\Models\BucketACLType::PRIVATE
    ));
    printf("Bucket ACL set successfully. RequestId: %s\n", $putResult->requestId);

    // Get the bucket ACL.
    $getResult = $client->getBucketAcl(new Oss\Models\GetBucketAclRequest(
        bucket: $bucketName
    ));
    printf("Current bucket ACL: %s\n", $getResult->accessControlList->grant);
} catch (Exception $e) {
    printf("Operation failed: %s\n", $e->getMessage());
}

    // This sample code shows how to set the access control list (ACL) for a bucket.
// Before you run the sample code, configure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.

using OSS = AlibabaCloud.OSS.V2;

var bucketName = "example-bucket";
var region = "<region-id>";

var cfg = OSS.Configuration.LoadDefault();
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
cfg.Region = region;

using var client = new OSS.Client(cfg);

try
{
    // Set the bucket ACL to private.
    // Valid values: "private", "public-read", and "public-read-write".
    var putResult = await client.PutBucketAclAsync(new OSS.Models.PutBucketAclRequest()
    {
        Bucket = bucketName,
        Acl = "private"
    });
    Console.WriteLine($"Bucket ACL set successfully. RequestId: {putResult.RequestId}");

    // Get the bucket ACL.
    var getResult = await client.GetBucketAclAsync(new OSS.Models.GetBucketAclRequest()
    {
        Bucket = bucketName
    });
    Console.WriteLine($"Current bucket ACL: {getResult.AccessControlPolicy?.AccessControlList?.Grant}");
}
catch (Exception ex)
{
    Console.WriteLine($"Operation failed: {ex.Message}");
}

    // This sample code shows how to set the access control list (ACL) for a bucket.
// Before you run the sample code, configure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.

const OSS = require('ali-oss');

async function main() {
    const bucketName = 'example-bucket';

    const client = new OSS({
        region: 'oss-<region-id>',
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        authorizationV4: true,
    });

    try {
        // Set the bucket ACL to private.
        // Valid values: 'private', 'public-read', and 'public-read-write'.
        await client.putBucketACL(bucketName, 'private');
        console.log('Bucket ACL set successfully.');

        // Get the bucket ACL.
        const result = await client.getBucketACL(bucketName);
        console.log(`Current bucket ACL: ${result.acl}`);
    } catch (err) {
        console.error('Operation failed:', err.message);
    }
}

main();

    Rastrear alterações na ACL do bucket

    Use o ActionTrail para monitorar mudanças na ACL do bucket, identificando quem fez cada alteração e quando. Esse rastreamento auxilia na investigação de acessos incomuns, exposição de dados, alertas de segurança ou auditorias de rotina.

    1. Acesse o console do ActionTrail. No painel de navegação à esquerda, escolha .

    2. Selecione a região do bucket. Defina Service Name como Object Storage Service (OSS) e Event Name como PutBucketAcl. O ActionTrail consulta os registros correspondentes automaticamente.

    3. Desative a opção Summary List. Na coluna Actions de um registro de alteração, clique em View Details e, em seguida, clique em Configure Timeline para visualizar os valores antes e depois da mudança.

    Perguntas frequentes

    Origem CDN: Uma ACL pública é obrigatória?

    Não. Mesmo com uma ACL privada, é possível configurar o CDN para acessar o bucket. Consulte Set up access to a private origin bucket.

    Documentos relacionados