API概覽 - Object Storage Service

為開發人員提供Object Storage Service 的 API 概覽，協助理解其核心概念與資源模型，並快速尋找所需介面。如果要進行快速二次開發，建議在生產環境中使用SDK開發包，其封裝了複雜的簽名、重試和並發邏輯，本文可作為 SDK 底層實現原理的參考，適用於需要深度定製或理解通訊機制的情境。

開始使用前，請注意：

API 的使用須遵循OSS使用限制。
建議在正式接入前瞭解OSS的計費說明，定價詳情見OSS產品定價。

快速上手：調用第一個API

以建立儲存空間（PutBucket）為例，介紹一次完整的API調用流程。

1. 準備工作

開始前，需擷取以下資訊：

AccessKey：為保證訪問安全，除匿名訪問外的所有 OSS API 請求都必須經過簽名認證。OSS 使用基於AccessKey（AccessKey ID 和 AccessKey Secret）的簽名機制驗證請求。簽名資訊需通過 HTTP 要求頭中的 Authorization 欄位傳遞，計算方法見簽名版本4（推薦）。
Endpoint：API 請求必鬚髮送到目標儲存空間所在地區的 Endpoint，Endpoint是訪問OSS服務的入口地址，各地區對應的 Endpoint 詳情見地區和Endpoint。

2. 構造並發送請求

PUT / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 03:15:40 GMT
x-oss-acl: private
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
    <DataRedundancyType>LRS</DataRedundancyType>    
</CreateBucketConfiguration>

3. 理解響應結果

成功響應：請求成功後，伺服器會返回 2xx 狀態代碼。對於有返回內容的操作，響應體為 XML 格式。

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

錯誤處理：請求失敗時，伺服器會返回 4xx 或 5xx 狀態代碼。響應體同樣為 XML 格式，其中包含具體的錯誤碼（Code）和錯誤資訊（Message），可參考錯誤碼定位問題

API 列表

關於Service操作

API	描述
ListBuckets（GetService）	返回要求者擁有的所有儲存空間（Bucket）。
ListUserDataRedundancyTransition	列舉要求者所有的儲存冗餘轉換任務。

關於Region操作

API	描述
DescribeRegions	查詢所有支援地區或者指定地區對應的Endpoint資訊。

關於Bucket操作

分類	API	描述
基礎操作	PutBucket	建立Bucket。
	DeleteBucket	刪除Bucket。
	ListObjects（GetBucket）	列出Bucket中所有檔案（Object）的資訊。
	ListObjectsV2（GetBucketV2）	列出Bucket中所有檔案（Object）的資訊。
	GetBucketInfo	擷取Bucket資訊。
	GetBucketLocation	擷取Bucket所屬的位置資訊。
	GetBucketStat	擷取Bucket的儲存容量以及Object數量。
合規保留原則（WORM）	InitiateBucketWorm	建立合規保留原則。
	AbortBucketWorm	刪除未鎖定的合規保留原則。
	CompleteBucketWorm	鎖定合規保留原則。
	ExtendBucketWorm	延長鎖定的合規保留原則對應Bucket中Object的保留天數。
	GetBucketWorm	擷取Bucket的合規保留原則資訊。
許可權控制（ACL）	PutBucketAcl	設定Bucket存取權限。
許可權控制（ACL）	GetBucketAcl	擷取Bucket存取權限。
生命週期（Lifecycle）	PutBucketLifecycle	設定Bucket中Object的生命週期規則。
	GetBucketLifecycle	擷取Bucket中Object的生命週期規則。
	DeleteBucketLifecycle	刪除Bucket中Object的生命週期規則。
傳輸加速（TransferAcceleration）	PutBucketTransferAcceleration	為儲存空間（Bucket）配置傳輸加速。
傳輸加速（TransferAcceleration）	GetBucketTransferAcceleration	擷取目標儲存空間（Bucket）的傳輸加速配置。
版本控制（Versioning）	PutBucketVersioning	設定Bucket的版本控制狀態。
	GetBucketVersioning	擷取Bucket的版本控制狀態。
	ListObjectVersions（GetBucketVersions）	列舉Bucket中所有Object的版本資訊。
資料複製（Replication）	PutBucketReplication	設定Bucket的資料複製規則。
	PutBucketRTC	為已有的跨地區複製規則開啟或關閉資料複製時間控制（RTC）功能。
	GetBucketReplication	查看Bucket已設定的資料複製規則。
	GetBucketReplicationLocation	查看可複製到的目標Bucket所在的地區。
	GetBucketReplicationProgress	查看Bucket的資料複製進度。
	DeleteBucketReplication	停止Bucket的資料複製任務並刪除Bucket的複製配置。
授權策略（Policy）	PutBucketPolicy	設定Bucket Policy。
	GetBucketPolicy	擷取Bucket Policy。
	GetBucketPolicyStatus	查看當前Bucket Policy是否允許公用訪問。
	DeleteBucketPolicy	刪除Bucket Policy。
清單（Inventory）	PutBucketInventory	設定Bucket清單規則。
	GetBucketInventory	查看Bucket中指定的清單任務。
	ListBucketInventory	查看Bucket中所有的清單任務。
	DeleteBucketInventory	刪除Bucket中指定的清單任務。
日誌管理（Logging）	PutBucketLogging	開啟Bucket訪問日誌記錄功能。
	GetBucketLogging	查看Bucket的訪問日誌配置情況。
	DeleteBucketLogging	關閉Bucket訪問日誌記錄功能。
	PutUserDefinedLogFieldsConfig	為Bucket即時日誌中的`user_defined_log_fields`欄位進行個人化配置。
	GetUserDefinedLogFieldsConfig	擷取Bucket即時日誌中的`user_defined_log_fields`欄位進行個人化配置。
	DeleteUserDefinedLogFieldsConfig	刪除Bucket即時日誌中的`user_defined_log_fields`欄位進行個人化配置。
靜態網站（Website）	PutBucketWebsite	設定Bucket為靜態網站託管模式。
	GetBucketWebsite	查看Bucket的靜態網站託管狀態。
	DeleteBucketWebsite	關閉Bucket的靜態網站託管模式。
防盜鏈（Referer）	PutBucketReferer	設定Bucket的防盜鏈規則。
防盜鏈（Referer）	GetBucketReferer	查看Bucket的防盜鏈規則。
標籤（Tags）	PutBucketTags	添加或修改Bucket標籤。
	GetBucketTags	查看Bucket標籤資訊。
	DeleteBucketTags	刪除Bucket標籤。
加密（Encryption）	PutBucketEncryption	配置Bucket的加密規則。
	GetBucketEncryption	擷取Bucket的加密規則。
	DeleteBucketEncryption	刪除Bucket的加密規則。
要求者付費（RequestPayment）	PutBucketRequestPayment	設定Bucket為要求者付費模式。
要求者付費（RequestPayment）	GetBucketRequestPayment	查看Bucket要求者付費模式配置資訊。
跨域資源共用（CORS）	PutBucketCors	為指定的儲存空間（Bucket）設定跨域資源共用CORS（Cross-Origin Resource Sharing）規則。
	GetBucketCors	擷取指定儲存空間（Bucket）當前的跨域資源共用CORS規則。
	DeleteBucketCors	關閉指定儲存空間（Bucket）對應的跨域資源共用CORS功能並清空所有規則。
	Options	瀏覽器在發送跨域請求之前會發送一個preflight請求（Options）給OSS，並帶上特定的來源域、HTTP方法和header等資訊，以決定是否發送真正的請求。
訪問跟蹤（AccessMonitor）	PutBucketAccessMonitor	配置Bucket的訪問跟蹤狀態。
訪問跟蹤（AccessMonitor）	GetBucketAccessMonitor	擷取Bucket的訪問跟蹤狀態。
資料索引（Data Indexing）	OpenMetaQuery	為Bucket開啟中繼資料管理功能。
	GetMetaQueryStatus	擷取指定Bucket的中繼資料索引庫資訊。
	DoMetaQuery	查詢滿足指定條件的Object，並按照指定欄位和排序方式列出Object資訊。
	CloseMetaQuery	關閉Bucket的中繼資料管理功能。
高防（DDoS Protection）	InitUserAntiDDosInfo	建立高防OSS執行個體。
	UpdateUserAntiDDosInfo	更改高防OSS執行個體狀態。
	GetUserAntiDDosInfo	查詢指定帳號下的高防OSS執行個體資訊。
	InitBucketAntiDDosInfo	初始化Bucket防護。
	UpdateBucketAntiDDosInfo	更新Bucket防護狀態。
	ListBucketAntiDDosInfo	擷取Bucket防護資訊列表。
資源群組	PutBucketResourceGroup	為Bucket配置所屬資源群組。
資源群組	GetBucketResourceGroup	擷取Bucket的資源群組ID。
自訂網域名（CNAME）	CreateCnameToken	建立網域名稱所有權驗證所需的CnameToken。
	GetCnameToken	擷取已建立的CnameToken。
	PutCname	為某個Bucket綁定CNAME。
	ListCname	擷取某個Bucket下綁定的所有CNAME列表。
	DeleteCname	刪除已綁定的CNAME。
圖片樣式（Style）	PutStyle	新增圖片樣式。
	GetStyle	擷取某個Bucket下指定的圖片樣式資訊。
	ListStyle	擷取某個Bucket下已建立的所有圖片樣式。
	DeleteStyle	刪除某個Bucket下指定的圖片樣式。
安全傳輸層協議（TLS）	PutBucketHttpsConfig	為Bucket開啟或關閉TLS版本設定。
安全傳輸層協議（TLS）	GetBucketHttpsConfig	查看Bucket的TLS版本設定。
儲存冗餘轉換（RedundancyTransition）	CreateBucketDataRedundancyTransition	建立儲存冗餘轉換任務。
	GetBucketDataRedundancyTransition	擷取儲存冗餘轉換任務。
	DeleteBucketDataRedundancyTransition	刪除儲存冗餘轉換任務。
	ListUserDataRedundancyTransition	列舉要求者所有的儲存冗餘轉換任務。
	ListBucketDataRedundancyTransition	列舉某個Bucket下所有的儲存冗餘轉換任務。
存取點（AccessPoint）	CreateAccessPoint	建立存取點。
	GetAccessPoint	擷取存取點資訊。
	DeleteAccessPoint	刪除存取點。
	ListAccessPoints	擷取使用者層級或Bucket層級的存取點資訊。
	PutAccessPointPolicy	配置存取點策略。
	GetAccessPointPolicy	擷取存取點策略配置。
	DeleteAccessPointPolicy	刪除存取點策略。
對象FC存取點（Object FC AccessPoint）	CreateAccessPointForObjectProcess	建立對象FC存取點。
	GetAccessPointForObjectProcess	擷取對象FC存取點基礎資訊。
	DeleteAccessPointForObjectProcess	刪除對象FC存取點。
	ListAccessPointsForObjectProcess	擷取使用者層級的對象FC存取點資訊。
	PutAccessPointConfigForObjectProcess	修改對象FC存取點配置。
	GetAccessPointConfigForObjectProcess	擷取對象FC存取點配置資訊。
	PutAccessPointPolicyForObjectProcess	為對象FC存取點配置權限原則。
	GetAccessPointPolicyForObjectProcess	擷取對象FC存取點的權限原則配置。
	DeleteAccessPointPolicyForObjectProcess	刪除對象FC存取點的權限原則。
	WriteGetObjectResponse	自訂返回資料和響應標題。
阻止公用訪問（BlockAccess）	PutPublicAccessBlock	為OSS全域開啟阻止公用訪問。
	GetPublicAccessBlock	擷取OSS全域阻止公用訪問的配置資訊。
	DeletePublicAccessBlock	刪除OSS全域阻止公用訪問配置資訊。
	PutBucketPublicAccessBlock	為Bucket開啟阻止公用訪問。
	GetBucketPublicAccessBlock	擷取指定Bucket的阻止公用訪問配置資訊。
	DeleteBucketPublicAccessBlock	刪除指定Bucket的阻止公用訪問配置資訊。
	PutAccessPointPublicAccessBlock	為存取點開啟阻止公用訪問。
	GetAccessPointPublicAccessBlock	擷取指定存取點的阻止公用訪問配置資訊。
	DeleteAccessPointPublicAccessBlock	刪除指定存取點的阻止公用訪問配置資訊。
歸檔直讀（ArchiveDirectRead）	PutBucketArchiveDirectRead	開啟或關閉歸檔直讀。
歸檔直讀（ArchiveDirectRead）	GetBucketArchiveDirectRead	查看是否已開啟歸檔直讀。
OSS加速器（OSS Accelerator）	PutBucketDataAccelerator	建立OSS加速器或修改其配置。
	GetBucketDataAccelerator	查詢OSS加速器資訊。
	DeleteBucketDataAccelerator	刪除OSS加速器。

關於Object的操作

分類	APi	描述
基礎操作	PutObject	上傳Object。
	GetObject	擷取Object。
	CopyObject	拷貝Object。
	AppendObject	以追加寫的方式上傳Object。
	SealAppendObject	禁止向一個Appendable Object繼續追加內容。
	DeleteObject	刪除單個Object。
	DeleteMultipleObjects	刪除多個Object。
	HeadObject	只返回某個Object的meta資訊，不返迴文件內容。
	GetObjectMeta	返回Object的基本meta資訊，包括該Object的ETag、Size（檔案大小）以及LastModified等，不返迴文件內容。
	PostObject	通過HTML表單上傳的方式上傳Object。
	Callback	您只需在發送給OSS的請求中攜帶相應的Callback參數即可實現回調。
	RestoreObject	解凍Archive Storage、冷Archive Storage或者深度冷Archive Storage類型的Object。
	CleanRestoredObject	提前結束解凍狀態。
	SelectObject	對目標檔案執行SQL語句，返回執行結果。
	CreateSelectObjectMeta	擷取目標檔案總行數、總列數（對於CSV檔案），以及Splits個數。
目錄管理	CreateDirectory	建立目錄（Directory）。
	Rename	重新命名目錄（Directory）或者檔案（Object）。
	DeleteDirectory	刪除目錄。
分區上傳（MultipartUpload）	InitiateMultipartUpload	初始化一個Multipart Upload事件。
	UploadPart	根據指定的Object名和uploadId來分塊（Part）上傳資料。
	UploadPartCopy	通過在UploadPart請求的基礎上增加一個要求標頭x-oss-copy-source來調用UploadPartCopy介面，實現從一個已存在的Object中拷貝資料來上傳一個Part。
	CompleteMultipartUpload	在將所有資料Part都上傳完成後，您必須調用CompleteMultipartUpload介面來完成整個檔案的分區上傳。
	AbortMultipartUpload	取消Multipart Upload事件並刪除對應的Part資料。
	ListMultipartUploads	列舉所有執行中的Multipart Upload事件，即已經初始化但還未完成（Complete）或者還未中止（Abort）的Multipart Upload事件。
	ListParts	列舉指定uploadId所屬的所有已經上傳成功Part。
許可權控制（ACL)	PutObjectACL	修改Object的存取權限。
許可權控制（ACL)	GetObjectACL	查看Object的存取權限。
軟連結（Symlink）	PutSymlink	建立軟連結。
軟連結（Symlink）	GetSymlink	擷取軟連結。
標籤（Tagging）	PutObjectTagging	設定或更新對象標籤。
	GetObjectTagging	擷取對象標籤資訊。
	DeleteObjectTagging	刪除指定的對象標籤。

關於向量Bucket的操作

分類	APi	描述
向量 Bucket	PutVectorBucket	建立向量 Bucket。
	GetVectorBucket	擷取向量Bucket的詳細資料。
	ListVectorBuckets	列舉當前帳號下的所有向量Bucket。
	DeleteVectorBucket	刪除向量Bucket。
索引 Index	PutVectorIndex	在向量 Bucket中建立向量索引。
	GetVectorIndex	擷取向量索引的詳細資料。
	ListVectorIndexes	列舉向量Bucket中的所有向量索引。
	DeleteVectorIndex	在將所有資料Part都上傳完成後，您必須調用CompleteMultipartUpload介面來完成整個檔案的分區上傳。
向量 Vectors	PutVectors	向索引中寫入向量資料。
	GetVectors	擷取指定的向量資料。
	ListVectors	列舉向量索引中的所有向量資料。
	DeleteVectors	刪除向量索引中的指定向量資料。
	QueryVectors	進行向量相似性檢索。

關於資源群組QoS的操作

API	描述
PutBucketQoSInfo	為資源集區內的Bucket設定流控。
GetBucketQoSInfo	擷取資源集區內某個Bucket的流控配置。
DeleteBucketQosInfo	刪除資源集區內指定Bucket的流控配置。
PutBucketRequesterQoSInfo	佈建要求者在Bucket層級的流控。
GetBucketRequesterQoSInfo	擷取指定要求者在Bucket層級的流控配置。
ListBucketRequesterQoSInfos	擷取所有要求者在Bucket層級的流控配置。
DeleteBucketRequesterQoSInfo	刪除Bucket的某個要求者流控配置。
ListResourcePools	擷取當前帳號下的所有資源集區資訊。
GetResourcePoolInfo	擷取指定資源集區流控配置。
ListResourcePoolBuckets	擷取指定資源集區包含的Bucket列表。
PutResourcePoolRequesterQoSInfo	為資源集區的要求者配置流控。
GetResourcePoolRequesterQoSInfo	擷取指定要求者在資源集區的流控配置。
ListResourcePoolRequesterQoSInfos	擷取所有要求者在資源集區的流控配置。
DeleteResourcePoolRequesterQoSInfo	刪除指定要求者在資源集區的流控配置。
PutBucketResourcePoolBucketGroup	將資源集區內的Bucket添加到BucketGroup。
ListResourcePoolBucketGroups	列舉指定資源集區的BucketGroup列表。
PutResourcePoolBucketGroupQoSInfo	配置或修改資源集區中BucketGroup的流控。
GetResourcePoolBucketGroupQoSInfo	擷取資源集區中BucketGroup的流控配置。
ListResourcePoolBucketGroupQoSInfos	列舉資源集區中BucketGroup的流控配置。
DeleteResourcePoolBucketGroupQoSInfo	刪除資源集區中BucketGroup的流控配置。

關於Live Channel的操作

API	描述
PutLiveChannelStatus	切換LiveChannel的狀態。
PutLiveChannel	建立LiveChannel。
GetVodPlaylist	擷取播放清單。
PostVodPlaylist	產生播放清單。
GetLiveChannelStat	擷取LiveChannel的推流狀態資訊。
GetLiveChannelInfo	擷取LiveChannel的配置資訊。
GetLiveChannelHistory	擷取LiveChannel的推流記錄。
ListLiveChannel	列舉LiveChannel。
DeleteLiveChannel	刪除LiveChannel。

Object Storage Service：API概覽