設定Object ACL控制單個檔案存取權限 - Object Storage Service

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。

Object Storage Service：Object ACL

工作原理

設定Object ACL

控制台

命令列工具ossutil

SDK

常見問題

如何將私人Object臨時分享給其他使用者？

相關文檔