Set Blob Service Properties

The Set Blob Service Properties operation sets properties for a storage account’s Blob Storage endpoint, including properties for Storage Analytics, cross-origin resource sharing (CORS) rules and soft-delete settings.

You can also use this operation to set the default request version for all incoming requests to Blob Storage that don't have a specified version.

For more information about CORS rules, see CORS support for the Azure Storage services.

Request

The Set Blob Service Properties request may be specified as follows. We recommend that you use HTTPS. Replace account-name with the name of your storage account:

Method Request URI HTTP version
PUT https://account-name.blob.core.windows.net/?restype=service&comp=properties HTTP/1.1

Note

The URI must always include a slash character (/) to separate the hostname from the path and query portions of the URI. In this operation, the path portion of the URI is empty.

URI parameters

URI Parameter Description
restype=service&comp=properties Required. The combination of both query strings is required to set the storage service properties.
timeout Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for Blob Storage operations.

Request headers

The required and optional request headers are described in the following table:

Request header Description
Authorization Required. Specifies the authorization scheme, storage account name, and signature. For more information, see Authorize requests to Azure Storage.
Date or x-ms-date Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
x-ms-version Required for all authorized requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.
x-ms-client-request-id Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Blob Storage.

Request body

For version 2012-02-12 and earlier, the format of the request body is as follows:

<?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>  
    <!-- The DefaultServiceVersion element can only be set for Blob Storage, and the request must be made using version 2011-08-18 and later -->  
    <DefaultServiceVersion>default-service-version-string</DefaultServiceVersion>  
</StorageServiceProperties>  

For version 2013-08-15 and later, the format of the request body is as follows:

<?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-verbs</AllowedMethods>  
            <MaxAgeInSeconds>max-caching-age-in-seconds</MaxAgeInSeconds>  
            <ExposedHeaders>comma-separated-list-of-response-headers</ExposedHeaders>  
            <AllowedHeaders>comma-separated-list-of-request-headers</AllowedHeaders>  
        </CorsRule>  
    </Cors>  
    <!-- The DefaultServiceVersion element can only be set for Blob Storage, and the request must be made using version 2011-08-18 and later -->  
    <DefaultServiceVersion>default-service-version-string</DefaultServiceVersion>  
</StorageServiceProperties>  

For version 2017-07-29 and later, the format of the request body is as follows:

<?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-verbs</AllowedMethods>  
            <MaxAgeInSeconds>max-caching-age-in-seconds</MaxAgeInSeconds>  
            <ExposedHeaders>comma-separated-list-of-response-headers</ExposedHeaders>  
            <AllowedHeaders>comma-separated-list-of-request-headers</AllowedHeaders>  
        </CorsRule>  
    </Cors>    
    <DefaultServiceVersion>default-service-version-string</DefaultServiceVersion>
    <DeleteRetentionPolicy>
        <Enabled>true|false</Enabled>
        <Days>number-of-days</Days>
    </DeleteRetentionPolicy>   
</StorageServiceProperties>  

For version 2018-03-28 and later, the format of the request body is as follows:

<?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-verbs</AllowedMethods>  
            <MaxAgeInSeconds>max-caching-age-in-seconds</MaxAgeInSeconds>  
            <ExposedHeaders>comma-separated-list-of-response-headers</ExposedHeaders>  
            <AllowedHeaders>comma-separated-list-of-request-headers</AllowedHeaders>  
        </CorsRule>  
    </Cors>    
    <DefaultServiceVersion>default-service-version-string</DefaultServiceVersion>
    <DeleteRetentionPolicy>
        <Enabled>true|false</Enabled>
        <Days>number-of-days</Days>
    </DeleteRetentionPolicy>
    <StaticWebsite>
        <Enabled>true|false</Enabled>
        <IndexDocument>default-name-of-index-page-under-each-directory</IndexDocument>
        <ErrorDocument404Path>absolute-path-of-the-custom-404-page</ErrorDocument404Path>
    </StaticWebsite>
</StorageServiceProperties>  

For version 2019-12-12 and later, the format of the request body is as follows:

<?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-verbs</AllowedMethods>  
            <MaxAgeInSeconds>max-caching-age-in-seconds</MaxAgeInSeconds>  
            <ExposedHeaders>comma-separated-list-of-response-headers</ExposedHeaders>  
            <AllowedHeaders>comma-separated-list-of-request-headers</AllowedHeaders>  
        </CorsRule>  
    </Cors>    
    <DefaultServiceVersion>default-service-version-string</DefaultServiceVersion>
    <DeleteRetentionPolicy>
        <Enabled>true|false</Enabled>
        <Days>number-of-days</Days>
    </DeleteRetentionPolicy>
    <StaticWebsite>
        <Enabled>true|false</Enabled>
        <IndexDocument>default-name-of-index-page-under-each-directory</IndexDocument>
        <DefaultIndexDocumentPath>absolute-path-of-the-default-index-page</DefaultIndexDocumentPath>
        <ErrorDocument404Path>absolute-path-of-the-custom-404-page</ErrorDocument404Path>
    </StaticWebsite>
</StorageServiceProperties>  

As of version 2013-08-15, you can call Set Blob Service Properties with one or more root elements specified in the request body. The root elements include:

  • Logging
  • HourMetrics
  • MinuteMetrics
  • Cors
  • DefaultServiceVersion
  • DeleteRetentionPolicy: Version 2017-07-29 and later
  • StaticWebsite: Version 2018-03-28 and later

It's no longer necessary to specify every root element on the request. If you omit a root element, the existing settings for the service for that functionality are preserved. However, if you do specify a root element, you must specify every child element for that element.

The following table describes the elements of the request body:

Element name Description
Logging Optional as of version 2013-08-15. Required for earlier versions. Groups the Azure Analytics Logging settings.
Metrics Required for version 2012-02-12 and earlier. Not applicable for version 2013-08-15 and later. Groups the Azure Analytics Metrics settings, which provide a summary of request statistics that are grouped by API in hourly aggregates for blobs.
HourMetrics Optional for version 2013-08-15 and later; not applicable for earlier versions. Groups the Azure Analytics HourMetrics settings, which provide a summary of request statistics grouped by API in hourly aggregates for blobs.
MinuteMetrics Optional for version 2013-08-15 and later; not applicable for earlier versions. Groups the Azure Analytics MinuteMetrics settings, which provide request statistics for each minute for blobs. For versions earlier than 2013-08-15, MinuteMetrics isn't included in the response body.
Version Required if the Logging, Metrics, HourMetrics, or MinuteMetrics settings are specified. The version of Storage Analytics to configure.
Delete Required if the Logging, Metrics, HourMetrics, or MinuteMetrics settings are specified. Applies only to logging configuration. Indicates whether all delete requests should be logged.
Read Required if the Logging, Metrics, HourMetrics, or MinuteMetrics settings are specified. Applies only to logging configuration. Indicates whether all read requests should be logged.
Write Required if the Logging, Metrics, HourMetrics, or MinuteMetrics settings are specified. Applies only to logging configuration. Indicates whether all write requests should be logged.
Enabled Required. Indicates whether metrics are enabled for Blob Storage.

If read-access geo-redundant replication is enabled, both primary and secondary metrics are collected. If read-access geo-redundant replication isn't enabled, only primary metrics are collected.
IncludeAPIs Required only if metrics are enabled. Applies only to metrics configuration. Indicates whether metrics should generate summary statistics for called API operations.
RetentionPolicy/Enabled Required. Indicates whether a retention policy is enabled for the storage service.
RetentionPolicy/Days Required only if a retention policy is enabled. Indicates the number of days that metrics or logging data should be retained. All data that's older than this value is deleted. The minimum value you can specify is 1; the largest value is 365 (one year).
RetentionPolicy/AllowPermanentDelete Optional, version 2020-02-10 and later. Allows you to enable permanent delete on the storage account. The default value is false.
DefaultServiceVersion Optional. To set DefaultServiceVersion, call Set Blob Service Properties by using version 2011-08-18 and later. DefaultServiceVersion indicates the default version to use for requests to Blob Storage if an incoming request’s version isn't specified. Possible values include version 2008-10-27 and later. For more information about applicable versions, see Versioning for the Azure Storage services.

Applies only to Blob Storage.
Cors Optional. The Cors element is supported for version 2013-08-15 and later. Groups all CORS rules.

Omitting this element group doesn't overwrite existing CORS settings.
CorsRule Optional. Specifies a CORS rule for Blob Storage. You can include up to five CorsRule elements in the request. If no CorsRule elements are included in the request body, all CORS rules are deleted, and CORS is disabled for Blob Storage.
AllowedOrigins Required if the CorsRule element is present. A comma-separated list of origin domains that are allowed via CORS, or "*" to allow all domains. An origin domain may also include a wildcard character in the subdomain to permit requests via CORS for all subdomains of a domain. Limited to 64 origin domains. Each allowed origin can have up to 256 characters.
ExposedHeaders Required if the CorsRule element is present. A comma-separated list of response headers to expose to CORS clients. Limited to 64 defined headers and two prefixed headers. Each header can be up to 256 characters.
MaxAgeInSeconds Required if the CorsRule element is present. The number of seconds that the client/browser should cache a preflight response.
AllowedHeaders Required if the CorsRule element exists. A comma-separated list of headers allowed to be part of the cross-origin request. Limited to 64 defined headers and 2 prefixed headers. Each header can be up to 256 characters.
AllowedMethods Required if the CorsRule element exists. A comma-separated list of HTTP methods that are allowed to be executed by the origin. For Azure Storage, permitted methods are DELETE, GET, HEAD, MERGE, PATCH, POST, OPTIONS, and PUT.
DeleteRetentionPolicy Optional. To set DeleteRetentionPolicy, call Set Blob Service Properties by using version 2017-07-29 and later. Groups the soft-delete settings. Applies only to Blob Storage.
DeleteRetentionPolicy/Enabled Required. Indicates whether the deleted blob or snapshot is retained or immediately removed by a delete operation.
DeleteRetentionPolicy/Days Required only if the DeleteRetentionPolicy/Enabled is true. Indicates the number of days that deleted blob be retained. All data that's older than this value is permanently deleted. The minimum value you can specify is 1; the largest value is 365.
StaticWebsite Optional. To set StaticWebsite properties, call Set Blob Service Properties by using version 2018-03-28 and later. Applies only to Blob Storage.
StaticWebsite/Enabled Required. Indicates whether static website support is enabled for the specified account.
StaticWebsite/IndexDocument Optional. The webpage that Azure Storage serves for requests to the root of a website or any subfolder (for example, index.html). The value is case-sensitive.
StaticWebsite/DefaultIndexDocumentPath Optional. The absolute path to a webpage that Azure Storage serves for requests that don't correspond to an existing file. The contents of the page are returned with HTTP 200 OK (for example, index.html). The element is mutually exclusive with StaticWebsite/IndexDocument. The value is case-sensitive.
StaticWebsite/ErrorDocument404Path Optional. The absolute path to a webpage that Azure Storage serves for requests that don't correspond to an existing file. The contents of the page are returned with HTTP 404 Not Found (for example, error/404.html). Only a single custom 404 page is supported in each static website. The value is case-sensitive.

Response

The response includes an HTTP status code and a set of response headers.

Status code

A successful operation returns status code 202 (Accepted).

Response headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response header Description
x-ms-request-id Uniquely identifies a request made against the service.
x-ms-version Specifies the version of the operation used for the response. For more information, see Versioning for the Azure Storage services.
x-ms-client-request-id Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header if it's present in the request and the value contains no more than 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it won't be present in the response.

Response body

None.

Authorization

Authorization is required when calling any data access operation in Azure Storage. You can authorize the Set Blob Service Properties operation as described below.

Azure Storage supports using Microsoft Entra ID to authorize requests to blob data. With Microsoft Entra ID, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. The security principal may be a user, group, application service principal, or Azure managed identity. The security principal is authenticated by Microsoft Entra ID to return an OAuth 2.0 token. The token can then be used to authorize a request against the Blob service.

To learn more about authorization using Microsoft Entra ID, see Authorize access to blobs using Microsoft Entra ID.

Permissions

Listed below are the RBAC action necessary for a Microsoft Entra user, group, or service principal to call the Set Blob Service Properties operation, and the least privileged built-in Azure RBAC role that includes this action:

To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.

Remarks

The following restrictions and limitations apply to CORS rules in Azure Storage:

  • A maximum of five rules can be stored.

  • The maximum size of all CORS rules settings on the request, excluding XML tags, should not exceed 2 KiB.

  • The length of an allowed header, exposed header, or allowed origin should not exceed 256 characters.

  • Allowed headers and exposed headers may be either:

    • Literal headers, where the exact header name is provided, such as x-ms-meta-processed. A maximum of 64 literal headers may be specified on the request.

    • Prefixed headers, where a prefix of the header is provided, such as x-ms-meta-data*. Specifying a prefix in this manner allows or exposes any header that begins with the specified prefix. A maximum of two prefixed headers may be specified on the request.

  • The methods (or HTTP verbs) that are specified in the AllowedMethods element must conform to the methods that are supported by the Azure Storage APIs. Supported methods are DELETE, GET, HEAD, MERGE, PATCH, POST, OPTIONS, and PUT.

Specifying CORS rules on the request is optional. If you call Set Blob Service Properties without specifying the Cors element in the request body, any existing CORS rules are maintained.

To disable CORS, call Set Blob Service Properties with an empty CORS rules setting (that is,</Cors>) and no inner CORS rules. This call deletes any existing rules, and it disables CORS for Blob Storage.

All CORS rule elements are required if the CorsRule element is specified. The request fails with error code 400 (Bad Request) if any element is missing.

As of version 2013-08-15, XML settings elements are optional, so you can update a specific element by sending an XML that contains only the updated element. Other settings aren't affected.

For detailed information about CORS rules and evaluation logic, see CORS support for the Azure Storage services.

Billing

Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API, or from an Azure Storage client library. These requests accrue charges per transaction. The type of transaction affects how the account is charged. For example, read transactions accrue to a different billing category than write transactions. The following table shows the billing category for Set Blob Service Properties requests based on the storage account type:

Operation Storage account type Billing category
Set Blob Service Properties Premium block blob
Standard general-purpose v2
Other operations
Set Blob Service Properties Standard general-purpose v1 Write operations

To learn about pricing for the specified billing category, see Azure Blob Storage Pricing.

Sample request and response

The following sample URI makes a request to change Blob Storage properties for the fictional storage account named myaccount:

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

The request is sent with the following headers:

x-ms-version: 2018-03-28
x-ms-date: Tue, 12 Sep 2018 23:38:35 GMT 
Authorization: SharedKey myaccount:Z1lTLDwtq5o1UYQluucdsXk6/iB7YxEu0m6VofAEkUE=  
Host: myaccount.blob.core.windows.net  

The request is sent with the following XML body:

<?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>1.0</Version>  
        <Enabled>true</Enabled>  
        <IncludeAPIs>true</IncludeAPIs>  
        <RetentionPolicy>  
            <Enabled>true</Enabled>  
            <Days>7</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>
    <DeleteRetentionPolicy>
        <Enabled>true</Enabled>
        <Days>5</Days>
    </DeleteRetentionPolicy>  
    <StaticWebsite>  
        <Enabled>true</Enabled>  
        <IndexDocument>index.html</IndexDocument>  
        <ErrorDocument404Path>error/404.html</ErrorDocument404Path>  
    </StaticWebsite>  
    <DefaultServiceVersion>2018-03-28</DefaultServiceVersion>  
</StorageServiceProperties>  

After the request has been sent, the following response is returned:

HTTP/1.1 202 Accepted
Transfer-Encoding: chunked
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cb939a31-0cc6-49bb-9fe5-3327691f2a30 
x-ms-version: 2018-03-28
Date: Tue, 12 Sep 2018 23:38:35 GMT
  

See also

Storage Analytics
CORS support for the Azure Storage services
CORS HTTP specification