Manage Azure File share backup with REST API
This article explains how to perform tasks for managing and monitoring the Azure file shares that are backed up by Azure Backup.
Monitor jobs
The Azure Backup service triggers jobs that run in the background. This includes scenarios such as triggering backup, restore operations, and disabling backup. These jobs can be tracked using their IDs.
Fetch job information from operations
An operation such as triggering backup will always return a jobID in the response.
For example, the final response of a trigger backup REST API operation is as follows:
{
"id": "c3a52d1d-0853-4211-8141-477c65740264",
"name": "c3a52d1d-0853-4211-8141-477c65740264",
"status": "Succeeded",
"startTime": "2020-02-03T18:10:48.296012Z",
"endTime": "2020-02-03T18:10:48.296012Z",
"properties": {
"objectType": "OperationStatusJobExtendedInfo",
"jobId": "e2ca2cf4-2eb9-4d4b-b16a-8e592d2a658b"
}
}
The Azure file share backup job is identified by the jobId field and can be tracked as mentioned here using a GET request.
Tracking the job
GET https://management.azure.com/Subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.RecoveryServices/vaults/{vaultName}/backupJobs/{jobName}?api-version=2019-05-13
The {jobName} is the "jobId" mentioned above. The response is always "200 OK" with the status field indicating the status of the job. Once it's "Completed" or "CompletedWithWarnings", the extendedInfo section reveals more details about the job.
GET https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupJobs/e2ca2cf4-2eb9-4d4b-b16a-8e592d2a658b?api-version=2019-05-13'
Response
| Name | Type | Description |
|---|---|---|
| 200 OK | JobResource | OK |
Response example
Once the GET URI is submitted, a 200 response is returned.
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'
'Server': 'Microsoft-IIS/10.0, Microsoft-IIS/10.0'
'X-Content-Type-Options': 'nosniff'
'x-ms-request-id': 'dba43f00-5cdb-43b1-a9ec-23e419db67c5'
'x-ms-client-request-id': 'a644712a-4895-11ea-ba57-0a580af42708, a644712a-4895-11ea-ba57-0a580af42708'
'X-Powered-By': 'ASP.NET'
'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'
'x-ms-ratelimit-remaining-subscription-reads': '11999'
'x-ms-correlation-request-id': 'dba43f00-5cdb-43b1-a9ec-23e419db67c5'
'x-ms-routing-request-id': 'WESTEUROPE:20200206T040341Z:dba43f00-5cdb-43b1-a9ec-23e419db67c5'
'Date': 'Thu, 06 Feb 2020 04:03:40 GMT'
{
"id": "/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupJobs/e2ca2cf4-2eb9-4d4b-b16a-8e592d2a658b",
"name": "e2ca2cf4-2eb9-4d4b-b16a-8e592d2a658b",
"type": "Microsoft.RecoveryServices/vaults/backupJobs",
"properties": {
"jobType": "AzureStorageJob",
"duration": "00:00:43.1809140",
"storageAccountName": "testvault2",
"storageAccountVersion": "Storage",
"extendedInfo": {
"tasksList": [],
"propertyBag": {
"File Share Name": "testshare",
"Storage Account Name": "testvault2",
"Policy Name": "schedule1"
}
},
"entityFriendlyName": "testshare",
"backupManagementType": "AzureStorage",
"operation": "ConfigureBackup",
"status": "Completed",
"startTime": "2020-02-03T18:10:48.296012Z",
"endTime": "2020-02-03T18:11:31.476926Z",
"activityId": "3677cec0-942d-4eac-921f-8f3c873140d7"
}
}
Modify policy
To change the policy with which the file share is protected, you can use the same format as enabling protection. Just provide the new policy ID in the request policy and submit the request.
For example: To change the protection policy of testshare from schedule1 to schedule2, provide the schedule2 ID in the request body.
{
"properties": {
"protectedItemType": "AzureFileShareProtectedItem",
"sourceResourceId": "/subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/AzureFiles/providers/Microsoft.Storage/storageAccounts/testvault2",
"policyId": "/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupPolicies/schedule2"
}
}
Stop protection but retain existing data
You can remove protection on a protected file share but retain the data already backed up. To do so, remove the policy in the request body you used to enable backup and submit the request. Once the association with the policy is removed, backups are no longer triggered, and no new recovery points are created.
{
"properties": {
"protectedItemType": "AzureFileShareProtectedItem",
"sourceResourceId": "/subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/AzureFiles/providers/Microsoft.Storage/storageAccounts/testvault2",
"policyId": "" ,
"protectionState":"ProtectionStopped"
}
}
Sample response
Stopping protection for a file share is an asynchronous operation. The operation creates another operation that needs to be tracked. It returns two responses: 202 (Accepted) when another operation is created, and 200 when that operation completes.
Response header when operation is successfully accepted:
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;testvault2/protectedItems/AzureFileShare;testshare/operationResults/b300922a-ad9c-4181-b4cd-d42ea780ad77?api-version=2019-05-13'
'Retry-After': '60'
msrest.http_logger : '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;testvault2/protectedItems/AzureFileShare;testshare/operationsStatus/b300922a-ad9c-4181-b4cd-d42ea780ad77?api-version=2019-05-13'
'X-Content-Type-Options': 'nosniff'
'x-ms-request-id': '3895e8a1-e4b9-4da5-bec7-2cf0266405f8'
'x-ms-client-request-id': 'd331c15e-48ab-11ea-84c0-0a580af46a50, d331c15e-48ab-11ea-84c0-0a580af46a50'
'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'
'X-Powered-By': 'ASP.NET'
'x-ms-ratelimit-remaining-subscription-writes': '1199'
'x-ms-correlation-request-id': '3895e8a1-e4b9-4da5-bec7-2cf0266405f8'
'x-ms-routing-request-id': 'WESTEUROPE:20200206T064224Z:3895e8a1-e4b9-4da5-bec7-2cf0266405f8'
'Date': 'Thu, 06 Feb 2020 06:42:24 GMT'
'Content-Length': '0'
Then track the resulting operation using the location header or Azure-AsyncOperation header with a GET command:
GET https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupoperations/b300922a-ad9c-4181-b4cd-d42ea780ad77?api-version=2016-12-01
Response body
{
"id": "b300922a-ad9c-4181-b4cd-d42ea780ad77",
"name": "b300922a-ad9c-4181-b4cd-d42ea780ad77",
"status": "Succeeded",
"startTime": "2020-02-06T06:42:24.4001299Z",
"endTime": "2020-02-06T06:42:24.4001299Z",
"properties": {
"objectType": "OperationStatusJobExtendedInfo",
"jobId": "7816fca8-d5be-4c41-b911-1bbd922e5826"
}
}
Stop protection and delete data
To remove the protection on a protected file share and delete the backup data as well, perform a delete operation as detailed here.
DELETE https://management.azure.com/Subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.RecoveryServices/vaults/{vaultName}/backupFabrics/{fabricName}/protectionContainers/{containerName}/protectedItems/{protectedItemName}?api-version=2019-05-13
The parameters {containerName} and {protectedItemName} are as set here.
The following example triggers an operation to stop protection for the testshare file share protected with azurefilesvault.
DELETE https://management.azure.com/Subscriptions/ef4ab5a7-c2c0-4304-af80-af49f48af3d1/resourceGroups/azurefiles/providers/Microsoft.RecoveryServices/vaults/azurefilesvault/backupFabrics/Azure/protectionContainers/StorageContainer;Storage;AzureFiles;testvault2/protectedItems/azurefileshare;testshare?api-version=2016-12-01
Responses
Delete protection is an asynchronous operation. The operation creates another operation that needs to be tracked separately. It returns two responses: 202 (Accepted) when another operation is created and 204 (NoContent) when that operation completes.
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for