設定 Blob 標記

發行項
02/02/2023

作業 Set Blob Tags 會將指定 Blob 的使用者定義標籤設定為一或多個索引鍵/值組。

要求

Set Blob Tags 要求的建構如下。建議您使用 HTTPS。以儲存體帳戶的名稱取代 myaccount ：

PUT 方法要求 URI	HTTP 版本
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=tags` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=tags&versionid=<DateTime>`	HTTP/1.1

URI 參數

您可以在要求 URI 上指定下列其他參數：

參數	描述
`versionid`	2019-12-12 版和更新版本的選擇性。參數 `versionid` 是不透明 `DateTime` 值，當存在時，會指定要擷取的 Blob 版本。
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定 Blob 儲存體作業的逾時。

要求標頭

下表說明必要的和選擇性要求標頭：

要求標頭	描述
`Authorization`	必要。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的「國際標準時間」(UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	所有授權要求都需要。指定用於這個要求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`Content-Length`	必要。要求內容的長度 (以位元組為單位)。此標頭是指標記檔的內容長度，而不是 Blob 本身的內容長度。
`Content-Type`	必要。此標頭的值應該是 application/xml;charset=UTF-8。
`Content-MD5`	選擇性。要求內容的 MD5 雜湊。在傳輸期間，此雜湊可用來驗證要求內容的完整性。如果兩個雜湊不相符，作業會失敗，錯誤碼為 400 (不正確的要求) 。此標頭與要求內容相關聯，而不是與 Blob 本身的內容相關聯。
`x-ms-content-crc64`	選擇性。要求內容的 CRC64 雜湊。在傳輸期間，此雜湊可用來驗證要求內容的完整性。如果兩個雜湊不相符，作業會失敗，錯誤碼為 400 (不正確的要求) 。此標頭與要求內容相關聯，而不是與 Blob 本身的內容相關聯。如果同時 `Content-MD5` 存在和 `x-ms-content-crc64` 標頭，要求就會失敗，錯誤碼為 400 (不正確的要求) 。
`x-ms-lease-id:<ID>`	如果 Blob 具有作用中租用，則為必要項目。若要在具有作用中租用的 Blob 執行這項作業，請指定此標頭的有效租用識別碼。如果未在要求上指定有效的租用識別碼，作業會失敗，狀態碼為 403 (禁止) 。
`x-ms-client-request-id`	選擇性。提供用戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。如需詳細資訊，請參閱監視Azure Blob 儲存體。

只有在符合指定的條件時， x-ms-if-tags 此作業才支援條件標頭來設定 Blob 標記。如需詳細資訊，請參閱指定 Blob 儲存體作業的條件式標頭。

要求本文

要求主體的格式如下：

<?xml version="1.0" encoding="utf-8"?>  
<Tags>  
    <TagSet>  
        <Tag>  
            <Key>tag-name-1</Key>  
            <Value>tag-value-1</Value>  
        </Tag>  
        <Tag>  
            <Key>tag-name-2</Key>  
            <Value>tag-value-2</Value>  
        </Tag>  
    </TagSet>  
</Tags>

要求本文必須是格式正確的 UTF-8 XML 檔，並包含代表 Blob 標籤的標記集。

標籤集不能包含超過 10 個標籤。標記索引鍵和值會區分大小寫。標籤索引鍵必須介於 1 到 128 個字元之間，而標籤值必須介於 0 到 256 個字元之間。有效的標記索引鍵和值字元包括：

a-z、A-Z) (小寫和大寫字母
數位 (0-9)
空間 ( )
加 (+) 、減 () 、句點 (.) 、斜線 (/) 、冒號 (：) 、等於 (=) 和底線 (_)

回應

回應包括 HTTP 狀態碼和一組回應標頭。

狀態碼

成功的作業會傳回狀態碼 204 (沒有內容)。

如需狀態碼的詳細資訊，請參閱狀態和錯誤碼。

回應標頭

這項作業的回應包括下列標頭。回應也可能包括其他標準 HTTP 標頭。所有標準標頭都符合 HTTP/1.1 通訊協定規格。

回應標頭	描述
`x-ms-request-id`	可唯一識別已提出的要求，並可用來對要求進行疑難排解。如需詳細資訊，請參閱針對 API 作業進行疑難排解。
`x-ms-version`	用來執行要求的 Blob 儲存體版本。
`Date`	服務所產生的 UTC 日期/時間值，表示起始回應的時間。
`x-ms-client-request-id`	可用來針對要求和對應的回應進行疑難排解。如果標頭存在於要求中，此標頭的值等於標頭的值 `x-ms-client-request-id` ，且值不超過 1，024 個可見的 ASCII 字元。 `x-ms-client-request-id`如果標頭不存在於要求中，則不會出現在回應中。

回應本文

無。

授權

此作業可由帳戶擁有者以及具有共用存取簽章且具有許可權的任何人呼叫，以在 SAS 許可權) (t 設定 Blob 的標籤。

此外，角色型存取控制 (RBAC) 具有許可權的使用者 Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write 可以執行這項作業。

備註

Set Blob TagsREST API 2019-12-12 版和更新版本支援此作業。

此 Set Blob Tags 作業會覆寫 Blob 上的所有現有標記。若要從 Blob 移除所有標記，請使用空 <TagSet> 的傳送 Set Blob Tags 要求。

此作業不會更新 Blob 的 ETag 或上次修改時間。您可以在封存的 Blob 上設定標記。

儲存體服務會維護 Blob 與其標記之間的強式一致性。 Blob 標記的變更會立即顯示在 Blob 上的後續 Get Blob Tags 作業。不過，次要索引最終會一致。作業可能無法立即看到 Find Blobs by Tags Blob 標記的變更。

如果要求提供不正確標籤，Blob 儲存體會傳回狀態碼 400 (不正確的要求) 。

另請參閱

使用 Blob 索引標籤管理及尋找 Blob 儲存體資料
 授權對 Azure 儲存體的要求
 狀態和錯誤碼
 Blob 儲存體錯誤碼