Set File Service Properties

  • Article

The Set File Service Properties operation sets properties for the File service resource by using the FileREST API. Although this API is fully supported, it's a legacy management API. We recommend that you instead use File Services - Set Service Properties, which is provided by the Azure Storage resource provider (Microsoft.Storage). To learn more about programmatically interacting with the File service resource by using the Azure Storage resource provider, see Operations on the File service.

Protocol availability

Enabled file share protocol Available
SMB Yes
NFS Yes

Request

You can specify the Set File Service Properties request 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.file.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 File service 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. This operation is available only in version 2015-02-21 and later. To enable metrics for the File service, you must specify version 2015-04-05 or later.

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 Storage Analytics 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 Files.

Request body

The format of the request body for version 2020-02-10 is as follows:

<?xml version="1.0" encoding="utf-8"?>  
<StorageServiceProperties>  
    <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>    
    <ShareDeleteRetentionPolicy>
        <Enabled>true|false</Enabled>
        <Days>integer-value</Days>
    </ShareDeleteRetentionPolicy>
    <ProtocolSettings>
        <SMB>
            <Multichannel>
                <Enabled>true|false</Enabled>
            </Multichannel>
            <Versions>comma-separated-list-of-smb-versions</Versions>
            <AuthenticationMethods>comma-separated-list-of-auth-methods</AuthenticationMethod>
            <KerberosTicketEncryption>csv-of-kerb-encryption-algorithms</KerberosTicketEncryption>
            <ChannelEncryption>csv-of-smb-encryption-algorithms</ChannelEncryption>
        </SMB>
    </ProtocolSettings>
</StorageServiceProperties>

It isn't 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 certain root element, you must specify every child element for that element. The root elements include:

  • HourMetrics
  • MinuteMetrics
  • Cors
  • ProtocolSettings

The elements of the request body are described in the following table:

Name Description
HourMetrics Optional for version 2015-04-05 and later. Not applicable for earlier versions. Groups the Storage Analytics HourMetrics settings, which provide a summary of request statistics grouped by API in hourly aggregates.
MinuteMetrics Optional for version 2015-04-05 and later. Not applicable for earlier versions. Groups the Storage Analytics MinuteMetrics settings, which provide request statistics for each minute.
Version Required if metrics are enabled. The version of Storage Analytics to configure. Use 1.0 for this value.
Enabled Required. Indicates whether metrics are enabled for the File service.
IncludeAPIs Required only if metrics are enabled. Indicates whether metrics should generate summary statistics for called API operations.
RetentionPolicy/Enabled Required. Indicates whether a retention policy is enabled for the File service. If false, metrics data is retained, and the user is responsible for deleting it.
RetentionPolicy/Days Required only if a retention policy is enabled. Indicates the number of days that metrics data should be retained. All data older than this value is deleted. The minimum that you can specify is 1, and the maximum value is 365 (one year). Metrics data is deleted on a best-effort basis after the retention period expires.
Cors Optional. The Cors element is supported for version 2015-02-21 and later. Groups all cross-origin resource sharing (CORS) rules. Omitting this element group doesn't overwrite existing CORS settings.
CorsRule Optional. Specifies a CORS rule for the File service. 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 the File service.
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 contain 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 that are allowed to be part of the cross-origin request. Limited to 64 defined headers and 2 prefixed headers. Each header can contain up to 256 characters.
AllowedMethods Required if CorsRule element exists. A comma-separated list of HTTP methods that are allowed to be executed by the origin. For Azure Files, the permitted methods are DELETE, GET, HEAD, MERGE, POST, OPTIONS, and PUT.
ShareDeleteRetentionPolicy Optional. The soft-delete properties for the Azure file shares in this storage account.
Days Optional. Indicates the number of days that the Azure file share should be retained (soft-deleted). The minimum that you can specify is 1, and the maximum value is 365 (one year).
Enabled Optional. Indicates whether the storage account has soft-delete enabled for Azure Files.
ProtocolSettings Optional. Groups the settings for file system protocols.
SMB Optional. Groups the settings for SMB.
Multichannel Optional. Contains the settings for SMB multichannel. SMB multichannel contains the Enabled Boolean property, which toggles the state of SMB multichannel.
Version Optional as of version 2020-04-08. Comma-separated list of allowed SMB versions. Allowed values are SMB2.1, SMB3.0, and SMB3.1.1.
AuthenticationMethods Optional as of version 2020-04-08. Comma-separated list of allowed authentication methods. Allowed values are NTLMv2 and Kerberos.
KerberosTicketEncryption Optional as of version 2020-04-08. Comma-separated list of allowed Kerberos ticket encryption algorithms. Allowed values are RC4-HMAC and AES-256.
ChannelEncryption Optional as of version 2020-04-08. Comma-separated list of allowed SMB channel encryption protocols. Allowed values are AES-128-CCM, AES-128-GCM, and AES-256-GCM.

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 A value that uniquely identifies a request that's made against the service.
x-ms-version Specifies the version of the operation that was 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 the 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

Only the account owner may call this operation.

Remarks

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

  • 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 can be either of the following:

    • Literal headers, where the exact header name is provided, such as x-ms-meta-processed. A maximum of 64 literal headers can 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 that prefix. A maximum of two prefixed headers can be specified on the request.

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

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

To disable CORS, call Set File 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 the File service.

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.

For more information about CORS rules and evaluation logic, see Cross-origin resource sharing support for the Azure Storage services.

Sample request and response

The following sample URI makes a request to change the File service properties for a storage account named myaccount:

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

The request is sent with the following headers:

x-ms-version: 2020-02-10  
x-ms-date: <date>  
Authorization: SharedKey myaccount:Z1lTLDwtq5o1UYQluucdsXk6/iB7YxEu0m6VofAEkUE=  
Host: myaccount.file.core.windows.net

The request is sent with the following XML body:

<?xml version="1.0" encoding="utf-8"?>  
<StorageServiceProperties>  
    <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>
    <ShareDeleteRetentionPolicy>
        <Enabled>true</Enabled>
        <Days>7</Days>
    </ShareDeleteRetentionPolicy>
    <ProtocolSettings>
        <SMB>
            <Multichannel>
                <Enabled>true</Enabled>
            </Multichannel>
            <Versions>SMB3.1.1</Versions>
            <AuthenticationMethods>Kerberos</AuthenticationMethods>
            <KerberosTicketEncryption>AES-256</KerberosTicketEncryption>
            <ChannelEncryption>AES-256-GCM</ChannelEncryption>
        </SMB>
    </ProtocolSettings>
</StorageServiceProperties>

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

HTTP/1.1 202 Accepted  
Connection: Keep-Alive  
Transfer-Encoding: chunked  
Date: <date>  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cb939a31-0cc6-49bb-9fe5-3327691f2a30  
x-ms-version: 2015-04-05

See also

For more information about CORS rules and evaluation logic, see Cross-origin resource sharing support for the Azure Storage services.

For more information about Storage Analytics, see Storage Analytics.