使用標(biāo)量檢索基于元數(shù)據(jù)屬性查詢OSS中的文件
標(biāo)量檢索是OSS提供的基于Object元數(shù)據(jù)的索引功能,允許您自定義條件,快速篩選并獲取Object列表。可以幫助您更好地管理與了解數(shù)據(jù)結(jié)構(gòu),方便您后續(xù)查詢、統(tǒng)計(jì)和管理Object。
使用場(chǎng)景
數(shù)據(jù)審計(jì)場(chǎng)景
通過(guò)標(biāo)量檢索,您可以快速定位文件,以滿足數(shù)據(jù)審計(jì)或監(jiān)管需求。例如,在金融服務(wù)行業(yè),您可以通過(guò)自定義標(biāo)簽、訪問(wèn)權(quán)限等元數(shù)據(jù)進(jìn)行篩選,從而找到具有特定敏感性級(jí)別或特定權(quán)限的文件,以提升數(shù)據(jù)審計(jì)的效率。
企業(yè)備份與歸檔場(chǎng)景
企業(yè)在進(jìn)行數(shù)據(jù)備份和歸檔時(shí),可以利用標(biāo)量檢索,例如根據(jù)文件的創(chuàng)建時(shí)間、存儲(chǔ)類型或自定義標(biāo)簽等元數(shù)據(jù),迅速檢索到特定日期或類型的文件,從而快速恢復(fù)歷史數(shù)據(jù)或歸檔記錄。
注意事項(xiàng)
地域限制
華東1(杭州)、華東2(上海)、華北1(青島)、華北2(北京)、華北3(張家口)、華南1(深圳)、華南3(廣州)、西南1(成都)、中國(guó)香港、新加坡、印度尼西亞(雅加達(dá))、德國(guó)(法蘭克福)、美國(guó)(弗吉尼亞)、美國(guó)(硅谷)、英國(guó)(倫敦)地域的Bucket支持使用標(biāo)量檢索功能。
Bucket限制
默認(rèn)只支持為文件數(shù)量在100億以下的Bucket開(kāi)啟標(biāo)量檢索功能。
費(fèi)用說(shuō)明
標(biāo)量檢索目前是公測(cè)階段。使用標(biāo)量檢索功能會(huì)產(chǎn)生Object的元數(shù)據(jù)管理費(fèi)用以及檢索次數(shù)費(fèi)用,但公測(cè)期間暫不收費(fèi)。關(guān)于標(biāo)量檢索計(jì)費(fèi)項(xiàng)的更多信息,請(qǐng)參見(jiàn)數(shù)據(jù)索引費(fèi)用。
除標(biāo)量檢索計(jì)費(fèi)項(xiàng)外,使用標(biāo)量檢索還會(huì)產(chǎn)生API請(qǐng)求費(fèi)用,按照API調(diào)用次數(shù)收費(fèi)。涉及的API請(qǐng)求如下:
行為
API
次數(shù)
為Bucket中的文件構(gòu)建索引
HeadObject
每個(gè)文件調(diào)用1次
Bucket中文件存在Tag
GetObjectTag
每個(gè)攜帶Tag的文件調(diào)用1次
Bucket中存在軟鏈接文件
GetSymlink
每個(gè)攜帶軟鏈接的文件調(diào)用1次
掃描Bucket中的文件
ListObjects
每掃描1000個(gè)文件調(diào)用1次
關(guān)于OSS API的請(qǐng)求費(fèi)用,請(qǐng)參見(jiàn)請(qǐng)求費(fèi)用。
建立索引所需時(shí)間
開(kāi)啟標(biāo)量檢索功能時(shí),建立索引所需時(shí)間與Bucket內(nèi)存量的文件數(shù)量成正比。文件數(shù)量越多,建立索引的時(shí)間越長(zhǎng)。 一般來(lái)說(shuō),1000萬(wàn)個(gè)文件初次建立索引的時(shí)間約為1小時(shí),10億個(gè)文件初次建立索引的時(shí)間約為1天,100億個(gè)文件初次建立索引的時(shí)間約為2~3 天,該時(shí)間僅供參考。
分片上傳
對(duì)于通過(guò)分片上傳生成的Object,查詢結(jié)果中只顯示已通過(guò)CompleteMultipartUpload操作將碎片(Part)合成的完整Object,不顯示已初始化但未完成(Complete)或者未中止(Abort)的碎片。
操作步驟
使用OSS控制臺(tái)
以查找所有文件大小小于500KB,最后更新時(shí)間在2024年9月11日0:00至2024年9月12日0:00的文件,輸出結(jié)果按文件大小升序排列,并按文件大小統(tǒng)計(jì)最大值為例:
Bucket為廣州地域
單擊Bucket 列表,然后單擊目標(biāo)Bucket名稱。
在左側(cè)導(dǎo)航欄, 選擇 。
在數(shù)據(jù)索引頁(yè)面,單擊立即開(kāi)啟。
選擇標(biāo)量檢索,單擊確認(rèn)開(kāi)啟。
說(shuō)明開(kāi)啟標(biāo)量檢索需要等待一定的時(shí)間,具體等待時(shí)長(zhǎng)取決于Bucket中Object的數(shù)量。
按以下說(shuō)明設(shè)置OSS元數(shù)據(jù)檢索條件,其他參數(shù)保留默認(rèn)設(shè)置。
將最后修改時(shí)間設(shè)置為2024年9月11日0:00至2024年9月12日0:00。
文件大小設(shè)置為小于500KB。
設(shè)置輸出方式。
對(duì)象排序方式選擇按照文件大小升序排列。
數(shù)據(jù)聚合選擇按照文件大小的最大值聚合輸出。
單擊立即查詢。符合檢索條件的所有文件共2個(gè),如下圖所示,文件最大為434KB。
如需了解完整的檢索條件和輸出設(shè)置,請(qǐng)參見(jiàn)檢索條件及輸出設(shè)置。
Bucket為杭州、上海、青島、北京、張家口、深圳、成都、中國(guó)香港、新加坡、雅加達(dá)、法蘭克福、弗吉尼亞、硅谷、倫敦地域
單擊Bucket 列表,然后單擊目標(biāo)Bucket名稱。
在左側(cè)導(dǎo)航欄, 選擇 。
開(kāi)啟元數(shù)據(jù)管理。
說(shuō)明開(kāi)啟元數(shù)據(jù)管理需要等待一定的時(shí)間,具體等待時(shí)長(zhǎng)取決于Bucket中Object的數(shù)量。
按以下說(shuō)明設(shè)置對(duì)象基礎(chǔ)過(guò)濾條件,其他參數(shù)保留默認(rèn)設(shè)置。
將最后修改時(shí)間設(shè)置為2024年9月11日0:00至2024年9月12日0:00。
文件大小設(shè)置為小于500KB。
展開(kāi)更多過(guò)濾條件。
對(duì)象排序方式選擇按照文件大小升序排列。
數(shù)據(jù)聚合選擇按照文件大小的最大值聚合輸出。
單擊查詢。符合檢索條件的所有文件共2個(gè),如下圖所示,文件最大為434KB。
如需了解完整的檢索條件和輸出設(shè)置,請(qǐng)參見(jiàn)檢索條件及輸出設(shè)置。
使用阿里云SDK
僅Java SDK、Python SDK以及Go SDK支持通過(guò)標(biāo)量檢索功能查詢滿足指定條件的Object。使用標(biāo)量檢索功能前,您需要為指定Bucket開(kāi)啟元數(shù)據(jù)管理功能。關(guān)于標(biāo)量檢索的代碼示例,請(qǐng)參見(jiàn)SDK簡(jiǎn)介。
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請(qǐng)按實(shí)際情況填寫。
private static String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填寫B(tài)ucket名稱,例如examplebucket。
private static String bucketName = "examplebucket";
public static void main(String[] args) throws Exception {
// 從環(huán)境變量中獲取訪問(wèn)憑證。運(yùn)行本代碼示例之前,請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 填寫B(tài)ucket所在地域。以華東1(杭州)為例,Region填寫為cn-hangzhou。
String region = "cn-hangzhou";
// 創(chuàng)建OSSClient實(shí)例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// 查詢滿足指定條件的文件(Object),并按照指定字段和排序方式列舉文件信息。
int maxResults = 20;
// 指定查詢小于1048576字節(jié)的文件,且最多返回20個(gè)結(jié)果,返回結(jié)果按升序排列。
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);
// 設(shè)置聚合操作。
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());
// 獲取標(biāo)識(shí)Object的內(nèi)容。
System.out.println("ETag: " + file.getETag());
// 獲取Object的訪問(wèn)權(quán)限
System.out.println("ObjectACL: " + file.getObjectACL());
// 獲取Object的類型。
System.out.println("OssObjectType: " + file.getOssObjectType());
// 獲取Object的存儲(chǔ)類型。
System.out.println("OssStorageClass: " + file.getOssStorageClass());
// 獲取Object的標(biāo)簽個(gè)數(shù)。
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());
// 獲取聚合操作的結(jié)果值。
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());
// 獲取分組聚合的總個(gè)數(shù)。
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 {
// 關(guān)閉OSSClient。
ossClient.shutdown();
}
}
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import MetaQuery, AggregationsRequest
# 從環(huán)境變量中獲取訪問(wèn)憑證。運(yùn)行本代碼示例之前,請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填寫B(tài)ucket所在地域?qū)?yīng)的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填寫Endpoint對(duì)應(yīng)的Region信息,例如cn-hangzhou。注意,v4簽名下,必須填寫該參數(shù)
region = "cn-hangzhou"
# examplebucket填寫存儲(chǔ)空間名稱。
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)
# 查詢滿足指定條件的Object,并按照指定字段和排序方式列舉Object信息。
# 指定查詢小于1 MB的文件,且最多返回十個(gè)結(jié)果,返回結(jié)果按升序排列。
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對(duì)應(yīng)的ETag。
print(result.files[0].etag)
# 打印Object類型。
print(result.files[0].oss_object_type)
# 打印Object存儲(chǔ)類型。
print(result.files[0].oss_storage_class)
# 打印Object的64位CRC值。
print(result.files[0].oss_crc64)
# 打印Object的訪問(wèn)權(quán)限。
print(result.files[0].object_acl)
package main
import (
"fmt"
"os"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func main() {
// 從環(huán)境變量中獲取訪問(wèn)憑證。運(yùn)行本代碼示例之前,請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 創(chuàng)建OSSClient實(shí)例。
// yourEndpoint填寫B(tài)ucket對(duì)應(yīng)的Endpoint,以華東1(杭州)為例,填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請(qǐng)按實(shí)際情況填寫。
// yourRegion填寫B(tài)ucket所在地域,以華東1(杭州)為例,填寫為cn-hangzhou。其它Region請(qǐng)按實(shí)際情況填寫。
clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
clientOptions = append(clientOptions, oss.Region("yourRegion"))
// 設(shè)置簽名版本
clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
client, err := oss.New("yourEndpoint", "", "", clientOptions...)
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 指定查詢大于30字節(jié)的文件,且最多返回十個(gè)結(jié)果,返回結(jié)果按升序排列。
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
如果您的程序自定義要求較高,您可以直接發(fā)起REST API請(qǐng)求。直接發(fā)起REST API請(qǐng)求需要手動(dòng)編寫代碼計(jì)算簽名。更多信息,請(qǐng)參見(jiàn)DoMetaQuery。
檢索條件及輸出設(shè)置
檢索條件
以下是完整的檢索條件,您可以根據(jù)需要進(jìn)行單獨(dú)或組合設(shè)置。
檢索條件 | 說(shuō)明 |
存儲(chǔ)類型 | 默認(rèn)選中OSS支持的標(biāo)準(zhǔn)、低頻訪問(wèn)、歸檔、冷歸檔和深度冷歸檔多種存儲(chǔ)類型。您可以按需選擇希望在查詢結(jié)果中顯示的Object存儲(chǔ)類型。 |
讀寫權(quán)限 | 默認(rèn)選中OSS支持的四種讀寫權(quán)限ACL,即繼承Bucket、私有、公共讀以及公共讀寫。您可以按需選擇希望在查詢結(jié)果中顯示的Object讀寫權(quán)限。 |
文件名 | 支持模糊匹配和等于。如果您希望在查詢結(jié)果中顯示某個(gè)文件名,例如exampleobject.txt。您可以通過(guò)以下兩種方式匹配目標(biāo)文件:
|
上傳類型 | 默認(rèn)選中OSS支持的四種Object類型,您可以按需選擇希望在查詢結(jié)果中顯示的Object類型。Object類型說(shuō)明如下:
|
最后修改時(shí)間 | 指定Object被最后修改的起始日期和結(jié)束日期,時(shí)間精確到秒。 |
文件大小 | 支持等于、大于、大于等于、小于和小于等于五種篩選條件,文件大小單位為KB。 |
對(duì)象版本 | 僅支持查詢當(dāng)前版本Object。 |
如需根據(jù)對(duì)象Etag及標(biāo)簽進(jìn)行過(guò)濾查找,可輸入您希望在查詢結(jié)果中顯示的Object對(duì)應(yīng)的ETag或標(biāo)簽信息。
ETag僅支持精確匹配。ETag必須帶引號(hào),示例值為"5B3C1A2E0563E1B002CC607C6689"。可輸入多個(gè)ETag,每行一個(gè)。
以鍵值對(duì)(Key-Value)的形式指定對(duì)象標(biāo)簽。對(duì)象標(biāo)簽的Key和Value均區(qū)分大小寫。關(guān)于標(biāo)簽規(guī)則的更多信息,請(qǐng)參見(jiàn)對(duì)象標(biāo)簽。
結(jié)果輸出設(shè)置
您可對(duì)輸出結(jié)果進(jìn)行排序和簡(jiǎn)單統(tǒng)計(jì)。
對(duì)象排序方式:支持根據(jù)最后修改時(shí)間、文件名和文件大小進(jìn)行升序、降序及默認(rèn)排序。您可以按需選擇并排序檢索結(jié)果,便于快速找到所需文件。
數(shù)據(jù)聚合:支持多種輸出類型,您可以對(duì)檢索結(jié)果進(jìn)行去重統(tǒng)計(jì)、分組計(jì)數(shù)、最大值、最小值、平均值和求和等計(jì)算,便于高效分析和管理數(shù)據(jù)。
常見(jiàn)問(wèn)題
Bucket內(nèi)文件數(shù)量達(dá)到上億級(jí)別時(shí),為什么很長(zhǎng)時(shí)間都沒(méi)有成功建立數(shù)據(jù)索引?
1秒內(nèi)大約可以為600個(gè)文件建立索引。您可以結(jié)合Bucket內(nèi)的文件數(shù)量,預(yù)估建立索引所需時(shí)間。
相關(guān)文檔
標(biāo)量檢索支持多項(xiàng)過(guò)濾條件,例如文件最后修改時(shí)間、存儲(chǔ)類型、讀寫權(quán)限、文件大小等。如果您希望從OSS Bucket的海量Object中篩選出指定時(shí)間范圍內(nèi)的Object,請(qǐng)參見(jiàn)如何篩選OSS指定時(shí)間范圍內(nèi)的文件?。