全部產品
Search
文件中心

Object Storage Service:儲存空間清單

更新時間:Nov 23, 2024

您可以使用Object Storage Service的清單功能擷取儲存空間(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寫入清單結果檔案的操作是OSS服務通過扮演使用者建立的RAM角色來完成。

您可以通過以下步驟為RAM使用者授權,建立RAM角色並為RAM角色授權。授權完成後,您可以建立清單規則。具體操作,請參見建立清單規則

重要

考慮到授予RAM使用者建立CreateRoleGetRoles等角色相關的許可權風險較大,您可以通過RAM使用者關聯的阿里雲帳號建立RAM角色並為相應的RAM角色完成授權。授權完成後,RAM使用者可以直接複用阿里雲帳號建立的RAM角色。

  • RAM使用者授權

    按如下步驟授予RAM使用者擁有建立Role以及配置清單規則的許可權。

    1. 通過指令碼編輯模式建立以下自訂策略。具體操作,請參見建立自訂權限原則

      說明

      以下授權策略中,僅在通過控制台的方式訪問時,需要授予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"
      }
    2. 為RAM使用者授予已建立的自訂策略。具體操作,請參見為RAM使用者授權

      完成RAM使用者授權後,RAM使用者具備建立RAM角色以及為RAM角色授權的許可權,請參見後續步驟完成RAM角色授權。

  • 建立RAM角色並為RAM角色授權

    重要

    如果您希望使用KMS祕密金鑰加密資訊清單檔,您還需要為建立的RAM角色授予AliyunKMSFullAccess(管理Key Management Service的許可權)。

    • 自動建立的RAM角色AliyunOSSRole

      通過控制台配置清單規則時,RAM控制台會自動建立RAM角色AliyunOSSRole,該角色預設擁有向目標Bucket寫入清單結果檔案的許可權。

      重要

      使用自動建立的RAM角色AliyunOSSRole可以避免額外的授權操作,但是該角色預設擁有管理OSS的許可權,許可權範圍較大。基於許可權範圍考慮,您還可以選擇建立自訂RAM角色,並授予RAM角色最小許可權。

    • 自訂RAM角色

      如果您需要使用自訂RAM角色向目標Bucket寫入清單結果檔案,請執行以下步驟建立RAM角色並為該角色授予權限原則:

      1. 建立普通服務角色。

        建立普通服務角色過程中,受信服務選擇Object Storage Service。其他參數的配置資訊,請參見建立可信實體為阿里雲服務的RAM角色

      2. 通過可視化編輯模式建立自訂權限原則。

        建立自訂權限原則過程中,您需要按照以下說明配置權限原則。其他參數的配置資訊,請參見建立自訂權限原則

        參數

        說明

        效果

        選中允許

        服務

        選中Object Storage Service

        操作

        選中指定操作,然後選中寫操作下的oss:PutObject

        資源

        選中全部資源

        該權限原則對應的JSON格式如下:

        {
          "Version": "1",
          "Statement": [
            {
              "Effect": "Allow",
              "Action": "oss:PutObject",
              "Resource": "*"
            }
          ]
        }
      3. 為角色授予自訂權限原則。

        具體操作,請參見為RAM角色授權

操作步驟

使用OSS控制台

  1. 登入OSS管理主控台

  2. 單擊Bucket 列表,然後單擊目標Bucket名稱。

  3. 在左側導覽列,選擇資料管理 > Bucket 清單

  4. Bucket 清單頁面,單擊建立清單

  5. 設定清單報告規則面板,按以下說明配置各項參數。

    參數

    說明

    狀態

    設定清單任務的狀態。可以選擇啟動禁用

    規則名稱

    設定清單任務的名稱。只能包含小寫字母、數字、短劃線(-),且不能以短劃線(-)開頭或結尾。

    儲存清單 Bucket

    選擇儲存資訊清單檔的Bucket。

    配置清單的源Bucket與存放資訊清單檔的目標Bucket可以相同也可以不同,但是必須屬於同一帳號下的相同地區。

    清單報告儲存路徑

    設定清單報告儲存路徑。

    • 如果要將清單報告儲存在Bucket根目錄下,請將此項置空。

    • 如果要將清單報告儲存在Bucket非根目錄下,請填寫不包含Bucket名稱在內的完整路徑。

      例如,當您需要將清單報告儲存在儲存空間examplebucket的exampledir1路徑下,則填寫為exampledir1。當您需要將清單報告儲存在儲存空間examplebucket的exampledir1/exampledir2路徑下,則填寫為exampledir1/exampledir2

    說明

    如果Bucket中不存在指定的清單報告儲存路徑,OSS會根據填寫的清單報告儲存路徑自動建立對應的路徑。

    清單報告匯出周期

    設定清單報告的組建循環。可選擇每周每天

    • 當檔案數量小於100億時,您可以根據自己的業務需要,設定按周或按天匯出清單。

    • 當檔案數量大於100億時,建議設定以周為單位匯出清單。

    清單報告加密選項

    是否加密資訊清單檔。

    • :不加密。

    • AES256:使用AES256密碼編譯演算法加密資訊清單檔。

    • KMS:使用KMS祕密金鑰加密資訊清單檔。

      您可以選擇使用OSS託管的KMS密鑰或在KMS平台建立一個與目標Bucket相同地區的KMS密鑰。KMS密鑰配置步驟,請參見建立密鑰

      說明

      使用KMS密鑰功能時會產生少量的KMS密鑰API調用費用。

    清單內容

    選擇您希望匯出的檔案資訊,包括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。

    • 儲存類型:設定待匯出哪些儲存類型的檔案。您可以選擇匯出標準儲存、低頻訪問、Archive Storage、冷Archive Storage以及深度冷Archive Storage的檔案。

    對象版本

    選擇清單掃描的檔案版本。

    如果Bucket已開啟版本控制,可選擇匯出目標檔案的目前的版本所有版本。更多資訊,請參見版本控制概述

    如果Bucket未開啟版本控制,預設匯出所有檔案。

  6. 選中我知曉並同意授予阿里雲 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";
        // 填寫Bucket所在地區。以華東1(杭州)為例,Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填寫Endpoint對應的Region資訊,例如cn-hangzhou。注意,v4簽名下,必須填寫該參數
region = "cn-hangzhou"

# examplebucket填寫儲存空間名稱。
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# 填寫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";
// 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";

// 建立ClientConfiguration執行個體,按照您的需要修改預設參數。
var conf = new ClientConfiguration();

// 設定v4簽名。
conf.SignatureVersion = SignatureVersion.V4;

// 建立OssClient執行個體。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
c.SetRegion(region);
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"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

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請按實際情況填寫。
	// yourRegion填寫Bucket所在地區,以華東1(杭州)為例,填寫為cn-hangzhou。其它Region請按實際情況填寫。
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// 設定簽名版本
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	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";
    /* yourRegion填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。*/
    std::string Region = "yourRegion";
    /* 填寫Bucket名稱,例如examplebucket。*/
    std::string BucketName = "examplebucket";

    /* 初始化網路等資源。*/
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    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.jsonmanifest.checksum檔案。

data/

該目錄下存放了包含源Bucket中的對象列表以及每個對象的中繼資料的資訊清單檔,資訊清單檔格式為使用GZIP壓縮的CSV檔案。

重要
  • 當匯出的源Bucket中Object數量較多時,為方便使用者下載和處理資料,程式會自動將資訊清單檔切分成多個CSV壓縮檔。CSV壓縮檔按照uuid.csv.gzuuid-1.csv.gzuuid-2.csv.gz的順序依次遞增。您可以從manifest.json檔案中擷取CSV檔案清單,然後按照以上順序依次解壓CSV檔案並讀取清單資料。

  • Object的單條記錄資訊僅出現在一個資訊清單檔內,不會分布到不同的資訊清單檔。

清單功能產生的具體檔案說明如下:

manifest檔案

manifest檔案包含manifest.jsonmanifest.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/目錄中,包含清單功能匯出的檔案資訊。清單報告樣本如下:

DCDD87B7-7499-4D22-B684-8B25B6F1C232.png

清單報告具體的欄位順序取決於您配置清單規則時的清單內容欄位排列順序。以上清單報告樣本中,各欄位按從左至右的順序說明如下。

欄位名稱

說明

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的內容。

  • 通過PutObject介面建立的Object,ETag值是其內容的MD5值。

  • 通過其他方式建立的Object,ETag值是基於一定計算規則產生的唯一值,但不是其內容的MD5值。

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用於存放清單結果檔案。

異常說明

  • 如果源Bucket沒有任何檔案,或清單任務設定的首碼沒有匹配到任何檔案,則不會產生資訊清單檔。

  • 匯出資訊清單檔的過程中,由於Object的建立、刪除或覆蓋等操作,可能會導致最終輸出的清單列表中不一定包含所有的Object。最後修改時間早於manifest.json檔案中createTimeStamp欄位顯示時間的Object會出現在資訊清單檔中;最後修改時間晚於createTimeStamp欄位顯示時間的Object可能不會出現在資訊清單檔中。建議您對清單列表中的Object進行操作之前,先使用HeadObject介面檢查Object的屬性。更多資訊,請參見HeadObject

清理資訊清單檔

在刪除清單規則前,OSS會根據清單規則中的設定,以天或周為單位持續匯出資訊清單檔。為避免持續匯出不必要的資訊清單檔,您可以及時刪除不再需要的清單規則。對於已匯出且不再需要的存量資訊清單檔,也可以及時清理。

常見問題