Proposed Pull Request Change

📄 Document Links

View on GitHub View on Microsoft Learn

--- title: Restore Azure Files with REST API description: Learn how to use REST API to restore Azure Files or specific files from a restore point created by Azure Backup ms.topic: how-to ms.date: 02/17/2026 author: AbhishekMallick-MS ms.author: v-mallicka # Customer intent: As a cloud administrator, I want to restore backed-up Azure Files using REST API, so that I can efficiently recover entire file shares or specific files from backup points without relying on GUI tools. --- # Restore Azure Files using REST API This article explains how to restore an entire File Share or specific files from a restore point created by [Azure Backup](./backup-overview.md) by using the REST API. You can also restore Azure Files using [Azure portal](restore-afs.md), [Azure PowerShell](restore-afs-powershell.md), [Azure CLI](restore-afs-cli.md). To learn about the supported Azure Files backup and restore scenarios, region availability, and limitations, see the [support matrix](azure-file-share-support-matrix.md). For common questions, see the [frequently asked questions](backup-azure-files-faq.yml). ## Prerequisites We assume that you already have a backed-up File Share you want to restore. If you don’t, check [Backup Azure Files using REST API](backup-azure-file-share-rest-api.md) to learn how to create one. For this article, we use the following resources: * **RecoveryServicesVault**: *azurefilesvault* * **Resource group**: *azurefiles* * **Storage Account**: *afsaccount* * **File Share**: *azurefiles* ## Fetch ContainerName and ProtectedItemName For most of the restore related API calls, you need to pass values for the {containerName} and {protectedItemName} URI parameters. Use the ID attribute in the response body of the [GET backupprotectableitems](/rest/api/backup/protected-items/get) operation to retrieve values for these parameters. In our example, the ID of the File Share we want to protect is: `"/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/storagecontainer;storage;azurefiles;afsaccount/protectableItems/azurefileshare;azurefiles` So the values translate as follows: * {containername} - *storagecontainer;storage;azurefiles;afsaccount* * {protectedItemName} - *azurefileshare;azurefiles* ## Fetch recovery points for backed up Azure Files To restore any backed-up File Share or files, first select a recovery point to perform the restore operation. The available recovery points of a backed-up item can be listed using the [Recovery Point-List](/rest/api/site-recovery/recoverypoints/listbyreplicationprotecteditems) REST API call. It's a GET operation with all the relevant values. ```http GET https://management.azure.com/Subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.RecoveryServices/vaults/{vaultName}/backupFabrics/{fabricName}/protectionContainers/{containerName}/protectedItems/{protectedItemName}/recoveryPoints?api-version=2019-05-13&$filter={$filter} ``` Set the URI values as follows: * {fabricName}: *Azure* * {vaultName}: *azurefilesvault* * {containername}: *storagecontainer;storage;azurefiles;afsaccount* * {protectedItemName}: *azurefileshare;azurefiles* * {ResourceGroupName}: *azurefiles* The GET URI has all the required parameters. There's no need for another request body. ```http GET https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;storage;azurefiles;afsaccount/protectedItems/AzureFileShare;azurefiles/recoveryPoints?api-version=2019-05-13 ``` ### Example response for fetch recovery points Once the GET URI is submitted, a 200 response is returned: ```http HTTP/1.1" 200 None 'Cache-Control': 'no-cache' 'Pragma': 'no-cache' 'Transfer-Encoding': 'chunked' 'Content-Type': 'application/json' 'Content-Encoding': 'gzip' 'Expires': '-1' 'Vary': 'Accept-Encoding' 'X-Content-Type-Options': 'nosniff' 'x-ms-request-id': 'd68d7951-7d97-4c49-9a2d-7fbaab55233a' 'x-ms-client-request-id': '4edb5a58-47ea-11ea-a27a-0a580af41908, 4edb5a58-47ea-11ea-a27a-0a580af41908' 'Strict-Transport-Security': 'max-age=31536000; includeSubDomains' 'Server': 'Microsoft-IIS/10.0' 'X-Powered-By': 'ASP.NET' 'x-ms-ratelimit-remaining-subscription-reads': '11998' 'x-ms-correlation-request-id': 'd68d7951-7d97-4c49-9a2d-7fbaab55233a' 'x-ms-routing-request-id': 'WESTEUROPE:20200205T073708Z:d68d7951-7d97-4c49-9a2d-7fbaab55233a' 'Date': 'Wed, 05 Feb 2020 07:37:08 GMT' { “value”:[ { "eTag": null, "id": "/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;storage;azurefiles;afsaccount/protectedItems/AzureFileShare;azurefiles/recoveryPoints/932881138555802864", "location": null, "name": "932881138555802864", "properties": { "fileShareSnapshotUri": "https://afsaccount.file.core.windows.net/azurefiles?sharesnapshot=2020-02-04T08:01:35.0000000Z", "objectType": "AzureFileShareRecoveryPoint", "recoveryPointSizeInGb": 1, "recoveryPointTime": "2020-02-04T08:01:35+00:00", "recoveryPointType": "FileSystemConsistent" }, "resourceGroup": "azurefiles", "tags": null, "type": "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints" }, { "eTag": null, "id": "/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;storage;azurefiles;afsaccount/protectedItems/AzureFileShare;azurefiles/recoveryPoints/932878582606969225", "location": null, "name": "932878582606969225", "properties": { "fileShareSnapshotUri": "https://afsaccount.file.core.windows.net/azurefiles?sharesnapshot=2020-02-03T08:05:30.0000000Z", "objectType": "AzureFileShareRecoveryPoint", "recoveryPointSizeInGb": 1, "recoveryPointTime": "2020-02-03T08:05:30+00:00", "recoveryPointType": "FileSystemConsistent" }, "resourceGroup": "azurefiles", "tags": null, "type": "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints" }, { "eTag": null, "id": "/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;storage;azurefiles;afsaccount/protectedItems/AzureFileShare;azurefiles/recoveryPoints/932890167574511261", "location": null, "name": "932890167574511261", "properties": { "fileShareSnapshotUri": "https://afsaccount.file.core.windows.net/azurefiles?sharesnapshot=2020-02-02T08:03:50.0000000Z", "objectType": "AzureFileShareRecoveryPoint", "recoveryPointSizeInGb": 1, "recoveryPointTime": "2020-02-02T08:03:50+00:00", "recoveryPointType": "FileSystemConsistent" }, "resourceGroup": "azurefiles", "tags": null, "type": "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints" }, ``` The recovery point is identified with the {name} field in the response above. ## Full share recovery using REST API Use this restore option to restore the complete File Share in the original or an alternate location. Triggering restore is a POST request and you can perform this operation using the [trigger restore](/rest/api/backup/restores/trigger) REST API. ```http POST https://management.azure.com/Subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.RecoveryServices/vaults/{vaultName}/backupFabrics/{fabricName}/protectionContainers/{containerName}/protectedItems/{protectedItemName}/recoveryPoints/{recoveryPointId}/restore?api-version=2019-05-13 ``` The values {containerName} and {protectedItemName} are as set [here](#fetch-containername-and-protecteditemname) and recoveryPointID is the {name} field of the recovery point mentioned above. ```http POST https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;storage;azurefiles;afsaccount/protectedItems/AzureFileShare%3Bazurefiles/recoveryPoints/932886657837421071/restore?api-version=2019-05-13' ``` ### Create request body To trigger a restore for an Azure Files, the following are the components of the request body: Name | Type | Description --- | ---- | ---- Properties | AzureFileShareRestoreRequest | RestoreRequestResource properties For the complete list of definitions of the request body and other details, refer to the [trigger Restore REST API document](/rest/api/backup/restores/trigger#request-body). ### Restore to original location #### Request body example for restore to original location The following request body defines properties required to trigger an Azure Files restore: ```json { "properties":{ "objectType":"AzureFileShareRestoreRequest", "recoveryType":"OriginalLocation", "sourceResourceId":"/subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/AzureFiles/providers/Microsoft.Storage/storageAccounts/afsaccount", "copyOptions":"Overwrite", "restoreRequestType":"FullShareRestore" } } ``` ### Restore to alternate location Specify the following parameters for alternate location recovery: * **targetResourceId**: The storage account to which the backed-up content is restored. The target storage account must be in the same location as the vault. * **name**: The File Share within the target storage account to which the backed-up content is restored. * **targetFolderPath**: The folder under the File Share to which data is restored. #### Request body example for restore to alternate location The following request body restores the *azurefiles* File Share in the *afsaccount* storage account to the *azurefiles1* File Share in the *afaccount1* storage account. ```json { "properties":{ "objectType":"AzureFileShareRestoreRequest", "recoveryType":"AlternateLocation", "sourceResourceId":"/subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/AzureFiles/providers/Microsoft.Storage/storageAccounts/afsaccount", "copyOptions":"Overwrite", "restoreRequestType":"FullShareRestore", "restoreFileSpecs":[ { "targetFolderPath":"restoredata" } ], "targetDetails":{ "name":"azurefiles1", "targetResourceId":"/subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/AzureFiles/providers/Microsoft.Storage/storageAccounts/afaccount1" } } } ``` ### Response The triggering of a restore operation is an [asynchronous operation](../azure-resource-manager/management/async-operations.md). This operation creates another operation that needs to be tracked separately. It returns two responses: 202 (Accepted) when another operation is created, and 200 (OK) when that operation completes. #### Response example Once you submit the *POST* URI for triggering a restore, the initial response is 202 (Accepted) with a location header or Azure-async-header. ```http HTTP/1.1" 202 'Cache-Control': 'no-cache' 'Pragma': 'no-cache' 'Expires': '-1' 'Location': 'https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;storage;azurefiles;afsaccount/protectedItems/AzureFileShare;azurefiles/operationResults/68ccfbc1-a64f-4b29-b955-314b5790cfa9?api-version=2019-05-13' 'Retry-After': '60' 'Azure-AsyncOperation': 'https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;storage;azurefiles;afsaccount/protectedItems/AzureFileShare;azurefiles/operationsStatus/68ccfbc1-a64f-4b29-b955-314b5790cfa9?api-version=2019-05-13' 'X-Content-Type-Options': 'nosniff' 'x-ms-request-id': '2426777d-c5ec-44b6-a324-384f8947460c' 'x-ms-client-request-id': '3c743096-47eb-11ea-ae90-0a580af41908, 3c743096-47eb-11ea-ae90-0a580af41908' 'Strict-Transport-Security': 'max-age=31536000; includeSubDomains' 'X-Powered-By': 'ASP.NET' 'x-ms-ratelimit-remaining-subscription-writes': '1198' 'x-ms-correlation-request-id': '2426777d-c5ec-44b6-a324-384f8947460c' 'x-ms-routing-request-id': 'WESTEUROPE:20200205T074347Z:2426777d-c5ec-44b6-a324-384f8947460c' 'Date': 'Wed, 05 Feb 2020 07:43:47 GMT' ``` Then track the resulting operation using the location header or the Azure-AsyncOperation header with a GET command. ```http GET https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupOperations/68ccfbc1-a64f-4b29-b955-314b5790cfa9?api-version=2016-12-01 ``` Once the operation completes, it returns 200 (OK) with the ID of the resulting restore job in the response body. ```http HTTP/1.1" 200 'Cache-Control': 'no-cache' 'Pragma': 'no-cache' 'Transfer-Encoding': 'chunked' 'Content-Type': 'application/json' 'Content-Encoding': 'gzip' 'Expires': '-1' 'Vary': 'Accept-Encoding' 'X-Content-Type-Options': 'nosniff' 'x-ms-request-id': '41ee89b2-3be4-40d8-8ff6-f5592c2571e3' 'x-ms-client-request-id': '3c743096-47eb-11ea-ae90-0a580af41908, 3c743096-47eb-11ea-ae90-0a580af41908' 'Strict-Transport-Security': 'max-age=31536000; includeSubDomains' 'Server': 'Microsoft-IIS/10.0' 'X-Powered-By': 'ASP.NET' 'x-ms-ratelimit-remaining-subscription-reads': '11998' 'x-ms-correlation-request-id': '41ee89b2-3be4-40d8-8ff6-f5592c2571e3' 'x-ms-routing-request-id': 'WESTEUROPE:20200205T074348Z:41ee89b2-3be4-40d8-8ff6-f5592c2571e3' 'Date': 'Wed, 05 Feb 2020 07:43:47 GMT' { "id": "/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupJobs/a7e97e42-4e54-4d4b-b449-26fcf946f42c", "location": null, "name": "a7e97e42-4e54-4d4b-b449-26fcf946f42c", "properties": { "actionsInfo": [ "Cancellable" ], "activityId": "3c743096-47eb-11ea-ae90-0a580af41908", "backupManagementType": "AzureStorage", "duration": "0:00:01.863098", "endTime": null, "entityFriendlyName": "azurefiles", "errorDetails": null, "extendedInfo": { "dynamicErrorMessage": null, "propertyBag": {}, "tasksList": [] }, "jobType": "AzureStorageJob", "operation": "Restore", "startTime": "2020-02-05T07:43:47.144961+00:00", "status": "InProgress", "storageAccountName": "afsaccount", "storageAccountVersion": "Storage" }, "resourceGroup": "azurefiles", "tags": null, "type": "Microsoft.RecoveryServices/vaults/backupJobs" } ``` For alternate location recovery, the response body will be like this: ```http { "id": "/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupJobs/7e0ee41e-6e31-4728-a25c-98ff6b777641", "location": null, "name": "7e0ee41e-6e31-4728-a25c-98ff6b777641", "properties": { "actionsInfo": [ "Cancellable" ], "activityId": "6077be6e-483a-11ea-a915-0a580af4ad72", "backupManagementType": "AzureStorage", "duration": "0:00:02.171965", "endTime": null, "entityFriendlyName": "azurefiles", "errorDetails": null, "extendedInfo": { "dynamicErrorMessage": null, "propertyBag": { "Data Transferred (in MB)": "0", "Job Type": "Recover to an alternate file share", "Number Of Failed Files": "0", "Number Of Restored Files": "0", "Number Of Skipped Files": "0", "RestoreDestination": "afaccount1/azurefiles1/restoredata", "Source File Share Name": "azurefiles", "Source Storage Account Name": "afsaccount", "Target File Share Name": "azurefiles1", "Target Storage Account Name": "afaccount1" }, "tasksList": [] }, "jobType": "AzureStorageJob", "operation": "Restore", "startTime": "2020-02-05T17:10:18.106532+00:00", "status": "InProgress", "storageAccountName": "afsaccount", "storageAccountVersion": "ClassicCompute" }, "resourceGroup": "azurefiles", "tags": null, "type": "Microsoft.RecoveryServices/vaults/backupJobs" } ``` Since the backup job is a long running operation, it should be tracked as explained in the [monitor jobs using REST API document](./backup-azure-arm-userestapi-managejobs.md#track-the-job). ## Item level recovery using REST API You can use this restore option to restore individual files or folders in the original or an alternate location. ```http POST https://management.azure.com/Subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.RecoveryServices/vaults/{vaultName}/backupFabrics/{fabricName}/protectionContainers/{containerName}/protectedItems/{protectedItemName}/recoveryPoints/{recoveryPointId}/restore?api-version=2019-05-13 ``` The values {containerName} and {protectedItemName} are as set [here](#fetch-containername-and-protecteditemname) and recoveryPointID is the {name} field of the recovery point mentioned above. ```http POST https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;storage;azurefiles;afsaccount/protectedItems/AzureFileShare%3Bazurefiles/recoveryPoints/932886657837421071/restore?api-version=2019-05-13' ``` ### Create request body for item-level recovery using REST API To trigger a restore for an Azure Files, the following are the components of the request body: Name | Type | Description --- | ---- | ---- Properties | AzureFileShareRestoreRequest | RestoreRequestResource properties For the complete list of definitions of the request body and other details, refer to the [trigger Restore REST API document](/rest/api/backup/restores/trigger#request-body). ### Restore to original location for item-level recovery using REST API The following request body is to restore the *Restoretest.txt* file in the *azurefiles* File Share in the *afsaccount* storage account. Create Request Body ```json { "properties":{ "objectType":"AzureFileShareRestoreRequest", "copyOptions":"Overwrite", "recoveryType":"OriginalLocation", "restoreFileSpecs":[ { "fileSpecType":"File", "path":"RestoreTest.txt", "targetFolderPath":null } ], "restoreRequestType":"ItemLevelRestore", "sourceResourceId":"/subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.storage/storageAccounts/afsaccount", "targetDetails":null } } ``` ### Restore to alternate location for item-level recovery using REST API The following request body is to restore the *Restoretest.txt* file in the *azurefiles* File Share in the *afsaccount* storage account to the *restoredata* folder of the *azurefiles1* File Share in the *afaccount1* storage account. Create request body ```json { "properties":{ "objectType":"AzureFileShareRestoreRequest", "recoveryType":"AlternateLocation", "sourceResourceId":"/subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/AzureFiles/providers/Microsoft.Storage/storageAccounts/afsaccount", "copyOptions":"Overwrite", "restoreRequestType":"ItemLevelRestore", "restoreFileSpecs":[ { "path":"Restore/RestoreTest.txt", "fileSpecType":"File", "targetFolderPath":"restoredata" } ], "targetDetails":{ "name":"azurefiles1", "targetResourceId":"/subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/AzureFiles/providers/Microsoft.Storage/storageAccounts/afaccount1" } } } ``` The response should be handled in the same way as explained above for [full share restores](#full-share-recovery-using-rest-api). ## Next steps Manage Azure Files backups using [Azure portal](manage-afs-backup.md), [Azure PowerShell](manage-afs-powershell.md), [Azure CLI](manage-afs-backup-cli.md), [REST API](manage-azure-file-share-rest-api.md).