设置Object ACL控制单个文件访问权限 - 对象存储 OSS

Object ACL（访问控制列表）是OSS提供的Object级别访问权限控制功能。当需要为Bucket中的某个Object设置独立于Bucket的访问权限时，可通过Object ACL精确控制单个文件的读写权限。

工作原理

Object ACL通过预定义的权限值控制单个Object的访问范围。OSS支持以下四种权限：

权限值	说明
default（默认值）	继承Bucket ACL。Object的读写权限与所属Bucket保持一致。
private	私有。只有Object拥有者或被授权用户可以对该Object进行读写操作，其他人无法访问。
public-read	公共读。只有Object拥有者或被授权用户可以写入，任何人（包括匿名访问者）都可以读取。
public-read-write	公共读写。任何人（包括匿名访问者）都可以对该Object进行读写操作。

Object ACL优先级高于Bucket ACL。当Object设置了非default的ACL时，系统将以Object ACL为准执行权限控制。例如，当Object ACL设置为public-read时，无论Bucket ACL是何种权限，该Object都可以被匿名访问。

重要

public-read-write：互联网上任何用户都可以对该Object进行访问和写入。这可能造成数据外泄、费用激增，甚至被恶意写入违法信息。除特殊场景外，不建议配置此权限。
public-read：互联网上任何用户都可以访问该Object，可能造成数据外泄和费用激增，请谨慎操作。

设置Object ACL

创建Bucket时默认开启阻止公共访问，Object ACL只能设置为private或default。如需设置为public-read或public-read-write，请先关闭阻止公共访问。

控制台

前往Bucket列表，单击目标Bucket名称。
在目标文件的操作列，单击详情，然后单击设置读写权限。
根据需求设置读写权限，然后单击确定。

命令行工具ossutil

使用命令行工具ossutil 2.0的put-object-acl命令设置Object ACL。

ossutil api put-object-acl --bucket examplebucket --key exampleobject --acl private

SDK

以下仅列举常见SDK设置Object ACL的代码示例，其他SDK的代码示例请参见SDK参考。

Java

// 本示例展示如何设置对象的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

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 SetObjectAcl {

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

        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()) {

            // 设置对象 ACL 为私有
            // 可选值: "private", "public-read", "public-read-write", "default"
            PutObjectAclRequest putRequest = PutObjectAclRequest.newBuilder()
                    .bucket(bucketName)
                    .key(objectName)
                    .objectAcl("private")
                    .build();
            PutObjectAclResult putResult = client.putObjectAcl(putRequest);
            System.out.println("设置 Object ACL 成功，RequestId: " + putResult.requestId());

            // 获取对象 ACL
            GetObjectAclRequest getRequest = GetObjectAclRequest.newBuilder()
                    .bucket(bucketName)
                    .key(objectName)
                    .build();
            GetObjectAclResult getResult = client.getObjectAcl(getRequest);
            System.out.println("当前 Object ACL: " + getResult.accessControlPolicy().accessControlList().grant());

        } catch (Exception e) {
            System.err.println("操作失败: " + e.getMessage());
        }
    }
}

Python

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# 本示例展示如何设置对象的访问权限（ACL）
# 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

import alibabacloud_oss_v2 as oss


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

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

    client = oss.Client(cfg)

    # 设置对象 ACL 为私有
    # 可选值: "private", "public-read", "public-read-write", "default"
    put_result = client.put_object_acl(oss.PutObjectAclRequest(
        bucket=bucket_name,
        key=object_name,
        acl="private"
    ))
    print(f"设置 Object ACL 成功，RequestId: {put_result.request_id}")

    # 获取对象 ACL
    get_result = client.get_object_acl(oss.GetObjectAclRequest(
        bucket=bucket_name,
        key=object_name
    ))
    print(f"当前 Object ACL: {get_result.acl}")


if __name__ == "__main__":
    main()

// 本示例展示如何设置对象的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

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"
	objectName := "example.txt"

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

	client := oss.NewClient(cfg)

	// 设置对象 ACL 为私有
	// 可选值: oss.ObjectACLPrivate, oss.ObjectACLPublicRead, oss.ObjectACLPublicReadWrite, oss.ObjectACLDefault
	putResult, err := client.PutObjectAcl(context.TODO(), &oss.PutObjectAclRequest{
		Bucket: oss.Ptr(bucketName),
		Key:    oss.Ptr(objectName),
		Acl:    oss.ObjectACLPrivate,
	})
	if err != nil {
		log.Fatalf("设置 Object ACL 失败: %v", err)
	}
	log.Printf("设置 Object ACL 成功，RequestId: %s", putResult.Headers.Get("X-Oss-Request-Id"))

	// 获取对象 ACL
	getResult, err := client.GetObjectAcl(context.TODO(), &oss.GetObjectAclRequest{
		Bucket: oss.Ptr(bucketName),
		Key:    oss.Ptr(objectName),
	})
	if err != nil {
		log.Fatalf("获取 Object ACL 失败: %v", err)
	}
	log.Printf("当前 Object ACL: %s", *getResult.ACL)
}

PHP

<?php
// 本示例展示如何设置对象的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

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

use AlibabaCloud\Oss\V2 as Oss;

$bucketName = 'example-bucket';
$objectName = 'example.txt';

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

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

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

try {
    // 设置对象 ACL 为私有
    // 可选值: ObjectACLType::PRIVATE, ObjectACLType::PUBLIC_READ, ObjectACLType::PUBLIC_READ_WRITE, ObjectACLType::DEFAULT
    $putResult = $client->putObjectAcl(new Oss\Models\PutObjectAclRequest(
        bucket: $bucketName,
        key: $objectName,
        acl: Oss\Models\ObjectACLType::PRIVATE
    ));
    printf("设置 Object ACL 成功，RequestId: %s\n", $putResult->requestId);

    // 获取对象 ACL
    $getResult = $client->getObjectAcl(new Oss\Models\GetObjectAclRequest(
        bucket: $bucketName,
        key: $objectName
    ));
    printf("当前 Object ACL: %s\n", $getResult->accessControlList->grant);
} catch (Exception $e) {
    printf("操作失败: %s\n", $e->getMessage());
}

// 本示例展示如何设置对象的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

using OSS = AlibabaCloud.OSS.V2;

var bucketName = "example-bucket";
var objectName = "example.txt";
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
{
    // 设置对象 ACL 为私有
    // 可选值: "private", "public-read", "public-read-write", "default"
    var putResult = await client.PutObjectAclAsync(new OSS.Models.PutObjectAclRequest()
    {
        Bucket = bucketName,
        Key = objectName,
        Acl = "private"
    });
    Console.WriteLine($"设置 Object ACL 成功，RequestId: {putResult.RequestId}");

    // 获取对象 ACL
    var getResult = await client.GetObjectAclAsync(new OSS.Models.GetObjectAclRequest()
    {
        Bucket = bucketName,
        Key = objectName
    });
    Console.WriteLine($"当前 Object ACL: {getResult.AccessControlPolicy?.AccessControlList?.Grant}");
}
catch (Exception ex)
{
    Console.WriteLine($"操作失败: {ex.Message}");
}

Node.js

// 本示例展示如何设置对象的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

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

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

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

    try {
        // 设置对象 ACL 为私有
        // 可选值: 'private', 'public-read', 'public-read-write', 'default'
        await client.putACL(objectName, 'private');
        console.log('设置 Object ACL 成功');

        // 获取对象 ACL
        const result = await client.getACL(objectName);
        console.log(`当前 Object ACL: ${result.acl}`);
    } catch (err) {
        console.error('操作失败:', err.message);
    }
}

main();

常见问题

如何将私有Object临时分享给其他用户？

通过生成预签名URL并分享给其他用户，可在指定有效期内访问私有Object，无需修改Object ACL。

对象存储 OSS：Object ACL

工作原理

设置Object ACL

控制台

命令行工具ossutil

SDK

常见问题

如何将私有Object临时分享给其他用户？

相关文档