列出 Blob
作業會 List Blobs
傳回指定容器下 Blob 的清單。
要求
您可以建構 List Blobs
要求,如下所示。 建議使用 HTTPS。 以記憶體帳戶的名稱取代 myaccount 。
方法 | 要求 URI | HTTP 版本 |
---|---|---|
GET |
https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list |
HTTP/1.1 |
模擬記憶體服務 URI
當您對模擬記憶體服務提出要求時,請將模擬器主機名和 Azure Blob 儲存體 埠指定為 127.0.0.1:10000
,後面接著仿真的記憶體帳戶名稱。
方法 | 要求 URI | HTTP 版本 |
---|---|---|
GET |
http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list |
HTTP/1.1 |
如需詳細資訊,請參閱 使用 Azurite 模擬器進行本機 Azure 記憶體開發。
URI 參數
您可以在 URI 上指定下列其他參數。
參數 | 描述 |
---|---|
prefix |
選擇性。 篩選結果,只傳回名稱開頭為指定前置詞的 Blob。 在具有階層命名空間的帳戶中,如果檔名出現在前置詞路徑中間,就會發生錯誤。 例如,您可能會嘗試使用前置詞路徑 folder1/folder2/readme/readmefile.txt 尋找名為 readmefile.txt 的 Blob。 如果任何子資料夾包含名為 readme 的檔案,則會出現錯誤。 |
delimiter |
選擇性。 當要求包含此參數時,作業會 BlobPrefix 傳回回應本文中的專案。 此元素可作為所有名稱開頭為相同子字串之 Blob 的佔位元,最多到分隔符的外觀。 此分隔符號可以是單一字元或字串。 |
marker |
選擇性。 識別下一個清單作業所要傳回之清單部分的字串值。 如果傳回的清單不完整,此作業會在回應主體中傳回標記值。 接著,您可以在後續呼叫中使用標記值來要求下一組清單專案。 此標記值對於用戶端為不透明。 |
maxresults |
選擇性。 指定要傳回的 Blob 數目上限,包括所有 BlobPrefix 項目。 如果要求未指定 maxresults ,或指定大於5,000的值,則伺服器最多會傳回5,000個專案。 如果傳回其他結果,服務會在響應項目中傳回接續令牌 NextMarker 。 在某些情況下,服務可能會傳回比 所 maxresults 指定少的結果,也會傳回接續令牌。若將 maxresults 設為小於或等於零的值,將會產生錯誤回應碼 400 (不正確的要求)。 |
include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions, deletedwithversions,immutabilitypolicy,legalhold,permissions} |
選擇性。 指定一個或多個包含在回應中的資料集: - snapshots :指定應該將快照集包含在列舉中。 回應中的快照集清單是從最舊排到最新。- metadata :指定在響應中傳回 Blob 元數據。- uncommittedblobs :指定已上傳區塊但尚未使用 Put Block List 認可的 Blob 包含在回應中。- copy :版本 2012-02-12 和更新版本。 指定在回應中包含的中繼資料,此資料與任何目前或先前的 Copy Blob 作業都有關聯。- deleted :版本 2017-07-29 和更新版本。 指定應該在回應中包含虛刪除的 Blob。 - tags :版本 2019-12-12 和更新版本。 指定回應中應包含使用者定義的 Blob 索引標籤。 - versions :版本 2019-12-12 和更新版本。 指定列舉中應包含 Blob 的版本。- deletedwithversions :版本 2020-10-02 和更新版本。 指定回應中應包含任何版本 (作用中或刪除) 已刪除的 Blob。 您永久刪除的專案會出現在回應中,直到垃圾收集處理它們為止。 使用標記 \<HasVersionsOnly\> 和值 true 。 - immutabilitypolicy :版本 2020-06-12 和更新版本。 指定列舉應該包含不變性原則,直到日期為止,以及 Blob 的不變性原則模式。- legalhold :版本 2020-06-12 和更新版本。 指定列舉應該包含 Blob 的法律保存。- permissions :版本 2020-06-12 和更新版本。 僅支援已啟用階層命名空間的帳戶。 如果要求包含此參數,則列出的 Blob 或目錄的擁有者、群組、許可權和訪問控制清單將會包含在列舉中。 若要在 URI 中指定上述多個選項,您必須以 URL 編碼的逗號 ("%82") 分隔每一個選項。 |
showonly={deleted,files,directories} |
選擇性。 指定要在回應中傳回的其中一個資料集: - deleted :選。 版本 2020-08-04 和更新版本。 僅適用於使用階層命名空間啟用的帳戶。 當要求包含此參數時,清單只會包含虛刪除的 Blob。 請注意,列出虛刪除的 Blob 不支援 POSIX ACL 授權後援。 如果 include=deleted 也指定 ,要求會失敗,並出現錯誤要求 (400) 。- files :選。 版本 2020-12-06 和更新版本。 僅適用於使用階層命名空間啟用的帳戶。 當要求包含此參數時,清單只會包含檔案。 - directories :選。 版本 2020-12-06 和更新版本。 僅適用於使用階層命名空間啟用的帳戶。 當要求包含此參數時,清單只會包含目錄。 |
timeout |
選擇性。 timeout 參數以秒為單位。 如需詳細資訊,請參閱 設定 Blob 記憶體作業的逾時。 |
要求標頭
下表描述必要的和選用的要求標頭。
要求標頭 | 描述 |
---|---|
Authorization |
必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊,請參閱授權對 Azure 儲存體提出要求。 |
Date 或 x-ms-date |
必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊,請參閱授權對 Azure 儲存體提出要求。 |
x-ms-version |
所有已授權要求的必要專案,以及匿名要求的選擇性要求。 指定用於這個要求的作業版本。 如需詳細資訊,請參閱 Azure 儲存體服務的版本。 |
x-ms-client-request-id |
選擇性。 提供客戶端產生的不透明值,其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。 強烈建議您使用此標頭,將用戶端活動與伺服器收到的要求相互關聯。 如需詳細資訊,請參閱監視 Azure Blob 儲存體。 |
x-ms-upn |
選擇性。 只有在啟用帳戶的階層命名空間時有效,而且 include=permissions 會在要求中提供。 如果true 為 ,則會將 [擁有者>]、<[群組>] 和 <[Acl>] 欄位中傳<回的使用者識別值從 Microsoft Entra 物件識別碼轉換成用戶主體名稱。 如果false 為 ,則會以物件標識碼的形式傳回值 Microsoft Entra。 預設值是 false 。 請注意,群組和應用程式對象標識碼不會翻譯,因為它們沒有唯一的易記名稱。 |
要求本文
無。
範例要求
如需範例要求,請參閱 列舉 Blob 資源 。
回應
回應包括 HTTP 狀態碼、一組回應標頭和 XML 格式的回應主體。
狀態碼
成功的作業會傳回狀態碼 200 (OK)。 如需狀態代碼的相關信息,請參閱 狀態和錯誤碼。
回應標頭
這項作業的回應包括下列標頭。 回應也可以包含額外的標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協議規格。
回應標頭 | 描述 |
---|---|
Content-Type |
指定傳回結果的格式。 目前此值為 application/xml 。 |
x-ms-request-id |
此標頭可唯一識別已提出的要求,並可用於對要求進行疑難解答。 如需詳細資訊,請參閱 針對 API 作業進行疑難解答。 |
x-ms-version |
指出用來執行要求的 Blob 記憶體版本。 使用 2009-09-19 版和更新版本提出的要求,會傳回此標頭。 如果使用 2009-09-19 版的 Blob 記憶體,此標頭也會針對匿名要求傳回,但未指定版本。 |
Date |
UTC 日期/時間值,指出起始響應的時間。 服務會產生此值。 |
x-ms-client-request-id |
您可以使用此標頭來針對要求和對應的回應進行疑難解答。 如果此標頭存在於要求中,這個標頭的值會等於標頭的值 x-ms-client-request-id 。 此值最多為1024個可見的ASCII字元。 x-ms-client-request-id 如果要求中沒有標頭,則此標頭不會出現在回應中。 |
回應本文
XML 回應的格式如下。
請注意,唯有在要求 URI 中指定 Prefix
、Marker
、MaxResults
和 Delimiter
項目時,這些項目才存在。 只有在清單結果未完成時,專案 NextMarker
才會有值。
唯有在要求 URI 中以 include
參數指定快照集、Blob 中繼資料和未認可的 Blob,這些項目才會包含在回應中。
在 2009-09-19 版和更新版本中,Blob 的屬性會封裝在 元素內 Properties
。
從 2009-09-19 版開始,List Blobs
會在回應主體中傳回下列重新命名的項目:
Last-Modified
(之前為LastModified
)Content-Length
(之前為Size
)Content-Type
(之前為ContentType
)Content-Encoding
(之前為ContentEncoding
)Content-Language
(之前為ContentLanguage
)
針對使用 2009-09-19 版和更新版本所建立的 Blob,會出現元素 Content-MD5
。 在 2012-02-12 版和更新版本中,Blob 記憶體會在 Content-MD5
您使用 Put Blob 上傳 Blob 時計算值。 當您使用 Put Block List 建立 Blob 時,Blob 記憶體不會計算此專案。 您可以在建立 Blob 時明確設定 Content-MD5
值,或呼叫 Put Block List 或 Set Blob Properties 作業。
針對 2009-09-19 和更新版本,但在 2015-02-21 版之前,您無法在包含附加 Blob 的容器上呼叫 List Blobs
。 如果清單的結果包含附加 Blob,服務會傳回狀態代碼 409 (Conflict) 。
LeaseState
和 LeaseDuration
只會出現在 2012-02-12 版和更新版本中。
當此作業包含 include={copy}
參數時,CopyId
、CopyStatus
、CopySource
、CopyProgress
、CopyCompletionTime
和 CopyStatusDescription
只會出現在 2012-02-12 版及更新版本中。 如果此 Blob 從未成為作業中的 Copy Blob
目的地,則不會顯示這些專案。 如果使用、 Put Blob
或 Put Block List
,在結束Copy Blob
的作業之後修改此 Blob,Set Blob Properties
則不會顯示專案。 在 2012-02-12 版之前,這些元素也不會與 複製 Blob 建立的 Blob 一起出現。
在 2013-08-15 版和更新版本中, EnumerationResults
元素包含指定 ServiceEndpoint
Blob 端點的屬性。 這個專案也包含指定 ContainerName
容器名稱的欄位。 在舊版中,這兩個屬性會在 字段中結合在一起 ContainerName
。 此外,在 2013-08-15 版和更新版本中,已移除 底下的 Url
Blob
元素。
針對 2015-02-21 版和更新版本, List Blobs
傳回所有類型的 Blob (區塊、分頁和附加 Blob) 。
針對 2015-12-11 版和更新版本, List Blobs
會傳 ServerEncrypted
回 元素。 如果 Blob 和應用程式中繼資料已完全加密,則false
這個項目會設定true
為 ,否則為 。
針對 2016-05-31 版和更新版本, List Blobs
傳回 IncrementalCopy
累加複製 Blob 和快照集的專案,並將值設定為 true
。
針對 2017-04-17 版和更新版本,如果明確設定存取層, List Blobs
則會傳回 AccessTier
元素。 如需允許的進階分頁 Blob 層清單,請參閱 VM 的高效能進階記憶體和受控磁碟。 對於 Blob 記憶體或一般用途 v2 帳戶,有效值為 Hot
、 Cool
和 Archive
。 如果 Blob 處於解除凍結擱置狀態,則會傳回元素,其中 ArchiveStatus
一個有效值 (rehydrate-pending-to-hot
、 rehydrate-pending-to-cool
或 rehydrate-pending-to-cold
) 。 如需區塊 Blob 階層處理的詳細資訊 ,請參閱經常性存取、非經常性存取和封存儲存層。
針對 2017-04-17 版和更新版本, List Blobs
傳回 AccessTierInferred
Blob 記憶體或一般用途 v2 帳戶上的 元素。 如果區塊 Blob 沒有存取層集,則會從記憶體帳戶屬性推斷階層資訊,而此值會設定為 true
。 只有在從帳戶屬性推斷階層時,才會顯示這個標頭。
針對 2017-04-17 版和更新版本, List Blobs
傳回 AccessTierChangeTime
Blob 記憶體或一般用途 v2 帳戶上的 元素。 只有在已設定區塊 Blob 上的層時,才會傳回這個值。 如需詳細資訊,請參閱 標頭中的日期時間值表示。
針對 2017-07-29 版和更新版本,Deleted
當DeletedTime
此作業包含 include={deleted}
參數時,會出現 、 和 RemainingRetentionDays
。 如果未刪除此 Blob,則不會顯示這些專案。 啟用虛刪除功能時,這些元素會出現在作業中刪除 DELETE
的 Blob 或快照集。 元素 Deleted
會針對虛刪除的 Blob 和快照集設定為 true
。 Deleted-Time
會對應至刪除 Blob 的時間。 RemainingRetentionDays
會指出永久刪除虛刪除 Blob 的天數。
針對 2017-11-09 版和更新版本, Creation-Time
傳回建立此 Blob 的時間。
針對 2019-02-02 版和更新版本,如果 Blob 是以客戶提供的密鑰加密, List Blobs
則會傳回 CustomerProvidedKeySha256
元素。 此值會設定為用來加密 Blob 之金鑰的 SHA-256 哈希。 此外,如果作業包含 include={metadata}
參數,而且有應用程式元數據存在於以客戶提供的密鑰加密的 Blob 上,專案 Metadata
會有 Encrypted="true"
屬性。 這個屬性表示 Blob 具有無法解密為作業一部分的 List Blobs
元數據。 若要存取這些 Blob 的元數據,請使用客戶提供的金鑰呼叫 取得 Blob 屬性 或 取得 Blob 元數據 。
針對 2019-02-02 版和更新版本,如果 Blob 是以加密範圍加密, List Blobs
則會傳回 EncryptionScope
元素。 此值會設定為用來加密 Blob 的加密範圍名稱。 如果作業包含 include={metadata}
參數,則 Blob 上的應用程式元數據會以透明方式解密,而且可在 Metadata
元素中使用。
針對 2019-12-12 版和更新版本,如果對象處於rehydrate pending
狀態,List Blobs
則會傳回 RehydratePriority
Blob 記憶體或一般用途 v2 帳戶上的專案。 有效值為 High
和 Standard
。
針對 2019-12-12 版和更新版本,會在帳戶上啟用版本控制時, List Blobs
傳回 VersionId
Blob 和產生的 Blob 版本的專案。
針對 2019-12-12 版和更新版本, List Blobs
傳 IsCurrentVersion
回目前 Blob 版本的 元素。 這個值設定為 true
。 此元素可讓您區分目前版本與唯讀、自動產生的版本。
針對 2019-12-12 版和更新版本, List Blobs
傳回 TagCount
具有任何標記之 Blob 的 元素。 Tags
只有當此作業包含 參數時,include={tags}
才會顯示元素。 如果 Blob 上沒有標記,這些元素就不會顯示。
針對 2019-12-12 版和更新版本, List Blobs
傳 Sealed
回附加 Blob 的 元素。 Sealed
只有在附加 Blob 已密封時,才會顯示專案。 如果附加 Blob 未密封,這些元素就不會顯示。
針對 2020-02-10 版和更新版本, List Blobs
會傳 LastAccessTime
回 專案。 元素會根據記憶體帳戶的上次存取時間追蹤原則,顯示 Blob 數據上次存取的時間。 如果記憶體帳戶沒有此原則,或原則已停用,則不會傳回元素。 如需設定帳戶上次存取時間追蹤原則的相關信息,請參閱 Blob 服務 API。 元素 LastAccessTime
不會追蹤上次存取 Blob 元數據的時間。
針對 2020-06-12 版和更新版本,當此作業包含 include={immutabilitypolicy}
參數時,List Blobs
會傳回 ImmutabilityPolicyUntilDate
和 ImmutabilityPolicyMode
元素。
針對 2020-06-12 版和更新版本,當此作業包含 include={legalhold}
參數時,List Blobs
會傳回 LegalHold
元素。
針對 2020-06-12 版和更新版本,針對已啟用階層命名空間的帳戶,List Blobs
會傳回 、 Group
Permissions
和元素Acl
Owner
。 要求必須包含 include={permissions}
參數。 請注意,元素 Acl
是檔案或目錄上所設定之存取和預設訪問控制清單的組合清單。
針對已啟用階層命名空間的帳戶,針對版本 2020-06-12 和更新版本, List Blobs
使用分隔符傳 Properties
回 元素中的 BlobPrefix
專案。 這會對應至目錄上的屬性。
針對已啟用階層命名空間的帳戶,針對版本 2020-08-04 和更新版本, List Blobs
會 DeletionId
傳回已刪除 Blob 的 元素。 DeletionId
是不帶正負號的64位標識碼。 元素可唯一識別虛刪除的路徑,以便與具有相同路徑的其他已刪除 Blob 區別。
針對已啟用階層命名空間的帳戶,針對 2020-10-02 版和更新版本, List Blobs
會 ResourceType
傳回路徑的屬性元素。 這可以是 file
或 directory
。
針對 2021-02-12 版和更新版本, List Blobs
每個 RFC 2396 的百分比編碼 () 所有 Blob
Name
或 BlobPrefix
Name
元素值。 具體來說,它會針對包含 XML (U+FFFE 或 U+FFFF) 中無效字元的值執行這項操作。 如果編碼,專案 Name
將會包含 Encoded=true
屬性。 請注意,這隻會針對 Name
XML 中含有無效字元的專案值發生,而不是回應中的其餘 Name
元素。
針對已啟用階層命名空間的帳戶,針對 2021-06-08 版和更新版本, List Blobs
會 Placeholder
傳回 properties 元素。 它會在佔位元目錄的 元素中 BlobPrefix
傳回這個專案,以分隔符列出已刪除的 Blob。 這些佔位元目錄存在,可協助流覽虛刪除的 Blob。
針對已啟用階層命名空間的帳戶,針對版本 2021-06-08 和更新版本, List Blobs
會 EncryptionContext
傳回 元素。 如果已設定加密內容屬性值,則會傳回設定的值。
針對已啟用階層命名空間的帳戶,針對 2020-02-10 版和更新版本, List Blobs
會 Expiry-Time
傳回已刪除 Blob 的 元素。 Expiry-Time
是檔案到期的時間,如果在相同時間上設定到期,則會針對檔案傳回。
<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/" ContainerName="mycontainer">
<Prefix>string-value</Prefix>
<Marker>string-value</Marker>
<MaxResults>int-value</MaxResults>
<Delimiter>string-value</Delimiter>
<Blobs>
<Blob>
<Name>blob-name</name>
<Snapshot>date-time-value</Snapshot>
<VersionId>date-time-vlue</VersionId>
<IsCurrentVersion>true</IsCurrentVersion>
<Deleted>true</Deleted>
<Properties>
<Creation-Time>date-time-value</Creation-Time>
<Last-Modified>date-time-value</Last-Modified>
<Etag>etag</Etag>
<Owner>owner user id</Owner>
<Group>owning group id</Group>
<Permissions>permission string</Permissions>
<Acl>access control list</Acl>
<ResourceType>file | directory</ResourceType>
<Placeholder>true</Placeholder>
<Content-Length>size-in-bytes</Content-Length>
<Content-Type>blob-content-type</Content-Type>
<Content-Encoding />
<Content-Language />
<Content-MD5 />
<Cache-Control />
<x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>
<BlobType>BlockBlob|PageBlob|AppendBlob</BlobType>
<AccessTier>tier</AccessTier>
<LeaseStatus>locked|unlocked</LeaseStatus>
<LeaseState>available | leased | expired | breaking | broken</LeaseState>
<LeaseDuration>infinite | fixed</LeaseDuration>
<CopyId>id</CopyId>
<CopyStatus>pending | success | aborted | failed </CopyStatus>
<CopySource>source url</CopySource>
<CopyProgress>bytes copied/bytes total</CopyProgress>
<CopyCompletionTime>datetime</CopyCompletionTime>
<CopyStatusDescription>error string</CopyStatusDescription>
<ServerEncrypted>true</ServerEncrypted>
<CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
<EncryptionContext>encryption-context<EncryptionContext>
<EncryptionScope>encryption-scope-name</EncryptionScope>
<IncrementalCopy>true</IncrementalCopy>
<AccessTierInferred>true</AccessTierInferred>
<AccessTierChangeTime>datetime</AccessTierChangeTime>
<DeletedTime>datetime</DeletedTime>
<RemainingRetentionDays>no-of-days</RemainingRetentionDays>
<TagCount>number of tags between 1 to 10</TagCount>
<RehydratePriority>rehydrate priority</RehydratePriority>
<Expiry-Time>date-time-value</Expiry-Time>
</Properties>
<Metadata>
<Name>value</Name>
</Metadata>
<Tags>
<TagSet>
<Tag>
<Key>TagName</Key>
<Value>TagValue</Value>
</Tag>
</TagSet>
</Tags>
<OrMetadata />
</Blob>
<BlobPrefix>
<Name>blob-prefix</Name>
</BlobPrefix>
</Blobs>
<NextMarker />
</EnumerationResults>
範例回應
如需範例回應 ,請參閱列舉 Blob 資源 。
授權
在 Azure 記憶體中呼叫任何數據存取作業時,需要授權。 您可以授權 List Blobs
作業,如下所述。
Azure 記憶體支援使用 Microsoft Entra ID 來授權 Blob 數據的要求。 使用 Microsoft Entra ID,您可以使用 Azure 角色型存取控制 (Azure RBAC) ,將許可權授與安全性主體。 安全性主體可能是使用者、群組、應用程式服務主體或 Azure 受控識別。 安全性主體會由 Microsoft Entra ID 進行驗證,以傳回 OAuth 2.0 令牌。 權杖接著可以用來授權對 Blob 服務的要求。
若要深入瞭解使用 Microsoft Entra ID 授權,請參閱使用 Microsoft Entra ID 授權 Blob 的存取權。
權限
以下是 Microsoft Entra 使用者、群組或服務主體呼叫List Blobs
作業所需的 RBAC 動作,以及包含此動作的最低特殊許可權內建 Azure RBAC 角色:
- Azure RBAC 宏指令:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- 最低特殊許可權的內建角色:記憶體 Blob 數據讀取器
若要深入瞭解如何使用 Azure RBAC 指派角色,請參閱 指派 Azure 角色以存取 Blob 數據。
備註
回應中的 Blob 屬性
如果您已要求將未認可的 Blob 包含在列舉中,請注意,在認可 Blob 之前,不會設定某些屬性。 某些屬性可能不會在回應中傳回。
x-ms-blob-sequence-number
項目只會針對分頁 Blob 傳回。
專案 OrMetadata
只會針對區塊 Blob 傳回。
針對分頁 Blob,在 Content-Length
項目中傳回的值會對應至 Blob 的 x-ms-blob-content-length
標頭值。
Content-MD5
只有在已使用 2009-09-19 版或更新版本在 Blob 上設定元素時,元素才會出現在回應本文中。 您可以在建立 Blob 時設定 Content-MD5
屬性,或呼叫 [設定 Blob 屬性]。 在 2012-02-12 版和更新版本中, Put Blob
即使 Put Blob
要求不包含 MD5 標頭,也會設定區塊 Blob 的 MD5 值。
回應中的元數據
只有在 URI 中指定 Metadata
參數時,include=metadata
項目才存在。 在 Metadata
項目中,每個名稱/值組的值會列於與組合名稱對應的項目內。
請注意,使用此參數要求的元數據必須根據 2009-09-19 版 Blob 記憶體所加加的命名限制來儲存。 從這個版本開始,所有元數據名稱都必須遵守 C# 識別碼的命名慣例。
如果元數據名稱/值組違反這些命名限制,回應本文會指出元素內 x-ms-invalid-name
有問題的名稱。 下列 XML 片段顯示下列內容:
…
<Metadata>
<MyMetadata1>first value</MyMetadata1>
<MyMetadata2>second value</MyMetadata2>
<x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>
</Metadata>
…
回應中的標記
Tags
只有在 include=tags
URI 上指定 參數,而且 Blob 上有標記時,才會存在元素。 在 TagSet
元素內,最多會傳回 10 Tag
個元素,每個元素都包含 key
使用者定義 Blob 索引標記的 和 value
。 回應中不保證標記的順序。
Tags
如果沒有 Blob 上的標記,則不會傳回 和 TagCount
元素。
記憶體服務會在 Blob 與其標記之間維持強式一致性,但次要索引最終會一致。 標記可以在作業看見之前Find Blobs by Tags
,在響應List Blobs
中顯示標記。
回應中的快照集
唯有在 URI 中指定 include=snapshots
參數,快照集才會在回應中列出。 回應中列出的快照集不包含 LeaseStatus
元素,因為快照集不能有作用中的租用。
使用服務版本 2021-06-08 和更新版本,您可以使用分隔符進行呼叫 List Blobs
,並在列舉中包含快照集。 針對 2021-06-08 之前的服務版本,包含兩者的要求都會傳回 InvalidQueryParameter 錯誤, (HTTP 狀態代碼 400 – 不正確的要求) 。
回應中未認可的 Blob
唯有在 URI 中指定 include=uncommittedblobs
參數,未認可的 Blob 才會在回應中列出。 回應中列出的未認可的 Blob 不包含下列任何元素:
Last-Modified
Etag
Content-Type
Content-Encoding
Content-Language
Content-MD5
Cache-Control
Metadata
回應中已刪除的 Blob
只有在 URI 上指定參數時, include=deleted
已刪除的 Blob 才會列在回應中。 回應中列出的已刪除 Blob 不包含 Lease 元素,因為已刪除的 Blob 不能有作用中的租用。
如果 include=deleted,snapshot
已在 URI 上指定,則會在清單回應中包含已刪除的快照集。
回應中的物件復寫元數據
在 OrMetadata
Blob 上評估物件複寫策略,並使用 List Blobs
2019-12-12 版或更新版本進行呼叫時,就會出現專案。 在 OrMetadata
項目中,每個名稱/值組的值會列於與組合名稱對應的項目內。 名稱的格式為 or-{policy-id}_{rule-id}
,其中 {policy-id}
是 GUID,代表記憶體帳戶上的物件復寫原則識別碼。 {rule-id}
是 GUID,表示記憶體容器上的規則識別碼。 有效值為 complete
或 failed
。
…
<OrMetadata>
<or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>
<or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>
</OrMetadata>
…
回應中的不變性原則
ImmutabilityPolicyUntilDate
只有在 URI 上指定 參數時include=immutabilitypolicy
,才會存在 和 ImmutabilityPolicyMode
元素。
<Properties>
<ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>
<ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>
</Properties>
回應中的法律保留
只有在 URI 中指定 LegalHold
參數時,include=legalhold
項目才存在。
<Properties>
<LegalHold>true | false </LegalHold>
</Properties>
使用標記值傳回結果集
如果您為 maxresults
參數指定值,而要傳回的 Blob 數目超過此值,或超過的 maxresults
預設值,則回應本文會 NextMarker
包含 元素。 這個專案表示下一個 Blob,以在後續要求上傳回。 在某些情況下,即使傳回的結果數目小於 的值maxresults
,服務還是可能會傳回 NextMarker
專案。
若要傳回下一組項目,請指定 NextMarker
的值做為 URI 中的標記參數,以進行後續要求。 請注意,NextMarker
的值應視為不透明。
使用分隔符周遊 Blob 命名空間
delimiter
參數可讓呼叫者藉由使用者設定的分隔符號周遊 Blob 命名空間。 如此一來,您便可以周遊 Blob 的虛擬階層,就像是檔案系統一般。 此分隔符號可以是單一字元或字串。
當要求包含此參數時,作業會傳回 BlobPrefix
項目。 項目 BlobPrefix
會傳回,取代名稱開頭為相同子字串的所有 Blob,最多到分隔符的外觀。 元素的值 BlobPrefix
是 substring+分隔符,其中 子字串 是開始一或多個 Blob 名稱的通用子字串,而 分隔符 則是 參數的值 delimiter
。
您可以使用 的值 BlobPrefix
進行後續呼叫,以列出開頭為這個前置詞的 Blob。 若要這樣做,請在要求 URI 上指定 參數的值BlobPrefix
prefix
。
請注意,每個傳回的 BlobPrefix
項目會計入最大結果數目,就像每個 Blob
項目一樣。
Blob 會按照字母順序在回應主體中列出,大寫字母先列出。
複製狀態描述中的複製錯誤
CopyStatusDescription
包含 Copy Blob
失敗的詳細資訊。
當複製嘗試失敗時,如果 Blob 記憶體仍在重試作業,
CopyStatus
則會設定pending
為 。 文字CopyStatusDescription
描述上次複製嘗試期間可能發生的失敗。當
CopyStatus
設為failed
時,CopyStatusDescription
文字會描述導致複製作業失敗的錯誤。
下表描述每個 CopyStatusDescription
值的欄位。
元件 | Description |
---|---|
HTTP 狀態碼 | 指定失敗的標準三位數整數。 |
錯誤碼 | 描述錯誤的關鍵詞。 它是由 ErrorCode> 元素中的 <Azure 所提供。 <如果沒有出現 ErrorCode> 元素,服務會傳回關鍵詞,其中包含與 HTTP 規格中三位數 HTTP 狀態代碼相關聯的標準錯誤文字。 如需詳細資訊,請參閱常見 REST API 錯誤碼。 |
資訊 | 失敗的詳細描述,以引弧括住。 |
下表說明常見失敗案例的 CopyStatus
和 CopyStatusDescription
值。
重要
此處顯示的描述文字可以變更而不發出警告,即使沒有版本變更也是如此。 請勿依賴比對這個確切文字。
案例 | 複製狀態值 | 複製狀態描述值 |
---|---|---|
複製作業已順利完成。 | 成功 | empty |
使用者已在複製作業完成之前中止。 | aborted | empty |
在複製作業期間從來源 Blob 讀取時發生失敗。 將會重試作業。 | 暫止 | 502 BadGateway「讀取來源時,發生可重試的錯誤。 將重試。 失敗時間: <時間>」 |
寫入複製作業的目的地 Blob 時發生失敗。 將會重試作業。 | 暫止 | 500 InternalServerError「發生可重試的錯誤。 將重試。 失敗時間: <時間>」 |
從複製作業的來源 Blob 在讀取時,發生無法復原的失敗。 | 失敗 | 404 ResourceNotFound「讀取來源時複製失敗」。當服務報告此基礎錯誤時,它會在 ErrorCode> 元素中<傳回ResourceNotFound 。 如果回應中沒有 <出現 ErrorCode> 元素,則會出現 HTTP 狀態的標準字串表示法,例如 NotFound 。 |
限制所有複製作業的逾時期限已過。 (目前逾時期間為兩周。) | 失敗 | 500 OperationCancelled「複製超過允許的最長時間。」 |
從來源讀取時,複製作業的失敗次數過於頻繁,且未達到嘗試成功的最低比率。 (此逾時可防止在失敗) 前兩周重試非常差的來源。 | 失敗 | 500 OperationCancelled「讀取來源時,複製失敗。」 |
計費
定價要求可能源自使用 Blob 記憶體 API 的用戶端,無論是直接透過 Blob 記憶體 REST API,還是來自 Azure 記憶體用戶端連結庫。 這些要求會累算每個交易的費用。 交易類型會影響帳戶的收費方式。 例如,讀取交易會累算到與寫入交易不同的計費類別。 下表顯示根據記憶體帳戶類型的要求計費類別 List Blobs
:
作業 | 儲存體帳戶類型 | 計費類別 |
---|---|---|
列出 Blob | 進階區塊 Blob 標準一般用途 v2 標準一般用途 v1 |
列出和建立容器作業 |
若要瞭解指定計費類別的定價,請參閱 Azure Blob 儲存體 定價。