使用資料索引功能快速尋找目標檔案 - Object Storage Service

資料索引是OSS對外提供的檔案（Object）中繼資料索引能力。您可以利用Object的中繼資料自訂索引的條件，從而快速擷取Object列表。資料索引可以協助您更好地管理與瞭解資料結構，方便您後續查詢、統計和管理Object。

使用情境

基於資料審計或者資料監管等原因，您可能需要從存放於OSS儲存空間（Bucket）內多達上億的海量Object中尋找符合特定條件的Object。Object本身包含大量的中繼資料，例如Object名稱、Object ETag、Object儲存類型、Object大小、Object標籤、Object最後修改時間等。通過中繼資料索引功能，您可以在尋找目標Object時結合具體的業務情境，通過組合簡單查詢條件以及彙總操作，提升尋找目標Object的效率。

注意事項

地區限制
華東1（杭州）、華北2（北京）、華北3（張家口）、華南1（深圳）、中國香港、新加坡地區的Bucket支援使用資料索引功能。
Bucket限制
預設只支援為檔案數量在100億以下的Bucket開啟中繼資料管理功能。
費用說明
資料索引目前是公測階段。使用資料索引功能時，需要開啟中繼資料管理。開啟中繼資料管理功能會產生Object的中繼資料管理費用以及檢索次數費用，但公測期間暫不收費。關於資料索引計費項目的更多資訊，請參見資料索引費用。
建立索引所需時間
開啟中繼資料管理功能時，建立索引所需時間與Bucket記憶體量的檔案數量成正比。檔案數量越多，建立索引的時間越長。一般來說，1000萬個檔案初次建立索引的時間約為1小時，10億個檔案初次建立索引的時間約為1天，100億個檔案初次建立索引的時間約為2~3 天，該時間僅供參考。
分區上傳
對於通過分區上傳產生的Object，則查詢結果中只顯示已通過CompleteMultipartUpload操作將片段（Part）合成的完整Object，不顯示已初始化但未完成（Complete）或者未中止（Abort）的片段。

操作步驟

使用OSS控制台

登入OSS管理主控台。
單擊Bucket 列表，然後單擊目標Bucket名稱。
在左側導覽列，選擇文件管理 > 數據索引。
在數據索引頁面，開啟中繼資料管理開關。
開啟中繼資料管理需要等待一定的時間，具體等待時間長度取決於Bucket中Object的數量。

設定Object基礎過濾條件。

在對象基礎過濾條件地區，按需設定以下基礎過濾條件。

過濾條件	說明
存儲類型	預設選中OSS支援的標準、低頻訪問、歸檔、冷歸檔和深度冷歸檔多種儲存類型。您可以按需選擇希望在查詢結果中顯示的Object儲存類型。
讀寫權限	預設選中OSS支援的四種讀寫權限ACL，即繼承Bucket、私人、公用讀取以及公用讀寫。您可以按需選擇希望在查詢結果中顯示的Object讀寫權限。
文件名	支援模糊比對和等於。如果您希望在查詢結果中顯示某個檔案名稱，例如exampleobject.txt。您可以通過以下兩種方式匹配目標檔案：選擇等於，然後輸入完整的檔案名稱`exampleobject.txt`。選擇模糊比對，然後輸入檔案首碼或者尾碼，例如`example`或者`.txt`。重要模糊比對可命中Object名稱的任一字元，例如輸入`test`，則查詢結果中將顯示localfolder/test/.example.jpg、localfolder/test.jpg等。
上傳類型	預設選中OSS支援的四種Object類型，您可以按需選擇希望在查詢結果中顯示的Object類型。Object類型說明如下： Normal：通過簡單上傳方式產生的Object。 Multipart：通過分區上傳方式產生的Object。 Appendable：通過追加上傳方式產生的Object。 Symlink：為快速存取Object建立的軟連結。
最後修改時間	指定Object被最後修改的起始日期和結束日期，時間精確到秒。
檔案大小	支援等於、大於、大於等於、小於和小於等於五種篩選條件，檔案大小單位為KB。
對象版本	僅支援查詢目前的版本Object。

可選：設定Object其他過濾條件。
如果您需要對查詢結果中的Object進行排序或者使用標籤過濾等，請單擊展開更多過濾條件。
- 設定Object排序方式。
  在對象排序方式地區，結合最後修改時間、文件名和檔案大小的篩選條件，選取查詢結果中Object按照這三種篩選條件進行升序或降序排列。
- 設定Object標籤過濾條件。
  在對象標籤過濾地區，輸入您希望在查詢結果中顯示的Object對應的ETag或標籤資訊。
  - ETag僅支援精確匹配。ETag必須帶引號，樣本值為"5B3C1A2E0563E1B002CC607C6689"。可輸入多個ETag，每行一個。
  - 以索引值對（Key-Value）的形式指定對象標籤。對象標籤的Key和Value均區分大小寫。關於標籤規則的更多資訊，請參見對象標籤。
- 設定對象資料彙總方式。
  如果您希望在查詢結果中對資料進行分類統計，例如統計所有檔案大小、去重統計檔案儲存體類型等，請添加資料彙總方式。

使用阿里雲SDK

僅Java SDK、Python SDK以及Go SDK支援通過資料索引功能查詢滿足指定條件的Object。使用資料索引功能前，您需要為指定Bucket開啟中繼資料管理功能。關於資料索引的程式碼範例，請參見SDK簡介。

Java

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 {

    // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
    private static String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
    // 填寫Bucket名稱，例如examplebucket。
    private static String bucketName = "examplebucket";

    public static void main(String[] args) throws Exception {
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 建立OSSClient執行個體。
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            // 查詢滿足指定條件的檔案（Object），並按照指定欄位和排序方式列舉檔案資訊。
            int maxResults = 20;
            // 指定查詢小於1048576位元組的檔案，且最多返回20個結果，返回結果按升序排列。
            String query = "{\"Field\": \"Size\",\"Value\": \"1048576\",\"Operation\": \"lt\"}";
            String sort = "Size";
            DoMetaQueryRequest doMetaQueryRequest = new DoMetaQueryRequest(bucketName, maxResults, query, sort);
            Aggregation aggregationRequest = new Aggregation();
            Aggregations aggregations = new Aggregations();
            List<Aggregation> aggregationList = new ArrayList<Aggregation>();
            // 指定彙總操作的欄位名稱。
            aggregationRequest.setField("Size");
            // 指定彙總操作的操作符，max表示最大值。
            aggregationRequest.setOperation("max");
            aggregationList.add(aggregationRequest);
            aggregations.setAggregation(aggregationList);

            // 設定彙總操作。
            doMetaQueryRequest.setAggregations(aggregations);
            doMetaQueryRequest.setOrder(SortOrder.ASC);
            DoMetaQueryResult doMetaQueryResult = ossClient.doMetaQuery(doMetaQueryRequest);
            if(doMetaQueryResult.getFiles() != null){
                for(ObjectFile file : doMetaQueryResult.getFiles().getFile()){
                    System.out.println("Filename: " + file.getFilename());
                    // 擷取標識Object的內容。
                    System.out.println("ETag: " + file.getETag());
                    // 擷取Object的存取權限
                    System.out.println("ObjectACL: " + file.getObjectACL());
                    // 擷取Object的類型。
                    System.out.println("OssObjectType: " + file.getOssObjectType());
                    // 擷取Object的儲存類型。
                    System.out.println("OssStorageClass: " + file.getOssStorageClass());
                    // 擷取Object的標籤個數。
                    System.out.println("TaggingCount: " + file.getOssTaggingCount());
                    if(file.getOssTagging() != null){
                        for(Tagging tag : file.getOssTagging().getTagging()){
                            System.out.println("Key: " + tag.getKey());
                            System.out.println("Value: " + tag.getValue());
                        }
                    }
                    if(file.getOssUserMeta() != null){
                        for(UserMeta meta : file.getOssUserMeta().getUserMeta()){
                            System.out.println("Key: " + meta.getKey());
                            System.out.println("Value: " + meta.getValue());
                        }
                    }
                }
            } else if(doMetaQueryResult.getAggregations() != null){
                for(Aggregation aggre : doMetaQueryResult.getAggregations().getAggregation()){
                    // 擷取彙總欄位名稱。
                    System.out.println("Field: " + aggre.getField());
                    // 擷取彙總欄位的操作符。
                    System.out.println("Operation: " + aggre.getOperation());
                    // 擷取彙總操作的結果值。
                    System.out.println("Value: " + aggre.getValue());
                    if(aggre.getGroups() != null && aggre.getGroups().getGroup().size() > 0){
                        // 擷取分組彙總的值。
                        System.out.println("Groups value: " + aggre.getGroups().getGroup().get(0).getValue());
                        // 擷取分組彙總的總個數。
                        System.out.println("Groups count: " + aggre.getGroups().getGroup().get(0).getCount());
                    }
                }
            } else {
                System.out.println("NextToken: " + doMetaQueryResult.getNextToken());
            }
        } catch (OSSException oe) {
            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("Error Message: " + ce.getMessage());
        } finally {
            // 關閉OSSClient。
            ossClient.shutdown();
        }
    }

Python

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import MetaQuery, AggregationsRequest
# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Endpoint以杭州為例，其它Region請按實際情況填寫。
# 填寫Bucket名稱，例如examplebucket。
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# 查詢滿足指定條件的Object，並按照指定欄位和排序方式列舉Object資訊。
# 指定查詢小於1 MB的檔案，且最多返回十個結果，返回結果按升序排列。
do_meta_query_request = MetaQuery(max_results=10, query='{"Field": "Size","Value": "1048576","Operation": "lt"}', sort='Size', order='asc')
result = bucket.do_bucket_meta_query(do_meta_query_request)

# 列印Object名稱。
print(result.files[0].file_name)
# 列印Object對應的ETag。
print(result.files[0].etag)
# 列印Object類型。
print(result.files[0].oss_object_type)
# 列印Object儲存類型。
print(result.files[0].oss_storage_class)
# 列印Object的64位CRC值。
print(result.files[0].oss_crc64)
# 列印Object的存取權限。
print(result.files[0].object_acl)

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)
    }    
    // 指定查詢大於30位元組的檔案，且最多返回十個結果，返回結果按升序排列。
    query := oss.MetaQuery{
        NextToken: "",
        MaxResults: 10,
        Query: `{"Field": "Size","Value": "30","Operation": "gt"}`,
        Sort: "Size",
        Order: "asc",
    }
    // 查詢滿足指定條件的Object，並按照指定欄位和排序方式列舉Object資訊。
    result,err := client.DoMetaQuery("examplebucket",query)
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
    fmt.Printf("NextToken:%s\n", result.NextToken)
    for _, file := range result.Files {
        fmt.Printf("File name: %s\n", file.Filename)
        fmt.Printf("size: %d\n", file.Size)
        fmt.Printf("File Modified Time:%s\n", file.FileModifiedTime)
        fmt.Printf("Oss Object Type:%s\n", file.OssObjectType)
        fmt.Printf("Oss Storage Class:%s\n", file.OssStorageClass)
        fmt.Printf("Object ACL:%s\n", file.ObjectACL)
        fmt.Printf("ETag:%s\n", file.ETag)
        fmt.Printf("Oss CRC64:%s\n", file.OssCRC64)
        fmt.Printf("Oss Tagging Count:%d\n", file.OssTaggingCount)
        for _, tagging := range  file.OssTagging {
            fmt.Printf("Oss Tagging Key:%s\n", tagging.Key)
            fmt.Printf("Oss Tagging Value:%s\n", tagging.Value)
        }
        for _, userMeta := range  file.OssUserMeta {
            fmt.Printf("Oss User Meta Key:%s\n", userMeta.Key)
            fmt.Printf("Oss User Meta Key Value:%s\n", userMeta.Value)
        }
    }
}

使用REST API

如果您的程式自訂要求較高，您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。更多資訊，請參見DoMetaQuery。

常見問題

Bucket內檔案數量達到上億層級時，為什麼很長時間都沒有成功建立資料索引？

1秒內大約可以為600個檔案建立索引。您可以結合Bucket內的檔案數量，預估建立索引所需時間。

Object Storage Service：資料索引（Data Indexing）