設定佇列服務屬性

發行項
08/05/2023

作業 Set Queue Service Properties 會設定儲存體帳戶佇列服務端點的屬性，包括儲存體分析和跨原始來源資源分享的屬性， (CORS) 規則。如需 CORS 規則的詳細資訊，請參閱儲存體服務的 CORS 支援。

要求

您可以指定 Set Queue Service Properties 要求，如下所示。建議您使用 HTTPS。以儲存體帳戶的名稱取代 account-name ：

方法	要求 URI	HTTP 版本
PUT	`https://account-name.queue.core.windows.net/?restype=service&comp=properties`	HTTP/1.1

注意

URI 必須一律包含斜線字元 (/) ，以分隔主機名稱與 URI 的路徑和查詢部分。在此作業中，URI 的路徑部分是空的。

URI 參數

參數	描述
`restype=service&comp=properties`	必要。需要這兩個查詢字串的組合，才能設定 Azure 儲存體服務屬性。
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定佇列服務作業的逾時。

要求標頭

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

要求標頭	描述
`Authorization`	必要。指定授權配置、儲存體帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的「國際標準時間」(UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	所有授權要求都需要。指定用於這個要求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`x-ms-client-request-id`	選擇性。提供用戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。如需詳細資訊，請參閱監視 Azure 佇列儲存體。

要求本文

2012-02-12 版及更早版本要求主體的格式如下：

<?xml version="1.0" encoding="utf-8"?>  
<StorageServiceProperties>  
    <Logging>  
        <Version>version-number</Version>  
        <Delete>true|false</Delete>  
        <Read>true|false</Read>  
        <Write>true|false</Write>  
        <RetentionPolicy>  
            <Enabled>true|false</Enabled>  
            <Days>number-of-days</Days>  
        </RetentionPolicy>  
    </Logging>  
    <Metrics>  
        <Version>version-number</Version>  
        <Enabled>true|false</Enabled>  
        <IncludeAPIs>true|false</IncludeAPIs>  
        <RetentionPolicy>  
            <Enabled>true|false</Enabled>  
            <Days>number-of-days</Days>  
        </RetentionPolicy>  
    </Metrics>  
</StorageServiceProperties>

2013-08-15 版及更新版本要求主體的格式如下：

<?xml version="1.0" encoding="utf-8"?>  
<StorageServiceProperties>  
    <Logging>  
        <Version>version-number</Version>  
        <Delete>true|false</Delete>  
        <Read>true|false</Read>  
        <Write>true|false</Write>  
        <RetentionPolicy>  
            <Enabled>true|false</Enabled>  
            <Days>number-of-days</Days>  
        </RetentionPolicy>  
    </Logging>  
    <HourMetrics>  
        <Version>version-number</Version>  
        <Enabled>true|false</Enabled>  
        <IncludeAPIs>true|false</IncludeAPIs>  
        <RetentionPolicy>  
            <Enabled>true|false</Enabled>  
            <Days>number-of-days</Days>  
        </RetentionPolicy>  
    </HourMetrics>  
    <MinuteMetrics>  
        <Version>version-number</Version>  
        <Enabled>true|false</Enabled>  
        <IncludeAPIs>true|false</IncludeAPIs>  
        <RetentionPolicy>  
            <Enabled>true|false</Enabled>  
            <Days>number-of-days</Days>  
        </RetentionPolicy>  
    </MinuteMetrics>  
    <Cors>  
        <CorsRule>  
            <AllowedOrigins>comma-separated-list-of-allowed-origins</AllowedOrigins>  
            <AllowedMethods>comma-separated-list-of-HTTP-verb</AllowedMethods>  
            <MaxAgeInSeconds>max-caching-age-in-seconds</MaxAgeInSeconds>  
            <ExposedHeaders>comma-seperated-list-of-response-headers</ExposedHeaders>  
            <AllowedHeaders> comma-seperated-list-of-request-headers </AllowedHeaders>  
        </CorsRule>  
    </Cors>  
</StorageServiceProperties>

自 2013-08-15 版起，您可以使用要求本文中指定的一或多個根項目呼叫 Set Queue Service Properties 。根元素包括：

Logging
HourMetrics
MinuteMetrics
Cors

不再需要在要求上指定每個根項目。如果省略根元素，將會保留服務該項功能現有的設定。不過，如果您確實指定指定的根項目，則必須指定該元素的每個子專案。

下表說明要求本文的元素：

元素名稱	Description
Logging	選擇性自 2013-08-15 版起。較舊的版本則為必要項。將儲存體分析記錄設定分組。
計量	2012-02-12 版及更早版本為必要項。不適用於 2013-08-15 版和更新版本。將儲存體分析計量設定分組。 Metrics 設定提供依應用程式開發介面分組，對佇列進行每小時彙總的要求統計資料摘要。
HourMetrics	2013-08-15 版和更新版本的選擇性。不適用於舊版。將儲存體分析HourMetrics設定分組。 HourMetrics 設定提供依應用程式開發介面分組，對佇列進行每小時彙總的要求統計資料摘要。
MinuteMetrics	2013-08-15 版和更新版本的選擇性。不適用於舊版。將儲存體分析MinuteMetrics設定分組。 MinuteMetrics 設定提供佇列每一分鐘的要求統計資料。對於 2013-08-15 之前的版本， MinuteMetrics 不會包含在回應本文中。
版本	如果指定了記錄、計量、 HourMetrics或 MinuteMetrics 設定，則為必要專案。要設定的儲存體分析版本。
刪除	如果指定了記錄、計量、 HourMetrics或 MinuteMetrics 設定，則為必要專案。只適用於記錄組態。指出是否需記錄所有刪除要求。
讀取	如果指定了記錄、計量、 HourMetrics或 MinuteMetrics 設定，則為必要專案。只適用於記錄組態。指出是否應該需記錄所有讀取要求。
寫入	如果指定了記錄、計量、 HourMetrics或 MinuteMetrics 設定，則為必要專案。只適用於記錄組態。指出是否需記錄所有寫入要求。
Enabled	必要。指出佇列服務是否已啟用度量。如果啟用了讀取權限的地理備援複寫，將會一併收集主要和次要度量。如果未啟用讀取權限異地備援複寫，則只會收集主要計量。
IncludeAPIs	唯有啟用度量時方為必要項。只適用於度量組態。指出度量是否應該產生所呼叫之應用程式開發介面作業的摘要統計資料。
RetentionPolicy/Enabled	必要。指出是否已啟用儲存體服務的保留原則。
RetentionPolicy/Days	只有在啟用保留原則時才需要。表示應該保留度量或記錄資料的天數。所有早于此值的資料都會遭到刪除。您可以指定的最小值是 `1` ，而最大值 (`365` 一年) 。
Cors	選擇性。 2013-08-15 版和更新版本支援 Cors 元素。將所有 CORS 規則分組。省略此元素群組並不會覆寫現有的 CORS 設定。
CorsRule	選擇性。指定佇列服務的 CORS 規則。您可以在要求中包含最多五個 CorsRule 元素。如果要求本文中未包含 CorsRule 元素，則會刪除所有 CORS 規則，並且會停用佇列服務的 CORS。
AllowedOrigins	如果 CorsRule 元素存在，則為必要專案。透過 CORS 所允許的原始網域以逗號分隔的清單，或 "*" 表示允許所有網域。原始網域也可能在子域中包含萬用字元，以允許透過 CORS 要求網域的所有子域。限制為 64 個原始網域。每個允許的原始網域最多可以有 256 個字元。
ExposedHeaders	如果 CorsRule 元素存在，則為必要專案。向 CORS 用戶端公開的回應標頭以逗號分隔的清單。限制為 64 個定義的標頭和兩個帶有前置詞的標頭。每個標頭最多可以包含 256 個字元。
MaxAgeInSeconds	如果 CorsRule 元素存在，則為必要專案。用戶端/瀏覽器應該快取預檢回應的秒數。
AllowedHeaders	如果 CorsRule 元素存在，則為必要專案。允許併入跨原始要求的標頭以逗號分隔的清單。限制為 64 個定義的標頭和 2 個帶有前置詞的標頭。每個標頭最多可以包含 256 個字元。
AllowedMethods	如果 CorsRule 元素存在，則為必要專案。允許由原始網域執行的 HTTP 方法以逗號分隔的清單。針對 Azure 儲存體，允許的方法為 `DELETE` 、 `GET` 、 `HEAD` 、 `MERGE` 、 `POST` 、 `OPTIONS` 或 `PUT` 。

回應

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

狀態碼

成功的作業會傳回狀態碼「202 (已接受)」。

回應標頭

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

回應標頭	描述
`x-ms-request-id`	唯一識別對服務提出的要求。
`x-ms-version`	指定用於回應的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`x-ms-client-request-id`	可用來針對要求和對應的回應進行疑難排解。如果此標頭存在於要求中，且值包含不超過 1，024 個可見的 ASCII 字元，則此標頭的值等於標頭的值 `x-ms-client-request-id` 。 `x-ms-client-request-id`如果要求中沒有標頭，它就不會出現在回應中。

回應本文

無。

授權

只有帳戶擁有者可呼叫這項作業。

備註

下列限制事項適用於 Azure 儲存體的 CORS 規則：

最多可儲存五個規則。
要求上所有 CORS 規則設定的大小上限，不包括 XML 標籤，不應超過 2 KiB。
允許的標頭、公開的標頭或允許的原始網域的長度不可超過 256 個字元。
允許的標頭和公開的標頭可以是下列其中一項：
- 常值標頭，即提供確切的標頭名稱，例如 x-ms-meta-processed。最多可在要求上指定 64 個常值標頭。
- 帶有前置詞的標頭，即提供標頭的前置詞，例如 x-ms-meta-data*。以這種方式指定前置詞可允許或公開開頭為指定前置詞的任何標頭。最多可在要求上指定兩個有前置詞的標頭。
在元素中指定的 AllowedMethods 方法 (或 HTTP 動詞命令) ，必須符合 Azure 儲存體服務 API 所支援的方法。支援的方法包括 DELETE 、 GET 、 HEAD 、 MERGEPOST 、、 OPTIONS 和 PUT 。

在要求上指定 CORS 規則是選擇性的作法。如果您在要求本文中未指定Cors元素的情況下呼叫 Set Queue Service Properties ，則會維護任何現有的 CORS 規則。

若要停用 CORS，請使用 Set Queue Service Properties 空白 CORS 規則設定 (呼叫，也就是* </Cors>) ，且沒有內部 CORS 規則。此呼叫會刪除任何現有的規則，並停用佇列服務的 CORS。

如果指定 CorsRule 元素，則需要所有 CORS 規則元素。如果遺漏任何元素，要求會失敗，錯誤碼為 400 (Bad Request) 。

自 2013-08-15 版起，XML 設定元素是選擇性的，因此您可以傳送只包含已更新專案的 XML 來更新特定元素。其他設定不會受到影響。

如需 CORS 規則和評估邏輯的詳細資訊，請參閱 Azure 儲存體服務的 CORS 支援。

範例要求與回應

下列範例 URI 會提出要求，以變更名為 myaccount的虛構儲存體帳戶佇列服務屬性：

PUT https://myaccount.queue.core.windows.net/?restype=service&comp=properties HTTP/1.1

所傳送的要求包含下列標頭：

x-ms-version: 2013-08-15  
x-ms-date: Wed, 23 Oct 2013 04:28:19 GMT  
Authorization: SharedKey  
myaccount:Z1lTLDwtq5o1UYQluucdsXk6/iB7YxEu0m6VofAEkUE=  
Host: myaccount.queue.core.windows.net

所傳送的要求包含下列 XML 主體：

<?xml version="1.0" encoding="utf-8"?>  
<StorageServiceProperties>  
    <Logging>  
        <Version>1.0</Version>  
        <Delete>true</Delete>  
        <Read>false</Read>  
        <Write>true</Write>  
        <RetentionPolicy>  
            <Enabled>true</Enabled>  
            <Days>7</Days>  
        </RetentionPolicy>  
    </Logging>  
    <HourMetrics>  
        <Version>1.0</Version>  
        <Enabled>true</Enabled>  
        <IncludeAPIs>false</IncludeAPIs>  
        <RetentionPolicy>  
            <Enabled>true</Enabled>  
            <Days>7</Days>  
        </RetentionPolicy>  
    </HourMetrics>  
    <MinuteMetrics>  
        <Version>version-number</Version>  
        <Enabled>true|false</Enabled>  
        <IncludeAPIs>true|false</IncludeAPIs>  
        <RetentionPolicy>  
            <Enabled>true|false</Enabled>  
            <Days>number-of-days</Days>  
        </RetentionPolicy>  
    </MinuteMetrics>  
    <Cors>  
        <CorsRule>  
            <AllowedOrigins> http://www.fabrikam.com,http://www.contoso.com</AllowedOrigins>  
            <AllowedMethods>GET,PUT</AllowedMethods>  
            <MaxAgeInSeconds>500</MaxAgeInSeconds>  
            <ExposedHeaders>x-ms-meta-data*,x-ms-meta-customheader</ExposedHeaders>  
            <AllowedHeaders>x-ms-meta-target*,x-ms-meta-customheader</AllowedHeaders>  
        </CorsRule>  
    </Cors>  
</StorageServiceProperties>

傳送要求之後，會傳回下列回應：

HTTP/1.1 202 Accepted  
Connection: Keep-Alive  
Transfer-Encoding: chunked  
Date: Wed, 23 Oct 2013 04:28:20 GMT  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cb939a31-0cc6-49bb-9fe5-3327691f2a30  
x-ms-version: 2013-08-15

另請參閱

Azure 儲存體服務的 CORS 支援
 CORS HTTP 規格