本文中含有需要您注意的重要提示信息,忽略該信息可能對您的業務造成影響,請務必仔細閱讀。
您可以使用對象存儲OSS的清單功能獲取存儲空間(Bucket)中指定文件(Object)的數量、大小、存儲類型、加密狀態等信息。相對于GetBucket(ListObjects)接口,在海量Object的列舉場景中,建議您優先使用清單功能。
為避免影響OSS-HDFS服務的正常使用或者引發數據污染的風險,在開通了OSS-HDFS服務的Bucket設置清單報告規則時,禁止將清單報告目錄填寫為.dlsdata/
。
計費說明
使用Bucket清單功能會產生一定的費用,但公測期間僅收取調用PutBucketInventory、GetBucketInventory、ListBucketInventory、DeleteBucketInventory API的請求費用、清單結果文件的存儲費用,以及正常讀取清單結果文件的流量和請求費用。
在您刪除清單規則前,OSS會按照清單規則一直生成清單文件,會產生一定的存儲費用。為避免產生不必要的費用,請及時清理不再需要的清單文件。
使用限制
對于單個Bucket,通過SDK或者命令行工具ossutil最多可配置1000條清單規則,通過OSS管理控制臺最多可配置10條清單規則。
配置清單的源Bucket與存放清單文件的目標Bucket可以相同也可以不同,但是必須屬于同一賬號下的相同地域。
金融云地域不支持配置存儲空間清單。
無地域屬性Bucket不支持配置存儲空間清單。
權限說明
使用Bucket清單功能時,涉及創建清單規則以及向目標Bucket寫入清單結果文件的操作。創建清單規則的操作由用戶完成,向目標Bucket寫入清單結果文件的操作是OSS服務通過扮演用戶創建的RAM角色來完成。
如果您通過阿里云賬號使用Bucket清單功能,則需要先完成創建RAM角色以及為RAM角色授權。
如果您通過RAM用戶使用Bucket清單功能,則需要先完成RAM用戶授權、創建RAM角色以及為RAM角色授權。
您可以通過以下步驟為RAM用戶授權,創建RAM角色并為RAM角色授權。授權完成后,您可以創建清單規則。具體操作,請參見創建清單規則。
考慮到授予RAM用戶創建CreateRole
、GetRoles
等角色相關的權限風險較大,您可以通過RAM用戶關聯的阿里云賬號創建RAM角色并為相應的RAM角色完成授權。授權完成后,RAM用戶可以直接復用阿里云賬號創建的RAM角色。
RAM用戶授權
按如下步驟授予RAM用戶擁有創建Role以及配置清單規則的權限。
通過腳本編輯模式創建以下自定義策略。具體操作,請參見創建自定義權限策略。
說明以下授權策略中,僅在通過控制臺的方式訪問時,需要授予RAM用戶
oss:ListBuckets
的Action。通過SDK或者ossutil等方式訪問時,不需要授予RAM用戶oss:ListBuckets
的Action。{ "Statement": [ { "Effect": "Allow", "Action": [ "oss:PutBucketInventory", "oss:GetBucketInventory", "oss:DeleteBucketInventory", "oss:ListBuckets", "ram:CreateRole", "ram:AttachPolicyToRole", "ram:GetRole", "ram:ListPoliciesForRole" ], "Resource": "*" } ], "Version": "1" }
重要如果當前賬號下已創建包含
AliyunOSSFullAccess
系統權限的RAM用戶,由于AliyunOSSFullAccess
包含了所有操作OSS資源的權限,則只需要為RAM用戶授予以下與Role相關的權限。{ "Statement": [ { "Effect": "Allow", "Action": [ "ram:CreateRole", "ram:AttachPolicyToRole", "ram:GetRole", "ram:ListPoliciesForRole" ], "Resource": "*" } ], "Version": "1" }
為RAM用戶授予已創建的自定義策略。具體操作,請參見為RAM用戶授權。
完成RAM用戶授權后,RAM用戶具備創建RAM角色以及為RAM角色授權的權限,請參見后續步驟完成RAM角色授權。
創建RAM角色并為RAM角色授權
重要如果您希望使用KMS密鑰加密清單文件,您還需要為創建的RAM角色授予
AliyunKMSFullAccess
(管理密鑰管理服務KMS的權限)。自動創建的RAM角色
AliyunOSSRole
通過控制臺配置清單規則時,RAM控制臺會自動創建RAM角色
AliyunOSSRole
,該角色默認擁有向目標Bucket寫入清單結果文件的權限。重要使用自動創建的RAM角色
AliyunOSSRole
可以避免額外的授權操作,但是該角色默認擁有管理OSS的權限,權限范圍較大。基于權限范圍考慮,您還可以選擇創建自定義RAM角色,并授予RAM角色最小權限。自定義RAM角色
如果您需要使用自定義RAM角色向目標Bucket寫入清單結果文件,請執行以下步驟創建RAM角色并為該角色授予權限策略:
創建普通服務角色。
創建普通服務角色過程中,受信服務選擇對象存儲。其他參數的配置信息,請參見創建可信實體為阿里云服務的RAM角色。
通過可視化編輯模式創建自定義權限策略。
創建自定義權限策略過程中,您需要按照以下說明配置權限策略。其他參數的配置信息,請參見創建自定義權限策略。
參數
說明
效果
選中允許。
服務
選中對象存儲。
操作
選中指定操作,然后選中寫操作下的oss:PutObject。
資源
選中全部資源。
該權限策略對應的JSON格式如下:
{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": "oss:PutObject", "Resource": "*" } ] }
為角色授予自定義權限策略。
具體操作,請參見為RAM角色授權。
操作步驟
使用OSS控制臺
登錄OSS管理控制臺。
單擊Bucket 列表,然后單擊目標Bucket名稱。
在左側導航欄,選擇 。
在Bucket 清單頁面,單擊創建清單。
在設置清單報告規則面板,按以下說明配置各項參數。
參數
說明
狀態
設置清單任務的狀態。可以選擇啟動和禁用。
規則名稱
設置清單任務的名稱。只能包含小寫字母、數字、短劃線(-),且不能以短劃線(-)開頭或結尾。
存儲清單 Bucket
選擇存儲清單文件的Bucket。
配置清單的源Bucket與存放清單文件的目標Bucket可以相同也可以不同,但是必須屬于同一賬號下的相同地域。
清單報告存儲路徑
設置清單報告存儲路徑。
如果要將清單報告保存在Bucket根目錄下,請將此項置空。
如果要將清單報告保存在Bucket非根目錄下,請填寫不包含Bucket名稱在內的完整路徑。
例如,當您需要將清單報告保存在存儲空間examplebucket的exampledir1路徑下,則填寫為exampledir1。當您需要將清單報告保存在存儲空間examplebucket的exampledir1/exampledir2路徑下,則填寫為exampledir1/exampledir2。
說明如果Bucket中不存在指定的清單報告存儲路徑,OSS會根據填寫的清單報告存儲路徑自動創建對應的路徑。
清單報告導出周期
設置清單報告的生成周期。可選擇每周或每天。
當文件數量小于100億時,您可以根據自己的業務需要,設置按周或按天導出清單。
當文件數量大于100億時,建議設置以周為單位導出清單。
清單報告加密選項
是否加密清單文件。
清單內容
選擇您希望導出的文件信息,包括Object大小、存儲類型、最后更新時間、ETag、分片上傳狀態、加密狀態、Object ACL、標簽個數、文件類型、Crc64。
按前綴匹配
設置清單規則掃描Object的前綴。
如果要掃描整個Bucket內的所有Object,請將此項置空。
如果要掃描Bucket某個路徑下的所有Object,請填寫不包含Bucket名稱在內的完整路徑。
例如,當您需要掃描存儲空間examplebucket的exampledir1路徑下的所有Object,則填寫為exampledir1/。如果您需要掃描examplebucket的exampledir1/exampledir2路徑下的所有Object,則填寫為exampledir1/exampledir2/。
說明如果設置的前綴沒有匹配Bucket內的任意Object,則不生成清單文件。
配置高級篩選功能
如果您需要根據文件大小、存儲類型等條件過濾導出的文件,需要打開配置高級篩選功能開關。支持的過濾選項說明如下:
重要僅華北1(青島)、華北5(呼和浩特)、德國(法蘭克福)以及澳大利亞(悉尼)關停中地域支持配置以下過濾選項。
時間范圍:設置待導出文件最后一次修改的起始日期和結束日期,時間精確到秒。
文件大小范圍:設置待導出文件的文件大小最小值和最大值。
重要設置文件大小范圍時,確保文件大小的最小值以及最大值均大于0 B,且最大值不超過48.8 TB。
存儲類型:設置待導出哪些存儲類型的文件。您可以選擇導出標準存儲、低頻訪問、歸檔存儲、冷歸檔存儲以及深度冷歸檔存儲的文件。
對象版本
選擇清單掃描的文件版本。
如果Bucket已開啟版本控制,可選擇導出目標文件的當前版本或所有版本。更多信息,請參見版本控制概述。
如果Bucket未開啟版本控制,默認導出所有文件。
選中我知曉并同意授予阿里云 OSS 服務訪問 Bucket 資源的權限,然后單擊確定。
涉及Object較多時,生成清單文件需要一定的時間。您可以通過兩種方式判斷是否已生成清單文件,詳情請參見如何判斷是否已生成清單文件?。
使用阿里云SDK
以下僅列舉常見SDK配置Bucket清單的代碼示例。關于其他SDK的配置Bucket清單代碼示例,請參見SDK簡介。
import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;
import java.util.ArrayList;
import java.util.List;
public class Demo {
public static void main(String[] args) throws Exception {
// Endpoint以華東1(杭州)為例,其它Region請按實際情況填寫。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 填寫Bucket名稱,例如examplebucket。
String bucketName = "examplebucket";
// 填寫存放清單結果的Bucket名稱。
String destBucketName ="yourDestinationBucketName";
// 填寫Bucket所有者授予的賬戶ID。
String accountId ="yourDestinationBucketAccountId";
// 填寫具有讀取源Bucket所有文件和向目標Bucket寫入文件權限的角色名稱。
String roleArn ="yourDestinationBucketRoleArn";
// 創建OSSClient實例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
try {
// 創建清單配置。
InventoryConfiguration inventoryConfiguration = new InventoryConfiguration();
// 設置清單規則名稱。
String inventoryId = "testid";
inventoryConfiguration.setInventoryId(inventoryId);
// 設置清單中包含的Object屬性。
List<String> fields = new ArrayList<String>();
fields.add(InventoryOptionalFields.Size);
fields.add(InventoryOptionalFields.LastModifiedDate);
fields.add(InventoryOptionalFields.IsMultipartUploaded);
fields.add(InventoryOptionalFields.StorageClass);
fields.add(InventoryOptionalFields.ETag);
fields.add(InventoryOptionalFields.EncryptionStatus);
inventoryConfiguration.setOptionalFields(fields);
// 設置清單的生成計劃,以下示例為每周一次。其中,Weekly表示每周一次,Daily表示每天一次。
inventoryConfiguration.setSchedule(new InventorySchedule().withFrequency(InventoryFrequency.Weekly));
// 設置清單中包含的Object的版本為當前版本。如果設置為InventoryIncludedObjectVersions.All則表示Object的所有版本在版本控制狀態下生效。
inventoryConfiguration.setIncludedObjectVersions(InventoryIncludedObjectVersions.Current);
// 清單配置是否啟用的標識,取值為true或者false,設置為true表示啟用清單配置,設置為false表示關閉清單配置。
inventoryConfiguration.setEnabled(true);
// 設置清單篩選規則,指定篩選Object的前綴。
InventoryFilter inventoryFilter = new InventoryFilter().withPrefix("obj-prefix");
inventoryConfiguration.setInventoryFilter(inventoryFilter);
// 創建存放清單結果的目標Bucket配置。
InventoryOSSBucketDestination ossInvDest = new InventoryOSSBucketDestination();
// 設置存放清單結果的存儲路徑前綴。
ossInvDest.setPrefix("destination-prefix");
// 設置清單格式。
ossInvDest.setFormat(InventoryFormat.CSV);
// 設置目標Bucket的用戶accountId。
ossInvDest.setAccountId(accountId);
// 設置目標Bucket的roleArn。
ossInvDest.setRoleArn(roleArn);
// 設置目標Bucket的名稱。
ossInvDest.setBucket(destBucketName);
// 如果需要使用KMS加密清單,請參考如下設置。
// InventoryEncryption inventoryEncryption = new InventoryEncryption();
// InventoryServerSideEncryptionKMS serverSideKmsEncryption = new InventoryServerSideEncryptionKMS().withKeyId("test-kms-id");
// inventoryEncryption.setServerSideKmsEncryption(serverSideKmsEncryption);
// ossInvDest.setEncryption(inventoryEncryption);
// 如果需要使用OSS服務端加密清單,請參考如下設置。
// InventoryEncryption inventoryEncryption = new InventoryEncryption();
// inventoryEncryption.setServerSideOssEncryption(new InventoryServerSideEncryptionOSS());
// ossInvDest.setEncryption(inventoryEncryption);
// 設置清單的目的地。
InventoryDestination destination = new InventoryDestination();
destination.setOssBucketDestination(ossInvDest);
inventoryConfiguration.setDestination(destination);
// 上傳清單配置。
ossClient.setBucketInventoryConfiguration(bucketName, inventoryConfiguration);
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException ce) {
System.out.println("Caught an ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}
const OSS = require('ali-oss');
const client = new OSS({
// yourregion填寫Bucket所在地域。以華東1(杭州)為例,Region填寫為oss-cn-hangzhou。
region: 'yourregion',
// 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 填寫存儲空間名稱。
bucket: 'yourbucketname'
});
const inventory = {
// 設置清單配置ID。
id: 'default',
// 清單配置是否啟用的標識,取值為true或false。
isEnabled: false,
//(可選)設置清單篩選規則,指定篩選object的前綴。
prefix: 'ttt',
OSSBucketDestination: {
// 設置清單格式。
format: 'CSV',
// 目標Bucket擁有者的賬號ID。
accountId: '<Your AccountId>',
// 目標Bucket的角色名稱。
rolename: 'AliyunOSSRole',
// 目標Bucket的名稱。
bucket: '<Your BucketName>',
//(可選)清單結果的存儲路徑前綴。
prefix: '<Your Prefix>',
// 如果需要使用SSE-OSS加密清單,請參考以下代碼。
//encryption: {'SSE-OSS': ''},
// 如果需要使用SSE-KMS加密清單,請參考以下代碼。
/*
encryption: {
'SSE-KMS': {
keyId: 'test-kms-id',
};,
*/
},
// 設置清單的生成計劃,WEEKLY對應每周一次,DAILY對應每天一次。
frequency: 'Daily',
// 設置清單結果中包含了Object的所有版本, 如果設置為Current,則表示僅包含Object的當前版本。
includedObjectVersions: 'All',
optionalFields: {
//(可選)設置清單中包含的Object屬性。
field: ["Size", "LastModifiedDate", "ETag", "StorageClass", "IsMultipartUploaded", "EncryptionStatus"]
},
}
async function putInventory(){
// 需要添加清單配置的Bucket名稱。
const bucket = '<Your BucketName>';
try {
await client.putBucketInventory(bucket, inventory);
console.log('清單配置添加成功')
} catch(err) {
console.log('清單配置添加失敗: ', err);
}
}
putInventory()
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import (InventoryConfiguration,
InventoryFilter,
InventorySchedule,
InventoryDestination,
InventoryBucketDestination,
INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
INVENTORY_FREQUENCY_DAILY,
INVENTORY_FORMAT_CSV,
FIELD_SIZE,
FIELD_LAST_MODIFIED_DATE,
FIELD_STORAG_CLASS,
FIELD_ETAG,
FIELD_IS_MULTIPART_UPLOADED,
FIELD_ENCRYPTION_STATUS)
# 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填寫Bucket所在地域對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
# 填寫Bucket名稱,例如examplebucket。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填寫Bucket所有者授予的賬戶ID。例如:1283641033516515
account_id = 'yourtBucketDestinationAccountId'
# 填寫具有讀取源Bucket所有文件和向目標Bucket寫入文件權限的角色名稱。例如:acs:ram::1283641033516515:role/AliyunOSSRole
role_arn = 'yourBucketDestinationRoleArn'
# 填寫存放清單結果的Bucket名稱。
dest_bucket_name = 'yourDestinationBucketName'
# 設置清單規則名稱。
inventory_id = "inventory1"
# 設置清單結果中包含的Object屬性。
optional_fields = [FIELD_SIZE, FIELD_LAST_MODIFIED_DATE, FIELD_STORAG_CLASS,
FIELD_ETAG, FIELD_IS_MULTIPART_UPLOADED, FIELD_ENCRYPTION_STATUS]
# 創建存放清單文件的目標Bucket配置。
bucket_destination = InventoryBucketDestination(
# 目標Bucket的用戶accountId。
account_id=account_id,
# 目標Bucket的roleArn。
role_arn=role_arn,
# 目標Bucket的名稱。
bucket=dest_bucket_name,
# 指定清單格式。
inventory_format=INVENTORY_FORMAT_CSV,
# 清單結果的存儲路徑前綴。
prefix='destination-prefix',
# 如果需要使用KMS加密清單,請參考如下設置。
# sse_kms_encryption=InventoryServerSideEncryptionKMS("test-kms-id"),
# 如果需要使用OSS服務端加密清單,請參考如下設置。
# sse_oss_encryption=InventoryServerSideEncryptionOSS()
)
# 創建清單配置。
inventory_configuration = InventoryConfiguration(
# 設置清單的配置id。
inventory_id=inventory_id,
# 清單配置是否啟用的標識, true或false。
is_enabled=True,
# 設置清單的生成計劃,以下示例為每天一次。其中,WEEKLY對應每周一次,DAILY對應每天一次。
inventory_schedule=InventorySchedule(frequency=INVENTORY_FREQUENCY_DAILY),
# 設置清單中包含的object的版本為當前版本。如果設置為INVENTORY_INCLUDED_OBJECT_VERSIONS_ALL則表示object的所有版本,在版本控制狀態下生效。
included_object_versions=INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
# 設置清單清篩選object的前綴。
# inventory_filter=InventoryFilter(prefix="obj-prefix"),
# 設置清單清篩選條件。假如篩選文件最后修改時間的起始時間戳為1637883649,
inventory_filter=InventoryFilter(
# 篩選規則的匹配前綴。
"obj-prefix",
# 篩選文件最后修改時間的起始時間戳,單位為秒。
1637883649,
# 篩選文件最后修改時間的終止時間戳,單位為秒。
1638347592,
# 篩選文件的最小大小,單位為B。
1024,
# 篩選文件的最大大小,單位為B。
1048576,
# 篩選文件的存儲類型,支持指定多種存儲類型。
'Standard,IA'),
# 設置清單中包含的object屬性。
optional_fields=optional_fields,
inventory_destination=InventoryDestination(bucket_destination=bucket_destination))
# 上傳清單配置。
result = bucket.put_bucket_inventory_configuration(inventory_configuration)
print(result.status)
using Aliyun.OSS;
using Aliyun.OSS.Common;
// yourEndpoint填寫Bucket所在地域對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填寫Bucket名稱。
var bucketName = "examplebucket";
// 填寫Bucket所有者授予的賬戶ID。
var accountId ="yourDestinationBucketAccountId";
// 填寫具有讀取源Bucket所有文件和向目標Bucket寫入文件權限的角色名稱。
var roleArn ="yourDestinationBucketRoleArn";
// 填寫存放清單結果的Bucket名稱。
var destBucketName ="yourDestinationBucketName";
// 創建OssClient實例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
// 添加Bucket清單。
var config = new InventoryConfiguration();
// 設置清單規則名稱。
config.Id = "report1";
// 清單配置是否啟用的標識,取值為true或false。設置為true,表示啟用清單配置。
config.IsEnabled = true;
// 設置清單篩選規則,指定篩選Object的前綴。
config.Filter = new InventoryFilter("filterPrefix");
// 創建清單的bucket目的地配置。
config.Destination = new InventoryDestination();
config.Destination.OSSBucketDestination = new InventoryOSSBucketDestination();
// 設置清單格式。
config.Destination.OSSBucketDestination.Format = InventoryFormat.CSV;
// 存放清單結果的目標Bucket的用戶accountId。
config.Destination.OSSBucketDestination.AccountId = accountId;
// 存放清單結果的目標Bucket的roleArn。
config.Destination.OSSBucketDestination.RoleArn = roleArn;
// 存放清單結果的目標Bucket名稱。
config.Destination.OSSBucketDestination.Bucket = destBucketName;
// 設置存放清單結果的存儲路徑前綴。
config.Destination.OSSBucketDestination.Prefix = "prefix1";
// 設置清單的生成計劃,以下示例為每周一次。其中,Weekly對應每周一次,Daily對應每天一次。
config.Schedule = new InventorySchedule(InventoryFrequency.Daily);
// 設置清單中包含的object的版本為當前版本。如果設置為InventoryIncludedObjectVersions.All則表示object的所有版本,在版本控制狀態下生效。
config.IncludedObjectVersions = InventoryIncludedObjectVersions.All;
// 設置清單中包含的Object屬性。
config.OptionalFields.Add(InventoryOptionalField.Size);
config.OptionalFields.Add(InventoryOptionalField.LastModifiedDate);
config.OptionalFields.Add(InventoryOptionalField.StorageClass);
config.OptionalFields.Add(InventoryOptionalField.IsMultipartUploaded);
config.OptionalFields.Add(InventoryOptionalField.EncryptionStatus);
config.OptionalFields.Add(InventoryOptionalField.ETag);
var req = new SetBucketInventoryConfigurationRequest(bucketName, config);
client.SetBucketInventoryConfiguration(req);
Console.WriteLine("Set bucket:{0} InventoryConfiguration succeeded", bucketName);
}
catch (OssException ex)
{
Console.WriteLine("Failed with error code: {0}; Error info: {1}. \nRequestID:{2}\tHostID:{3}",
ex.ErrorCode, ex.Message, ex.RequestId, ex.HostId);
}
package main
import (
"fmt"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
"os"
)
func main() {
/// 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 創建OSSClient實例。
// yourEndpoint填寫Bucket對應的Endpoint,以華東1(杭州)為例,填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
IsEnabled := true
// 如果需要使用KMS加密清單,請參考如下設置。
//var invEncryption oss.InvEncryption
//var invSseOss oss.InvSseOss
//var invSseKms oss.InvSseKms
//invSseKms.KmsId = "<yourKmsId>" // 填寫KMS密鑰ID。
//invEncryption.SseOss = &invSseOss // 使用OSS完全托管加密(SSE-OSS)方式進行加密。
//invEncryption.SseKms = &invSseKms // 使用KMS托管密鑰(SSE-KMS)的方式進行加密。
invConfig := oss.InventoryConfiguration{
// 由用戶指定的清單名稱,清單名稱在當前Bucket下必須全局唯一。
Id: "yourInventoryId2",
// 啟用清單配置。
IsEnabled: &IsEnabled,
// 設置清單篩選規則,指定篩選Object的前綴。
Prefix: "yourFilterPrefix",
OSSBucketDestination: oss.OSSBucketDestination{
// 導出清單文件的文件格式。
Format: "CSV",
// 存儲空間所有者授予的賬戶ID,例如109885487000****。
AccountId: "yourGrantAccountId",
// 存儲空間所有者授予操作權限的角色名,比如acs:ram::109885487000****:role/ram-test。
RoleArn: "yourRoleArn",
// 存放導出的清單結果的Bucket名稱。
Bucket: "acs:oss:::" + "yourDestBucketName",
// 存放清單結果的存儲路徑前綴。
Prefix: "yourDestPrefix",
// 如果清單需要加密,請參考以下代碼。
//Encryption: &invEncryption,
},
// 清單文件導出的周期。
Frequency: "Daily",
// 是否在清單中包含Object的所有版本信息。
IncludedObjectVersions: "All",
OptionalFields: oss.OptionalFields{
// 清單結果中包含的配置項。
Field: []string{
"Size", "LastModifiedDate", "ETag", "StorageClass", "IsMultipartUploaded", "EncryptionStatus",
},
},
}
// yourBucketName填寫待配置清單規則的Bucket名稱。
err = client.SetBucketInventory("yourBucketName", invConfig)
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
}
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;
int main(void)
{
/* 初始化OSS賬號信息。*/
/* yourEndpoint填寫Bucket所在地域對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
std::string Endpoint = "yourEndpoint";
/* 填寫Bucket名稱,例如examplebucket。*/
std::string BucketName = "examplebucket";
/* 初始化網絡等資源。*/
InitializeSdk();
ClientConfiguration conf;
/* 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
OssClient client(Endpoint, credentialsProvider, conf);
InventoryConfiguration inventoryConf;
/* 指定清單規則名稱,該名稱在當前Bucket下必須全局唯一。*/
inventoryConf.setId("inventoryId");
/* 清單配置是否啟用的標識,可選值為true或false。*/
inventoryConf.setIsEnabled(true);
/* (可選)清單篩選的前綴。指定前綴后,清單將篩選出符合前綴的Object。*/
inventoryConf.setFilter(InventoryFilter("objectPrefix"));
InventoryOSSBucketDestination dest;
/* 導出清單文件的文件格式。*/
dest.setFormat(InventoryFormat::CSV);
/* 存儲空間擁有者的賬戶UID。*/
dest.setAccountId("10988548********");
/* 指定角色名稱,該角色需要擁有讀取源存儲空間所有文件以及向目標存儲空間寫入文件的權限,格式為acs:ram::uid:role/rolename。*/
dest.setRoleArn("acs:ram::10988548********:role/inventory-test");
/* 存放導出的清單文件的存儲空間。*/
dest.setBucket("yourDstBucketName");
/* 清單文件的存儲路徑前綴。*/
dest.setPrefix("yourPrefix");
/* (可選)清單文件的加密方式, 可選SSEOSS或者SSEKMS方式加密。*/
//dest.setEncryption(InventoryEncryption(InventorySSEOSS()));
//dest.setEncryption(InventoryEncryption(InventorySSEKMS("yourKmskeyId")));
inventoryConf.setDestination(dest);
/* 清單文件導出的周期, 可選為Daily或者Weekly。*/
inventoryConf.setSchedule(InventoryFrequency::Daily);
/* 是否在清單中包含Object版本信息, 可選為All或者Current。*/
inventoryConf.setIncludedObjectVersions(InventoryIncludedObjectVersions::All);
/* (可選)設置清單結果中應包含的配置項, 請按需配置。*/
InventoryOptionalFields field {
InventoryOptionalField::Size, InventoryOptionalField::LastModifiedDate,
InventoryOptionalField::ETag, InventoryOptionalField::StorageClass,
InventoryOptionalField::IsMultipartUploaded, InventoryOptionalField::EncryptionStatus
};
inventoryConf.setOptionalFields(field);
/* 設置清單配置。*/
auto outcome = client.SetBucketInventoryConfiguration(
SetBucketInventoryConfigurationRequest(BucketName, inventoryConf));
if (!outcome.isSuccess()) {
/* 異常處理。*/
std::cout << "Set Bucket Inventory fail" <<
",code:" << outcome.error().Code() <<
",message:" << outcome.error().Message() <<
",requestId:" << outcome.error().RequestId() << std::endl;
return -1;
}
/* 釋放網絡等資源。*/
ShutdownSdk();
return 0;
}
使用命令行工具ossutil
關于使用ossutil配置Bucket清單的具體操作, 請參見inventory(清單)。
使用REST API
如果您的程序自定義要求較高,您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。更多信息,請參見PutBucketInventory。
清單文件
清單任務配置完成后,OSS會按清單規則指定的導出周期生成清單文件。清單文件的目錄結構如下:
dest_bucket
└──destination-prefix/
└──src_bucket/
└──inventory_id/
├──YYYY-MM-DDTHH-MMZ/
│ ├──manifest.json
│ └──manifest.checksum
└──data/
└──745a29e3-bfaa-490d-9109-47086afcc8f2.csv.gz
目錄結構 | 說明 |
destination-prefix/ | 該目錄根據設置的清單報告名前綴生成,如果清單報告名前綴設置為空,將省略該目錄。 |
src_bucket/ | 該目錄根據配置清單報告的源Bucket名生成。 |
inventory_id/ | 該目錄根據清單任務的規則名稱生成。 |
YYYY-MM-DDTHH-MMZ/ | 該目錄是標準的格林威治時間戳,表示開始掃描Bucket的時間,例如2020-05-17T16-00Z。該目錄下包含了manifest.json和manifest.checksum文件。 |
data/ | 該目錄下存放了包含源Bucket中的對象列表以及每個對象的元數據的清單文件,清單文件格式為使用GZIP壓縮的CSV文件。 重要
|
清單功能生成的具體文件說明如下:
manifest文件
manifest文件包含manifest.json和manifest.checksum,詳細說明如下:
manifest.json:提供了有關清單的元數據和其他基本信息。
{ "creationTimestamp": "1642994594", "destinationBucket": "destbucket", "fileFormat": "CSV", "fileSchema": "Bucket, Key, VersionId, IsLatest, IsDeleteMarker, Size, StorageClass, LastModifiedDate, ETag, IsMultipartUploaded, EncryptionStatus, ObjectAcl, TaggingCount, ObjectType, Crc64", "files": [{ "MD5checksum": "F77449179760C3B13F1E76110F07****", "key": "destbucket/inventory0124/data/a1574226-b5e5-40ee-91df-356845777c04.csv.gz", "size": 2046}], "sourceBucket": "srcbucket", "version": "2019-09-01"}
各字段詳細說明如下:
字段名稱
說明
creationTimestamp
以紀元日期格式創建的時間戳,顯示開始掃描源Bucket的時間。
destinationBucket
存放清單文件的目標Bucket。
fileFormat
清單文件的格式。
fileSchema
清單文件包含的字段,分為固定字段和可選字段。其中,固定字段的順序是固定的,可選字段的排列順序取決于您配置清單規則時清單內容字段的排列順序(控制臺配置時以字段的勾選先后順序為準)。 因此,建議您以fileSchema中的字段順序去解析csv.gz中的數據列,避免出現列和屬性對應錯誤的情況。
配置清單規則時如果對象版本選擇了當前版本,則fileSchema中,先排列固定字段
Bucket, Key
,后續為可選字段。配置清單規則時如果對象版本選擇了所有版本,則fileSchema中,先排列固定字段
Bucket, Key, VersionId, IsLatest, IsDeleteMarker
,后續為可選字段。
files
包含清單文件的MD5值、文件名完整路徑及文件大小。
sourceBucket
配置清單規則的源Bucket。
version
清單版本號。
manifest.checksum:包含manifest.json文件的MD5值,例如
8420A430CBD6B659A1C0DFC1C11A****
。
清單報告
清單報告存儲在data/目錄中,包含清單功能導出的文件信息。清單報告示例如下:
清單報告具體的字段順序取決于您配置清單規則時的清單內容字段排列順序。以上清單報告示例中,各字段按從左到右的順序說明如下。
字段名稱 | 說明 |
Bucket | 執行清單任務的源Bucket名稱。 |
Key | Bucket中Object的名稱。 Object名稱使用URL編碼,您必須解碼后查看。 |
VersionId | Object的版本ID。 僅當Bucket已開啟版本控制功能,且您配置的清單規則為導出所有版本時出現此字段。 |
IsLatest | Object版本是否為最新版本。當版本為最新版本時取值為True,否則取值為False。 僅當Bucket已開啟版本控制功能,且您配置的清單規則為導出所有版本時出現此字段。 |
IsDeleteMarker | Object版本是否為刪除標記。當版本為刪除標記時取值為True,否則取值為False。 僅當Bucket已開啟版本控制功能,且您配置的清單規則為導出所有版本時出現此字段。 |
Size | Object大小。 |
StorageClass | Object的存儲類型。 |
LastModifiedDate | Object的最后修改時間,格式是格林威治時間,與北京時間相差8小時。 |
ETag | Object的ETag。 Object生成時會創建相應的ETag,用于標識一個Object的內容。
|
IsMultipartUploaded | Object是否通過分片上傳生成。如果是,則該字段值為True,否則為False。 |
EncryptionStatus | Object是否已加密。若Object已加密,則該字段值為True,否則為False。 |
ObjectAcl | Object的讀寫權限。更多信息,請參見Object ACL。 |
TaggingCount | Object的標簽個數。 |
ObjectType | Object類型。更多信息,請參見Object類型。 |
Crc64 | Object的CRC64。 |
注意事項
配置數量
存儲空間清單支持按天或按周導出清單文件。
Bucket內的文件數量 | 導出建議 |
<100億 | 按需配置按天或按周導出 |
100億~500億 | 按周導出 |
≥500億 |
|
流量帶寬說明
為保障較快的清單文件列表導出速度,在清單文件列表導出到目標Bucket的過程中,可能會占用一定的Bucket與用戶級別帶寬。如果存放清單文件列表的目標Bucket與配置清單任務的源Bucket相同,且源Bucket存在流量較大帶寬緊張的情況,建議新建一個目標Bucket用于存放清單結果文件。
異常說明
如果源Bucket沒有任何文件,或清單任務設置的前綴沒有匹配到任何文件,則不會生成清單文件。
導出清單文件的過程中,由于Object的創建、刪除或覆蓋等操作,可能會導致最終輸出的清單列表中不一定包含所有的Object。最后修改時間早于manifest.json文件中createTimeStamp字段顯示時間的Object會出現在清單文件中;最后修改時間晚于createTimeStamp字段顯示時間的Object可能不會出現在清單文件中。建議您對清單列表中的Object進行操作之前,先使用HeadObject接口檢查Object的屬性。更多信息,請參見HeadObject。
清理清單文件
在刪除清單規則前,OSS會根據清單規則中的設置,以天或周為單位持續導出清單文件。為避免持續導出不必要的清單文件,您可以及時刪除不再需要的清單規則。對于已導出且不再需要的存量清單文件,也可以及時清理。