Get File Service Properties

Article
02/01/2023

The Get File Service Properties operation gets properties for the FileService 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 - Get Service Properties, which is provided by the storage resource provider (Microsoft.Storage). To learn more about programmatically interacting with the FileService resource by using the storage resource provider, see Operations on the FileService resource.

Protocol availability

Enabled file share protocol	Available
SMB
NFS

Request

The Get File 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
GET	`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 following table describes required and optional request headers.

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 retrieve metrics properties 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 Azure 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

None.

Response

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

Status code

A successful operation returns status code 200 (OK).

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 that's made against the service.
`x-ms-version`	Specifies the version of the operation that's 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 their 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 isn't present in the response.

Response body

The format of the response 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>

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

Name	Description
`HourMetrics`	Groups the Storage Analytics `HourMetrics` settings. The `HourMetrics` settings provide a summary of request statistics, grouped by API in hourly aggregates.
`MinuteMetrics`	Groups the Storage Analytics `MinuteMetrics` settings. The `MinuteMetrics` settings provide request statistics for each minute.
`Version`	The version of Storage Analytics that's currently in use.
`Enabled`	Indicates whether metrics are enabled for the File service.
`IncludeAPIs`	Indicates whether metrics generate summary statistics for called API operations.
`RetentionPolicy/Enabled`	Indicates whether a retention policy is enabled for the File service.
`RetentionPolicy/Days`	Indicates the number of days for which metrics data is retained. All data that's older than this value is deleted on a best-effort basis.
`Cors`	Groups all cross-origin resource sharing (CORS) rules.
`CorsRule`	Groups settings for a CORS rule.
`AllowedOrigins`	A comma-separated list of origin domains that are allowed via CORS, or "*" if all domains are allowed.
`ExposedHeaders`	A comma-separated list of response headers to expose to CORS clients.
`MaxAgeInSeconds`	The number of seconds that the client or browser should cache a preflight response.
`AllowedHeaders`	A comma-separated list of headers that are allowed to be part of the cross-origin request.
`AllowedMethods`	A comma-separated list of HTTP methods that are allowed to be executed by the origin. For Azure Files, permitted methods are DELETE, GET, HEAD, MERGE, POST, OPTIONS, and PUT.
`ShareDeleteRetentionPolicy`	The soft-delete properties for the Azure file shares in this storage account.
`Days`	Indicates the number of days that the Azure file share should be retained (soft-deleted). The minimum specified value can is 1 and the maximum value is 365.
`Enabled`	Indicates whether the storage account has soft-delete enabled for Azure Files.
`ProtocolSettings`	Groups the settings for file system protocols.
`SMB`	Groups the settings for Server Message Block (SMB).
`Multichannel`	Contains the settings for SMB Multichannel. This setting has one property: enabled/disabled.
`Version`	Available as of version 2020-04-08. A comma-separated list of allowed SMB versions. Possible values: `SMB2.1`, `SMB3.0`, and `SMB3.1.1`. If `Version` isn't specified, the default is that all versions are enabled. However, SMB 2.1 is available only if the storage account's `require secure transit` property is disabled, because SMB 2.1 doesn't support encryption.
`AuthenticationMethods`	Available as of version 2020-04-08. A comma-separated list of allowed authentication methods. Possible values: `NTLMv2`, `Kerberos`. If `AuthenticationMethods` isn't specified, the default is that all authentication methods are allowed.
`KerberosTicketEncryption`	Available as of version 2020-04-08. A comma-separated list of allowed Kerberos ticket encryption algorithms. Possible values: `RC4-HMAC` and `AES-256`. If `KerberosTicketEncryption` isn't specified, the default is that all Kerberos ticket encryption algorithms are supported.
`ChannelEncryption`	Available as of version 2020-04-08. A comma-separated list of allowed SMB channel encryption protocols. Possible values: `AES-128-CCM`, `AES-128-GCM`, and `AES-256-GCM`. If `ChannelEncryption` isn't specified, the default is that all channel encryption values are supported. If the storage account's `require secure transit` property is disabled, unencrypted SMB access is also allowed.

Authorization

Only the storage account owner may call this operation.

Sample request and response

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

Method	URL	Protocol
GET	`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

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

HTTP/1.1 200 OK  
Content-Length: 1020  
Content-Type: application/xml  
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

The response includes 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>

Remarks

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

For more information, see Storage Analytics.

Share via