指定 Blob 服務作業的條件式標頭

有幾項 Blob 服務作業支援使用條件式標頭。 您可以指定條件式標頭,在符合指定條件的情況下執行作業。

Blob 服務會遵循適用于條件式標頭的 HTTP/1.1 通訊協定規格

支援的條件式標頭

下表說明支援的條件式標頭。

條件式標頭 描述
If-Modified-Since DateTime 值。 只有資源在指定的時間後修改,才能指定此標準執行作業。
If-Unmodified-Since DateTime 值。 只有資源沒有在指定的日期/時間後修改,才能指定此標頭執行作業。
If-Match ETag 值。 只有資源的 ETag 與指定的值相符,才能指定此標頭執行作業。 若為 2011-08-18 版及更新版本,指定的 ETag 會加上引號。
If-None-Match ETag 值,或萬用字元 (*)。 只有資源的 ETag 與指定的值不相符,才能指定此標頭執行作業。 若為 2011-08-18 版及更新版本,指定的 ETag 會加上引號。

指定萬用字元 *) (只有在資源不存在時才會執行作業,並在作業存在時讓作業失敗。

在 2013-08-15 版或更新版中指定 Blob 服務讀取作業的條件式標頭

從2013-08-15 版開始,「 取得 blob 」和「 取得 blob 屬性 」作業支援多個條件式標頭。 您可以指定支援之條件式標頭的任何組合。 Blob 服務會根據下列運算式評估這些條件:

If-Match && If-Unmodified-Since && (If-None-Match || If-Modified-Since)

您也可以為 If-MatchIf-None-Match 提供多個逗號分隔值。 如果您為 If-Match 指定多個值,則 Blob 服務會在評估整個運算式之前,先對所有提供的值執行邏輯 OR 作業。 如果您為 if-None-Match 指定多個值,則服務會在評估整個運算式之前,先執行邏輯 AND 作業。 不支援為 If-Modified-SinceIf-Unmodified-Since 指定多個值,且會產生錯誤碼 400 (Bad Request)。

這項功能已啟用,以符合HTTP/1.1 規格,並符合內容傳遞網路 (CDN) 或 proxy 伺服器將其他條件式標頭新增至傳遞要求的情況。 以下為一些條件式標頭的不同組合範例。

範例 1:

請考慮包含和標頭的 Get Blob 要求 If-Match If-Modified-Since 。 下表指出個別評估標頭的結果,以及利用組合評估標頭的結果。

條件式標頭 個別評估的結果 利用組合評估的結果
If-Match 412 (先決條件失敗) 412 (先決條件失敗)
If-Modified-Since 200 (確定) 412 (先決條件失敗)
If-Match 412 (先決條件失敗) 412 (先決條件失敗)
If-Modified-Since 304 (未修改) 412 (先決條件失敗)
If-Match 200 (確定) 200 (確定)
If-Modified-Since 200 (確定) 200 (確定)
If-Match 200 (確定) 304 (未修改)
If-Modified-Since 304 (未修改) 304 (未修改)

範例 2:

請考慮包含 If-None-MatchIf-Modified-Since 標頭的要求。

條件式標頭 個別評估的結果 利用組合評估的結果
If-None-Match 304 (未修改) 200 (確定)
If-Modified-Since 200 (確定) 200 (確定)
If-None-Match 200 (確定) 200 (確定)
If-Modified-Since 200 (確定) 200 (確定)
If-None-Match 200 (確定) 200 (確定)
If-Modified-Since 304 (未修改) 200 (確定)
If-None-Match 304 (未修改) 304 (未修改)
If-Modified-Since 304 (未修改) 304 (未修改)

範例3:

請考慮包含 If-Modified-SinceIf-MatchIf-Unmodified-Since 標頭的要求。

條件式標頭 個別評估的結果 利用組合評估的結果
If-Modified-Since 200 (確定) 412 (先決條件失敗)
If-Match 412 (先決條件失敗) 412 (先決條件失敗)
If-Unmodified-Since 200 (確定) 412 (先決條件失敗)
If-Modified-Since 200 (確定) 412 (先決條件失敗)
If-Match 200 (確定) 412 (先決條件失敗)
If-Unmodified-Since 412 (先決條件失敗) 412 (先決條件失敗)
If-Modified-Since 304 (未修改) 412 (先決條件失敗)
If-Match 200 (確定) 412 (先決條件失敗)
If-Unmodified-Since 412 (先決條件失敗) 412 (先決條件失敗)
If-Modified-Since 304 (未修改) 304 (未修改)
If-Match 200 (確定) 304 (未修改)
If-Unmodified-Since 200 (確定) 304 (未修改)

範例4:

請考慮包含 If-Modified-SinceIf-None-MatchIf-Unmodified-SinceIf-Match 標頭的要求。

合併 個別 HTTP 狀態碼 取得 Blob 狀態結果
If-Modified-Since 200 (確定) 200 (確定)
If-None-Match 200 (確定) 200 (確定)
If-Unmodified-Since 200 (確定) 200 (確定)
If-Match 200 (確定) 200 (確定)
If-Modified-Since 200 (確定) 412 (先決條件失敗)
If-None-Match 304 (未修改) 412 (先決條件失敗)
If-Unmodified-Since 412 (先決條件失敗) 412 (先決條件失敗)
If-Match 200 (確定) 412 (先決條件失敗)
If-Modified-Since 200 (確定) 200 (確定)
If-None-Match 304 (未修改) 200 (確定)
If-Unmodified-Since 200 (確定) 200 (確定)
If-Match 200 (確定) 200 (確定)
If-Modified-Since 304 (未修改) 412 (先決條件失敗)
If-None-Match 200 (確定) 412 (先決條件失敗)
If-Unmodified-Since 200 (確定) 412 (先決條件失敗)
If-Match 412 (先決條件失敗) 412 (先決條件失敗)
If-Modified-Since 304 (未修改) 412 (先決條件失敗)
If-None-Match 200 (確定) 412 (先決條件失敗)
If-Unmodified-Since 412 (先決條件失敗) 412 (先決條件失敗)
If-Match 412 (先決條件失敗) 412 (先決條件失敗)
If-Modified-Since 304 (未修改) 200 (確定)
If-None-Match 200 (確定) 200 (確定)
If-Unmodified-Since 200 (確定) 200 (確定)
If-Match 200 (確定) 200 (確定)
If-Modified-Since 304 (未修改) 412 (先決條件失敗)
If-None-Match 304 (未修改) 412 (先決條件失敗)
If-Unmodified-Since 412 (先決條件失敗) 412 (先決條件失敗)
If-Match 200 (確定) 412 (先決條件失敗)

在 2013-08-15 版之前的版本中指定讀取作業的條件式標頭,以及指定寫入作業的條件式標頭 (所有版本)

呼叫 Blob 服務讀取作業時 (取得 blob ,並取得與2013-08-15 之前的版本) 的 blob 屬性 ,以及在呼叫任何寫入作業(不論版本為何)時,請記住下列事項:

  • 如果要求同時指定 If-None-MatchIf-Modified-Since 標頭,則會根據 If-None-Match 中所指定的準則來評估要求。

  • 如果要求同時指定 If-MatchIf-Unmodified-Since 標頭,則會根據 If-Match 中所指定的準則來評估要求。

  • 除了上述兩個條件式標頭組合之外,一個要求只能指定一個條件式標頭。 指定多個條件式標頭會導致狀態碼 400 (Bad Request)。

  • 如果回應包含 ETag,請先驗證要求和回應的版本,再處理 ETag。 例如,2011-08-18 版及更新版會傳回加上引號的 ETag,而舊版則不會。 請確定您的應用程式可以處理兩種 ETag 格式,再進行評估。

  • RFC 2616 允許單一標頭中有多個 etag 值,但是對 Blob 服務的要求只能包含一個 ETag 值。 指定多個 ETag 值會導致狀態碼 400 (Bad Request)。

支援條件式標頭的作業

下表說明支援條件式標頭的作業。

REST 作業 作業類型 支援的條件式標頭
附加區塊

(2015-02-21 版和更新版本)
寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
從 URL 附加區塊

(2018-11-09 版和更新版本)
寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
複製 Blob 讀取和寫入 目的地 Blob 的條件:

- 若為-已修改-自

- 如果-未修改-自

- If-match

- If-None-Match

- x------標記

來源 Blob 的條件:

- x-毫秒-已修改-自

- x-毫秒-未經修改-自

- x-毫秒-相符

- x-毫秒-不符合

- x------------標記
刪除 Blob 寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
刪除容器 寫入 If-Modified-Since

If-Unmodified-Since
取得 Blob 讀取 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
取得 Blob 中繼資料 讀取 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
Get Blob Properties 讀取 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
取得 Blob 標記

(2019-12-12 版和更新版本)
讀取 x------標記
取得區塊清單 讀取 x------標記
機器翻譯 讀取 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
租用 Blob 寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
租用容器 寫入 If-Modified-Since

If-Unmodified-Since
從 URL 放置 Blob 寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

來源 Blob 的條件:

- x-毫秒-已修改-自

- x-毫秒-未經修改-自

- x-毫秒-相符

- x-毫秒-不符合

放置 Blob 寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
從 URL 放置區塊

(2018-03-28 版和更新版本)
寫入 x-毫秒-已修改-自

x-毫秒-未經修改-自

x-毫秒-相符

x-毫秒-不符合
放置區塊清單 寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
放置頁面 寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
從 URL 放置頁面

(2018-11-09 版和更新版本)
寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
設定 Blob 中繼資料 寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
設定 Blob 屬性 寫入 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
Set Container ACL (設定容器 ACL) 寫入 If-Modified-Since

If-Unmodified-Since
設定容器中繼資料 寫入 If-Modified-Since
設定 Blob 標記

(2019-12-12 版和更新版本)
寫入 x------標記
Set Blob Tier 讀取或寫入 x------標記
快照 Blob 讀取 If-Modified-Since

If-Unmodified-Since

If-match

If-None-Match

x------標記
設定 Blob 永久性原則 寫入 If-Unmodified-Since

下面 Blob 服務資料作業目前不支援條件式標頭:

支援條件式標頭之作業的 HTTP 回應碼

如果要求包含條件式標頭,但要求的資源與指定的條件不相符,則 Blob 服務會傳回 HTTP 回應碼。 傳回的回應碼符合 HTTP/1.1 通訊協定規格 (RFC 2616)。

Azure .NET 用戶端程式庫中的方法會將這些錯誤回應碼轉換成 StorageException 物件。

讀取作業

下表指出當做業為讀取作業時,未符合每個條件式標頭的條件所傳回的回應碼。 讀取作業使用動詞命令 GET 或 HEAD。

條件式標頭 未符合條件時的回應碼
If-Modified-Since 未修改 (304 (未修改))
If-Unmodified-Since 先決條件失敗 (412 (先決條件失敗))
If-Match 先決條件失敗 (412 (先決條件失敗))
If-None-Match 未修改 (304 (未修改))

透過 2013-08-15 版或更新版使用多個標頭時,請參考上述範例以獲得結果。

寫入作業

下表指出當做業為寫入作業時,未符合每個條件式標頭的條件所傳回的回應碼。 寫入作業使用動詞命令 PUT 或 DELETE。

條件式標頭 未符合條件時的回應碼
If-Modified-Since 先決條件失敗 (412 (先決條件失敗))
If-Unmodified-Since 先決條件失敗 (412 (先決條件失敗))
If-Match 先決條件失敗 (412 (先決條件失敗))
If-None-Match 先決條件失敗 (412 (先決條件失敗))

複製作業

下表指出當做業為複製作業時,未符合每個條件式標頭的條件所傳回的回應碼。 複製 Blob作業會使用動詞命令 PUT。

條件式標頭 未符合條件時的回應碼
If-Modified-Since 先決條件失敗 (412 (先決條件失敗))
If-Unmodified-Since 先決條件失敗 (412 (先決條件失敗))
If-Match 先決條件失敗 (412 (先決條件失敗))
If-None-Match 先決條件失敗 (412 (先決條件失敗))
x-ms-source-if-modified-since 先決條件失敗 (412 (先決條件失敗))
x-ms-source-if-unmodified-since 先決條件失敗 (412 (先決條件失敗))
x-ms-source-if-match 先決條件失敗 (412 (先決條件失敗))
x-ms-source-if-none-match 先決條件失敗 (412 (先決條件失敗))

標記條件式作業

除了 Blob 服務所支援的標準 HTTP 條件式標頭之外,數種作業也支援對 blob 資源上的標記條件。

條件式標頭 描述
x-ms-if-tags 2019-12-12 版和更新版本。 TagsPredicate 值。 只有當述詞 true 針對 blob 的標記評估為時,才能指定此標頭執行作業。
x-ms-source-if-tags 2019-12-12 版和更新版本。 僅適用于複製 Blob。 TagsPredicate 值。 只有當述詞 true 針對來源 blob 的標記評估為時,才指定此標頭執行作業。

如果 x-ms-if-tags x-ms-source-if-tags 要求中有或條件式標頭,且 TagsPredicate 評估為 false ,則 Blob 服務會傳回錯誤碼 412 (作業的先決條件失敗) 。

呼叫端必須具有讀取 blob 上標記的許可權,才能使用 x-ms-if-tags 或條件式 x-ms-source-if-tags 標頭。

標記述詞語法

Blob 服務支援 ANSI SQL WHERE 子句文法的子集,其中的 TagsPredicate 標頭值為。 支援下列運算子:

運算子 描述 範例
= 等於 Status = 'In Progress'
<> 不等於 Status <> 'Done'
> 大於 LastModified > '2018-06-18 20:51:26Z'
>= 大於或等於 Priority >= '05'
< 小於 Age < '032'
<= 小於或等於 Reviewer <= 'Smith'
AND 邏輯 and Name > 'C' AND Name < 'D'
Age > '032' AND Age < '100'
OR 邏輯 or Status = 'Done' or LastModified > '2018-06-18 20:51:26Z'

所有標記值都是字串,而支援的二進位關聯式運算子會使用標記值的詞典編纂排序。 若要支援非字串資料類型(包括數位和日期),則必須採用適當的填補和可排序格式。 標記值必須以單引號括住。

如果標記名稱是標準 SQL 識別碼,它們可能不會進行任何轉義;如果它們包含任何特殊字元,則必須使用雙引號來分隔 (例如 "TagName" = ' TagValue ' ) 。

運算式可能包含多個標記名稱和值的比較。 括弧 (()) 可用來將邏輯運算式分組,並控制標準的運算順序。 TagsPredicate最多可以包含10個 (10) 的邏輯作業。

儲存體服務會拒絕任何包含無效運算式的要求,錯誤碼為 400 (錯誤的要求) 。

另請參閱

Blob 服務概念