你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

设置队列服务属性

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 存储的请求
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权对 Azure 存储的请求
x-ms-version 对于所有已授权的请求是必需的。 指定用于此请求的操作的版本。 有关详细信息,请参阅 Azure 存储服务的版本控制
x-ms-client-request-id 可选。 提供客户端生成的不透明值,其中包含 1-kibite (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 。 根元素包括:

  • 日志记录
  • HourMetrics
  • MinuteMetrics
  • Cors

不再需要在请求中指定每个根元素。 如果忽略某个根元素,则将保留针对该功能的服务现有设置。 但是,如果指定了指定的根元素,则必须为该元素指定每个子元素。

下表描述了请求正文的元素:

元素名称 说明
日志记录 自版本 2013-08-15 起可选。 对于早期版本是必需的。 对存储分析日志记录设置进行分组。
度量值 对 2012-02-12 版和更早版本是必需的。 不适用于版本 2013-08-15 及更高版本。 对存储分析指标设置进行分组。 Metrics 设置汇总了队列的每小时聚合中按 API 分组的请求统计信息。
HourMetrics 对于版本 2013-08-15 及更高版本是可选的。 不适用于早期版本。 对 存储分析 HourMetrics 设置进行分组。 HourMetrics 设置汇总了队列的每小时聚合中按 API 分组的请求统计信息。
MinuteMetrics 对于版本 2013-08-15 及更高版本是可选的。 不适用于早期版本。 对 存储分析 MinuteMetrics 设置进行分组。 MinuteMetrics 设置提供了队列每分钟的请求统计信息。 对于早于 2013-08-15 的版本, MinuteMetrics 不包括在响应正文中。
版本 如果指定 了 LoggingMetricsHourMetricsMinuteMetrics 设置,则是必需的。 要配置的存储分析版本。
删除 如果指定 了 LoggingMetricsHourMetricsMinuteMetrics 设置,则是必需的。 仅适用于日志记录配置。 指示是否应记录所有删除请求。
读取 如果指定 了 LoggingMetricsHourMetricsMinuteMetrics 设置,则是必需的。 仅适用于日志记录配置。 指示是否应记录所有读取请求。
写入 如果指定 了 LoggingMetricsHourMetricsMinuteMetrics 设置,则是必需的。 仅适用于日志记录配置。 指示是否应记录所有写入请求。
已启用 必需。 指示是否为队列服务启用度量。

如果启用了读访问的地域冗余复制,则同时收集主度量值和辅助度量值。 如果未启用读取访问异地冗余复制,则仅收集主要指标。
IncludeAPIs 仅当启用度量值时才是必需的。 仅适用于度量值配置。 指示度量值是否应为调用的 API 操作生成汇总统计信息。
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 个定义的标头和 2 个带前缀的标头。 每个标头最多可以包含 256 个字符。
MaxAgeInSeconds 如果 存在 CorsRule 元素,则为必需项。 客户端/浏览器应缓存预检响应的秒数。
AllowedHeaders 如果 CorsRule 元素存在,则为必需项。 允许成为跨源请求的一部分的标头的以逗号分隔的列表。 限制为 64 个定义的标头和 2 个带前缀的标头。 每个标头最多可以包含 256 个字符。
AllowedMethods 如果 CorsRule 元素存在,则为必需项。 允许由源执行的 HTTP 方法的以逗号分隔的列表。 对于 Azure 存储,允许的方法是 DELETE、、GETHEADMERGEPOSTOPTIONSPUT

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

成功的操作将返回状态代码 202(已接受)。

响应头

此操作的响应包括以下标头。 该响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范

响应标头 说明
x-ms-request-id 唯一标识针对服务发出的请求。
x-ms-version 指定用于响应的操作的版本。 有关详细信息,请参阅 Azure 存储服务的版本控制
x-ms-client-request-id 可用于对请求和相应的响应进行故障排除。 如果请求中存在标头, x-ms-client-request-id 并且该值包含的可见 ASCII 字符不超过 1,024 个,则此标头的值等于标头的值。 x-ms-client-request-id如果请求中不存在标头,则响应中不会显示该标头。

响应正文

无。

授权

只有帐户所有者可以调用此操作。

注解

下列限制适用于 Azure 存储中的 CORS 规则:

  • 最多可存储 5 条规则。

  • 请求上所有 CORS 规则设置(不包括 XML 标记)的最大大小不应超过 2 KiB。

  • 允许的标头、公开的标头或允许的源的长度不应超过 256 个字符。

  • 允许的标头和公开的标头可以是以下任一项:

    • 文本标头,其中提供了准确的标头名称,如 x-ms-meta-processed。 最多可在请求中指定 64 个文本标头。

    • 带前缀的标头,其中提供了标头的前缀,如 x-ms-meta-data*。 以这种方式指定前缀允许或公开以指定前缀开头的任何标头。 最多可在请求中指定 2 个带前缀的标头。

  • 元素中指定的 AllowedMethods 方法 (或 HTTP 谓词) 必须符合 Azure 存储服务 API 支持的方法。 支持的方法包括 DELETE、、GETHEADMERGEPOSTOPTIONSPUT

在请求中指定 CORS 规则是可选的。 如果在请求正文中未指定 Cors 元素的情况下调用 Set Queue Service Properties ,则会保留任何现有的 CORS 规则。

若要禁用 CORS,请使用空的 CORS 规则设置 (调用 Set Queue Service Properties ,即,*</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 规范