file_shares

Creates, updates, deletes, gets or lists a file_shares resource.

Overview

Name	file_shares
Type	Resource
Id	azure.storage.file_shares

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}.
name	string	The name of the resource.
accessTier	string	Access tier for specific share. GpV2 account can choose between TransactionOptimized (default), Hot, and Cool. FileStorage account can choose Premium. Known values are: "TransactionOptimized", "Hot", "Cool", and "Premium". (TransactionOptimized, Hot, Cool, Premium)
accessTierChangeTime	string (date-time)	Indicates the last modification time for share access tier.
accessTierStatus	string	Indicates if there is a pending transition for access tier.
deleted	boolean	Indicates whether the share was deleted.
deletedTime	string (date-time)	The deleted time if the share was deleted.
enabledProtocols	string	The authentication protocol that is used for the file share. Can only be specified when creating a share. Known values are: "SMB" and "NFS". (SMB, NFS)
etag	string	Resource Etag.
fileSharePaidBursting	object	File Share Paid Bursting properties.
includedBurstIops	integer	The calculated burst IOPS of the share. This property is only for file shares created under Files Provisioned v2 account type.
lastModifiedTime	string (date-time)	Returns the date and time the share was last modified.
leaseDuration	string	Specifies whether the lease on a share is of infinite or fixed duration, only when the share is leased. Known values are: "Infinite" and "Fixed". (Infinite, Fixed)
leaseState	string	Lease state of the share. Known values are: "Available", "Leased", "Expired", "Breaking", and "Broken". (Available, Leased, Expired, Breaking, Broken)
leaseStatus	string	The lease status of the share. Known values are: "Locked" and "Unlocked". (Locked, Unlocked)
maxBurstCreditsForIops	integer	The calculated maximum burst credits for the share. This property is only for file shares created under Files Provisioned v2 account type.
metadata	object	A name-value pair to associate with the share as metadata.
nextAllowedProvisionedBandwidthDowngradeTime	string (date-time)	Returns the next allowed provisioned bandwidth downgrade time for the share. This property is only for file shares created under Files Provisioned v2 account type.
nextAllowedProvisionedIopsDowngradeTime	string (date-time)	Returns the next allowed provisioned IOPS downgrade time for the share. This property is only for file shares created under Files Provisioned v2 account type.
nextAllowedQuotaDowngradeTime	string (date-time)	Returns the next allowed provisioned storage size downgrade time for the share. This property is only for file shares created under Files Provisioned v1 SSD and Files Provisioned v2 account type.
provisionedBandwidthMibps	integer	The provisioned bandwidth of the share, in mebibytes per second. This property is only for file shares created under Files Provisioned v2 account type. Please refer to the GetFileServiceUsage API response for the minimum and maximum allowed value for provisioned bandwidth.
provisionedIops	integer	The provisioned IOPS of the share. This property is only for file shares created under Files Provisioned v2 account type. Please refer to the GetFileServiceUsage API response for the minimum and maximum allowed value for provisioned IOPS.
remainingRetentionDays	integer	Remaining retention days for share that was soft deleted.
rootSquash	string	The property is for NFS share only. The default is NoRootSquash. Known values are: "NoRootSquash", "RootSquash", and "AllSquash". (NoRootSquash, RootSquash, AllSquash)
shareQuota	integer	The provisioned size of the share, in gibibytes. Must be greater than 0, and less than or equal to 5TB (5120). For Large File Shares, the maximum size is 102400. For file shares created under Files Provisioned v2 account type, please refer to the GetFileServiceUsage API response for the minimum and maximum allowed provisioned storage size.
shareUsageBytes	integer	The approximate size of the data stored on the share. Note that this value may not include all recently created or recently resized files.
signedIdentifiers	array	List of stored access policies specified on the share.
snapshotTime	string (date-time)	Creation time of share snapshot returned in the response of list shares with expand param "snapshots".
systemData	object	Azure Resource Manager metadata containing createdBy and modifiedBy information.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts".
version	string	The version of the share.

list

Name	Datatype	Description
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}.
name	string	The name of the resource.
accessTier	string	Access tier for specific share. GpV2 account can choose between TransactionOptimized (default), Hot, and Cool. FileStorage account can choose Premium. Known values are: "TransactionOptimized", "Hot", "Cool", and "Premium". (TransactionOptimized, Hot, Cool, Premium)
accessTierChangeTime	string (date-time)	Indicates the last modification time for share access tier.
accessTierStatus	string	Indicates if there is a pending transition for access tier.
deleted	boolean	Indicates whether the share was deleted.
deletedTime	string (date-time)	The deleted time if the share was deleted.
enabledProtocols	string	The authentication protocol that is used for the file share. Can only be specified when creating a share. Known values are: "SMB" and "NFS". (SMB, NFS)
etag	string	Resource Etag.
fileSharePaidBursting	object	File Share Paid Bursting properties.
includedBurstIops	integer	The calculated burst IOPS of the share. This property is only for file shares created under Files Provisioned v2 account type.
lastModifiedTime	string (date-time)	Returns the date and time the share was last modified.
leaseDuration	string	Specifies whether the lease on a share is of infinite or fixed duration, only when the share is leased. Known values are: "Infinite" and "Fixed". (Infinite, Fixed)
leaseState	string	Lease state of the share. Known values are: "Available", "Leased", "Expired", "Breaking", and "Broken". (Available, Leased, Expired, Breaking, Broken)
leaseStatus	string	The lease status of the share. Known values are: "Locked" and "Unlocked". (Locked, Unlocked)
maxBurstCreditsForIops	integer	The calculated maximum burst credits for the share. This property is only for file shares created under Files Provisioned v2 account type.
metadata	object	A name-value pair to associate with the share as metadata.
nextAllowedProvisionedBandwidthDowngradeTime	string (date-time)	Returns the next allowed provisioned bandwidth downgrade time for the share. This property is only for file shares created under Files Provisioned v2 account type.
nextAllowedProvisionedIopsDowngradeTime	string (date-time)	Returns the next allowed provisioned IOPS downgrade time for the share. This property is only for file shares created under Files Provisioned v2 account type.
nextAllowedQuotaDowngradeTime	string (date-time)	Returns the next allowed provisioned storage size downgrade time for the share. This property is only for file shares created under Files Provisioned v1 SSD and Files Provisioned v2 account type.
provisionedBandwidthMibps	integer	The provisioned bandwidth of the share, in mebibytes per second. This property is only for file shares created under Files Provisioned v2 account type. Please refer to the GetFileServiceUsage API response for the minimum and maximum allowed value for provisioned bandwidth.
provisionedIops	integer	The provisioned IOPS of the share. This property is only for file shares created under Files Provisioned v2 account type. Please refer to the GetFileServiceUsage API response for the minimum and maximum allowed value for provisioned IOPS.
remainingRetentionDays	integer	Remaining retention days for share that was soft deleted.
rootSquash	string	The property is for NFS share only. The default is NoRootSquash. Known values are: "NoRootSquash", "RootSquash", and "AllSquash". (NoRootSquash, RootSquash, AllSquash)
shareQuota	integer	The provisioned size of the share, in gibibytes. Must be greater than 0, and less than or equal to 5TB (5120). For Large File Shares, the maximum size is 102400. For file shares created under Files Provisioned v2 account type, please refer to the GetFileServiceUsage API response for the minimum and maximum allowed provisioned storage size.
shareUsageBytes	integer	The approximate size of the data stored on the share. Note that this value may not include all recently created or recently resized files.
signedIdentifiers	array	List of stored access policies specified on the share.
snapshotTime	string (date-time)	Creation time of share snapshot returned in the response of list shares with expand param "snapshots".
systemData	object	Azure Resource Manager metadata containing createdBy and modifiedBy information.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts".
version	string	The version of the share.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	resource_group_name, account_name, share_name, subscription_id	$expand, x-ms-snapshot	Gets properties of a specified share.
list	select	resource_group_name, account_name, subscription_id	$maxpagesize, $filter, $expand	Lists all shares.
create	insert	resource_group_name, account_name, share_name, subscription_id	$expand	Creates a new share under the specified account as described by request body. The share resource includes metadata and properties for that share. It does not include a list of the files contained by the share.
update	update	resource_group_name, account_name, share_name, subscription_id		Updates share properties as specified in request body. Properties not mentioned in the request will not be changed. Update fails if the specified share does not already exist.
delete	delete	resource_group_name, account_name, share_name, subscription_id	x-ms-snapshot, $include	Deletes specified share under its account.
restore	exec	resource_group_name, account_name, share_name, subscription_id, deletedShareName, deletedShareVersion		Restore a file share within a valid retention days if share soft delete is enabled.
lease	exec	resource_group_name, account_name, share_name, subscription_id, action	x-ms-snapshot	The Lease Share operation establishes and manages a lock on a share for delete operations. The lock duration can be 15 to 60 seconds, or can be infinite.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_name	string	The name of the storage account within the specified resource group. Storage account names must be between 3 and 24 characters in length and use numbers and lower-case letters only. Required.
resource_group_name	string	The name of the resource group. The name is case insensitive. Required.
share_name	string	The name of the file share within the specified storage account. File share names must be between 3 and 63 characters in length and use numbers, lower-case letters and dash (-) only. Every dash (-) character must be immediately preceded and followed by a letter or number. Required.
subscription_id	string
$expand	string	Optional, used to expand the properties within share's properties. Valid values are: snapshots. Should be passed as a string with delimiter ','. Default value is None.
$filter	string	Optional. When specified, only share names starting with the filter will be listed. Default value is None.
$include	string	Optional. Valid values are: snapshots, leased-snapshots, none. The default value is snapshots. For 'snapshots', the file share is deleted including all of its file share snapshots. If the file share contains leased-snapshots, the deletion fails. For 'leased-snapshots', the file share is deleted included all of its file share snapshots (leased/unleased). For 'none', the file share is deleted if it has no share snapshots. If the file share contains any snapshots (leased or unleased), the deletion fails. Default value is None.
$maxpagesize	string
x-ms-snapshot	string	Optional. Specify the snapshot time to lease a snapshot. Default value is None.

SELECT examples

get

Gets properties of a specified share.

SELECT
id,
name,
accessTier,
accessTierChangeTime,
accessTierStatus,
deleted,
deletedTime,
enabledProtocols,
etag,
fileSharePaidBursting,
includedBurstIops,
lastModifiedTime,
leaseDuration,
leaseState,
leaseStatus,
maxBurstCreditsForIops,
metadata,
nextAllowedProvisionedBandwidthDowngradeTime,
nextAllowedProvisionedIopsDowngradeTime,
nextAllowedQuotaDowngradeTime,
provisionedBandwidthMibps,
provisionedIops,
remainingRetentionDays,
rootSquash,
shareQuota,
shareUsageBytes,
signedIdentifiers,
snapshotTime,
systemData,
type,
version
FROM azure.storage.file_shares
WHERE resource_group_name = '{{ resource_group_name }}' -- required
AND account_name = '{{ account_name }}' -- required
AND share_name = '{{ share_name }}' -- required
AND subscription_id = '{{ subscription_id }}' -- required
AND $expand = '{{ $expand }}'
AND x-ms-snapshot = '{{ x-ms-snapshot }}'
;

list

Lists all shares.

SELECT
id,
name,
accessTier,
accessTierChangeTime,
accessTierStatus,
deleted,
deletedTime,
enabledProtocols,
etag,
fileSharePaidBursting,
includedBurstIops,
lastModifiedTime,
leaseDuration,
leaseState,
leaseStatus,
maxBurstCreditsForIops,
metadata,
nextAllowedProvisionedBandwidthDowngradeTime,
nextAllowedProvisionedIopsDowngradeTime,
nextAllowedQuotaDowngradeTime,
provisionedBandwidthMibps,
provisionedIops,
remainingRetentionDays,
rootSquash,
shareQuota,
shareUsageBytes,
signedIdentifiers,
snapshotTime,
systemData,
type,
version
FROM azure.storage.file_shares
WHERE resource_group_name = '{{ resource_group_name }}' -- required
AND account_name = '{{ account_name }}' -- required
AND subscription_id = '{{ subscription_id }}' -- required
AND $maxpagesize = '{{ $maxpagesize }}'
AND $filter = '{{ $filter }}'
AND $expand = '{{ $expand }}'
;

INSERT examples

create

Creates a new share under the specified account as described by request body. The share resource includes metadata and properties for that share. It does not include a list of the files contained by the share.

INSERT INTO azure.storage.file_shares (
properties,
resource_group_name,
account_name,
share_name,
subscription_id,
$expand
)
SELECT 
'{{ properties }}',
'{{ resource_group_name }}',
'{{ account_name }}',
'{{ share_name }}',
'{{ subscription_id }}',
'{{ $expand }}'
RETURNING
id,
name,
etag,
properties,
systemData,
type
;

Manifest

# Description fields are for documentation purposes
- name: file_shares
props:
  - name: resource_group_name
    value: "{{ resource_group_name }}"
    description: Required parameter for the file_shares resource.
  - name: account_name
    value: "{{ account_name }}"
    description: Required parameter for the file_shares resource.
  - name: share_name
    value: "{{ share_name }}"
    description: Required parameter for the file_shares resource.
  - name: subscription_id
    value: "{{ subscription_id }}"
    description: Required parameter for the file_shares resource.
  - name: properties
    description: |
      Properties of the file share.
    value:
      lastModifiedTime: "{{ lastModifiedTime }}"
      metadata: "{{ metadata }}"
      shareQuota: {{ shareQuota }}
      provisionedIops: {{ provisionedIops }}
      provisionedBandwidthMibps: {{ provisionedBandwidthMibps }}
      includedBurstIops: {{ includedBurstIops }}
      maxBurstCreditsForIops: {{ maxBurstCreditsForIops }}
      nextAllowedQuotaDowngradeTime: "{{ nextAllowedQuotaDowngradeTime }}"
      nextAllowedProvisionedIopsDowngradeTime: "{{ nextAllowedProvisionedIopsDowngradeTime }}"
      nextAllowedProvisionedBandwidthDowngradeTime: "{{ nextAllowedProvisionedBandwidthDowngradeTime }}"
      enabledProtocols: "{{ enabledProtocols }}"
      rootSquash: "{{ rootSquash }}"
      version: "{{ version }}"
      deleted: {{ deleted }}
      deletedTime: "{{ deletedTime }}"
      remainingRetentionDays: {{ remainingRetentionDays }}
      accessTier: "{{ accessTier }}"
      accessTierChangeTime: "{{ accessTierChangeTime }}"
      accessTierStatus: "{{ accessTierStatus }}"
      shareUsageBytes: {{ shareUsageBytes }}
      leaseStatus: "{{ leaseStatus }}"
      leaseState: "{{ leaseState }}"
      leaseDuration: "{{ leaseDuration }}"
      signedIdentifiers:
        - id: "{{ id }}"
          accessPolicy:
            startTime: "{{ startTime }}"
            expiryTime: "{{ expiryTime }}"
            permission: "{{ permission }}"
      snapshotTime: "{{ snapshotTime }}"
      fileSharePaidBursting:
        paidBurstingEnabled: {{ paidBurstingEnabled }}
        paidBurstingMaxIops: {{ paidBurstingMaxIops }}
        paidBurstingMaxBandwidthMibps: {{ paidBurstingMaxBandwidthMibps }}
  - name: $expand
    value: "{{ $expand }}"
    description: Optional, used to expand the properties within share's properties. Valid values are: snapshots. Should be passed as a string with delimiter ','. Default value is None.
    description: Optional, used to expand the properties within share's properties. Valid values are: snapshots. Should be passed as a string with delimiter ','. Default value is None.

UPDATE examples

update

Updates share properties as specified in request body. Properties not mentioned in the request will not be changed. Update fails if the specified share does not already exist.

UPDATE azure.storage.file_shares
SET 
properties = '{{ properties }}'
WHERE 
resource_group_name = '{{ resource_group_name }}' --required
AND account_name = '{{ account_name }}' --required
AND share_name = '{{ share_name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
RETURNING
id,
name,
etag,
properties,
systemData,
type;

DELETE examples

delete

Deletes specified share under its account.

DELETE FROM azure.storage.file_shares
WHERE resource_group_name = '{{ resource_group_name }}' --required
AND account_name = '{{ account_name }}' --required
AND share_name = '{{ share_name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
AND x-ms-snapshot = '{{ x-ms-snapshot }}'
AND $include = '{{ $include }}'
;

Lifecycle Methods

restore

Restore a file share within a valid retention days if share soft delete is enabled.

EXEC azure.storage.file_shares.restore 
@resource_group_name='{{ resource_group_name }}' --required, 
@account_name='{{ account_name }}' --required, 
@share_name='{{ share_name }}' --required, 
@subscription_id='{{ subscription_id }}' --required 
@@json=
'{
"deletedShareName": "{{ deletedShareName }}", 
"deletedShareVersion": "{{ deletedShareVersion }}"
}'
;

lease

The Lease Share operation establishes and manages a lock on a share for delete operations. The lock duration can be 15 to 60 seconds, or can be infinite.

EXEC azure.storage.file_shares.lease 
@resource_group_name='{{ resource_group_name }}' --required, 
@account_name='{{ account_name }}' --required, 
@share_name='{{ share_name }}' --required, 
@subscription_id='{{ subscription_id }}' --required, 
@x-ms-snapshot='{{ x-ms-snapshot }}' 
@@json=
'{
"action": "{{ action }}", 
"leaseId": "{{ leaseId }}", 
"breakPeriod": {{ breakPeriod }}, 
"leaseDuration": {{ leaseDuration }}, 
"proposedLeaseId": "{{ proposedLeaseId }}"
}'
;