[Key Vault] Added support for /prerestore and /prebackup endpoint…

…s in Backup clients (#39878) * Updated `autorest.md` files in all swagger folders. * Re-generated implementation code. * Updated ServiceVersion expandable enums. * Added public APIs for the new /prebacukp and /prerestore endpoints. * Added tests. * Refactored Backup client tests. * Updated tests. * Updated test recordings. * Updated documentation and samples. * Addressed PR feedback.
Azure · May 9, 2024 · 92a1a90 · 92a1a90
1 parent 6884420
commit 92a1a90
Show file tree

Hide file tree

Showing 36 changed files with 1,873 additions and 303 deletions.
diff --git a/sdk/keyvault/azure-security-keyvault-administration/README.md b/sdk/keyvault/azure-security-keyvault-administration/README.md
@@ -111,9 +111,15 @@ The Key Vault Backup Client provides both synchronous and asynchronous operation
 
 > NOTE: The backing store for key backups is a blob storage container using Shared Access Signature authentication. For more details on creating a SAS token using the `BlobServiceClient`, see the [Azure Storage Blobs client README][storage_readme_sas_token]. Alternatively, it is possible to [generate a SAS token in Storage Explorer][portal_sas_token].
 
+### Pre-Backup Operation
+A pre-backup operation represents a long-running operation that checks if it is possible to perform a full key backup.
+
 ### Backup Operation
 A backup operation represents a long-running operation for a full key backup.
 
+### Pre-Restore Operation
+A pre-restore operation represents a long-running operation that checks if it is possible to perform a full key restore from a backup.
+
 ### Restore Operation
 A restore operation represents a long-running operation for both a full key and selective key restore.
 
@@ -340,20 +346,47 @@ keyVaultAccessControlAsyncClient.deleteRoleAssignment(KeyVaultRoleScope.GLOBAL,
 ### Examples
 #### Sync API
 The following sections provide several code snippets covering some of the most common Azure Key Vault Backup client tasks, including:
+- [Pre-backup check for a Key Vault](#run-pre-backup-check-for-a-collection-of-keys)
 - [Backup a Key Vault](#backup-a-collection-of-keys)
+- [Pre-restore check for a Key Vault](#run-pre-restore-check-for-a-collection-of-keys)
 - [Restore a Key Vault](#restore-a-collection-of-keys)
 - [Restore a key](#selectively-restore-a-key)
 
+##### Run pre-backup check for a collection of keys
+Check if an entire collection of keys can be backed up by using `beginPreBackup()`.
+
+```java readme-sample-beginPreBackup
+String blobStorageUrl = "https://myaccount.blob.core.windows.net/myContainer";
+String sasToken = "<sas-token>";
+
+SyncPoller<KeyVaultBackupOperation, String> preBackupPoller =
+    keyVaultBackupClient.beginPreBackup(blobStorageUrl, sasToken);
+PollResponse<KeyVaultBackupOperation> pollResponse = preBackupPoller.poll();
+
+System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
+
+PollResponse<KeyVaultBackupOperation> finalPollResponse = preBackupPoller.waitForCompletion();
+
+if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
+    String folderUrl = preBackupPoller.getFinalResult();
+
+    System.out.printf("Pre-backup check completed successfully.%n");
+} else {
+    KeyVaultBackupOperation operation = preBackupPoller.poll().getValue();
+
+    System.out.printf("Pre-backup check failed with error: %s.%n", operation.getError().getMessage());
+}
+```
+
 ##### Backup a collection of keys
 Back up an entire collection of keys using `beginBackup()`.
 
 ```java readme-sample-beginBackup
 String blobStorageUrl = "https://myaccount.blob.core.windows.net/myContainer";
-String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
+String sasToken = "<sas-token>";
 
 SyncPoller<KeyVaultBackupOperation, String> backupPoller =
     keyVaultBackupClient.beginBackup(blobStorageUrl, sasToken);
-
 PollResponse<KeyVaultBackupOperation> pollResponse = backupPoller.poll();
 
 System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
@@ -371,26 +404,49 @@ if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COM
 }
 ```
 
+##### Run pre-restore check for a collection of keys
+Check if an entire collection of keys can be restored from a backup by using `beginPreRestore()`.
+
+```java readme-sample-beginPreRestore
+String folderUrl = "https://myaccount.blob.core.windows.net/myContainer/mhsm-myaccount-2020090117323313";
+String sasToken = "<sas-token>";
+
+SyncPoller<KeyVaultRestoreOperation, KeyVaultRestoreResult> preRestorePoller =
+    keyVaultBackupClient.beginPreRestore(folderUrl, sasToken);
+PollResponse<KeyVaultRestoreOperation> pollResponse = preRestorePoller.poll();
+
+System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
+
+PollResponse<KeyVaultRestoreOperation> finalPollResponse = preRestorePoller.waitForCompletion();
+
+if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
+    System.out.printf("Pre-restore check completed successfully.%n");
+} else {
+    KeyVaultRestoreOperation operation = preRestorePoller.poll().getValue();
+
+    System.out.printf("Pre-restore check failed with error: %s.%n", operation.getError().getMessage());
+}
+```
+
 ##### Restore a collection of keys
 Restore an entire collection of keys from a backup using `beginRestore()`.
 
 ```java readme-sample-beginRestore
 String folderUrl = "https://myaccount.blob.core.windows.net/myContainer/mhsm-myaccount-2020090117323313";
-String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
+String sasToken = "<sas-token>";
 
-SyncPoller<KeyVaultRestoreOperation, KeyVaultRestoreResult> backupPoller =
+SyncPoller<KeyVaultRestoreOperation, KeyVaultRestoreResult> restorePoller =
     keyVaultBackupClient.beginRestore(folderUrl, sasToken);
-
-PollResponse<KeyVaultRestoreOperation> pollResponse = backupPoller.poll();
+PollResponse<KeyVaultRestoreOperation> pollResponse = restorePoller.poll();
 
 System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
 
-PollResponse<KeyVaultRestoreOperation> finalPollResponse = backupPoller.waitForCompletion();
+PollResponse<KeyVaultRestoreOperation> finalPollResponse = restorePoller.waitForCompletion();
 
 if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
     System.out.printf("Backup restored successfully.%n");
 } else {
-    KeyVaultRestoreOperation operation = backupPoller.poll().getValue();
+    KeyVaultRestoreOperation operation = restorePoller.poll().getValue();
 
     System.out.printf("Restore failed with error: %s.%n", operation.getError().getMessage());
 }
@@ -401,41 +457,60 @@ Restore a specific key from a backup using `beginSelectiveRestore()`.
 
 ```java readme-sample-beginSelectiveKeyRestore
 String folderUrl = "https://myaccount.blob.core.windows.net/myContainer/mhsm-myaccount-2020090117323313";
-String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
+String sasToken = "<sas-token>";
 String keyName = "myKey";
 
-SyncPoller<KeyVaultSelectiveKeyRestoreOperation, KeyVaultSelectiveKeyRestoreResult> backupPoller =
+SyncPoller<KeyVaultSelectiveKeyRestoreOperation, KeyVaultSelectiveKeyRestoreResult> restorePoller =
     keyVaultBackupClient.beginSelectiveKeyRestore(folderUrl, sasToken, keyName);
-
-PollResponse<KeyVaultSelectiveKeyRestoreOperation> pollResponse = backupPoller.poll();
+PollResponse<KeyVaultSelectiveKeyRestoreOperation> pollResponse = restorePoller.poll();
 
 System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
 
-PollResponse<KeyVaultSelectiveKeyRestoreOperation> finalPollResponse = backupPoller.waitForCompletion();
+PollResponse<KeyVaultSelectiveKeyRestoreOperation> finalPollResponse = restorePoller.waitForCompletion();
 
 if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
     System.out.printf("Key restored successfully.%n");
 } else {
-    KeyVaultSelectiveKeyRestoreOperation operation = backupPoller.poll().getValue();
+    KeyVaultSelectiveKeyRestoreOperation operation = restorePoller.poll().getValue();
 
     System.out.printf("Key restore failed with error: %s.%n", operation.getError().getMessage());
 }
 ```
 
 #### Async API
 The following sections provide several code snippets covering some of the most common asynchronous Azure Key Vault Backup client tasks, including:
+- [Run pre-backup check for a collection of keys asynchronously](#run-pre-backup-check-for-a-collection-of-keys-asynchronously)
 - [Backup a Key Vault asynchronously](#backup-a-collection-of-keys-asynchronously)
+- [Run pre-restore check for a collection of keys asynchronously](#run-pre-restore-check-for-a-collection-of-keys-asynchronously)
 - [Restore a Key Vault asynchronously](#restore-a-collection-of-keys-asynchronously)
 - [Restore a key asynchronously](#selectively-restore-a-key-asynchronously)
 
 > Note : You should add `System.in.read()` or `Thread.sleep()` after the function calls in the main class/thread to allow async functions/operations to execute and finish before the main application/thread exits.
 
+##### Run pre-backup check for a collection of keys asynchronously
+Check if an entire collection of keys can be backed up by using `beginPreBackup()`.
+
+```java readme-sample-beginPreBackupAsync
+String blobStorageUrl = "https://myaccount.blob.core.windows.net/myContainer";
+String sasToken = "<sas-token>";
+
+keyVaultBackupAsyncClient.beginPreBackup(blobStorageUrl, sasToken)
+    .setPollInterval(Duration.ofSeconds(1)) // You can set a custom polling interval.
+    .doOnError(e -> System.out.printf("Pre-backup check failed with error: %s.%n", e.getMessage()))
+    .doOnNext(pollResponse ->
+        System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus()))
+    .filter(pollResponse -> pollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED)
+    .flatMap(AsyncPollResponse::getFinalResult)
+    .subscribe(folderUrl ->
+        System.out.printf("Pre-backup check completed successfully.%n"));
+```
+
 ##### Backup a collection of keys asynchronously
 Back up an entire collection of keys using `beginBackup()`.
 
 ```java readme-sample-beginBackupAsync
 String blobStorageUrl = "https://myaccount.blob.core.windows.net/myContainer";
-String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
+String sasToken = "<sas-token>";
 
 keyVaultBackupAsyncClient.beginBackup(blobStorageUrl, sasToken)
     .setPollInterval(Duration.ofSeconds(1)) // You can set a custom polling interval.
@@ -448,12 +523,29 @@ keyVaultBackupAsyncClient.beginBackup(blobStorageUrl, sasToken)
         System.out.printf("Backup completed. The storage location of this backup is: %s.%n", folderUrl));
 ```
 
+##### Run pre-restore check for a collection of keys asynchronously
+Check if an entire collection of keys can be restored from a backup by using `beginPreRestore()`.
+
+```java readme-sample-beginPreRestoreAsync
+String folderUrl = "https://myaccount.blob.core.windows.net/myContainer/mhsm-myaccount-2020090117323313";
+String sasToken = "<sas-token>";
+
+keyVaultBackupAsyncClient.beginPreRestore(folderUrl, sasToken)
+    .setPollInterval(Duration.ofSeconds(1)) // You can set a custom polling interval.
+    .doOnError(e -> System.out.printf("Pre-restore check failed with error: %s.%n", e.getMessage()))
+    .doOnNext(pollResponse ->
+        System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus()))
+    .filter(pollResponse -> pollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED)
+    .flatMap(AsyncPollResponse::getFinalResult)
+    .subscribe(unused -> System.out.printf("Pre-restore check completed successfully.%n"));
+```
+
 ##### Restore a collection of keys asynchronously
 Restore an entire collection of keys from a backup using `beginRestore()`.
 
 ```java readme-sample-beginRestoreAsync
 String folderUrl = "https://myaccount.blob.core.windows.net/myContainer/mhsm-myaccount-2020090117323313";
-String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
+String sasToken = "<sas-token>";
 
 keyVaultBackupAsyncClient.beginRestore(folderUrl, sasToken)
     .setPollInterval(Duration.ofSeconds(1)) // You can set a custom polling interval.
@@ -470,7 +562,7 @@ Restore an entire collection of keys from a backup using `beginSelectiveRestore(
 
 ```java readme-sample-beginSelectiveKeyRestoreAsync
 String folderUrl = "https://myaccount.blob.core.windows.net/myContainer/mhsm-myaccount-2020090117323313";
-String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
+String sasToken = "<sas-token>";
 String keyName = "myKey";
 
 keyVaultBackupAsyncClient.beginSelectiveKeyRestore(folderUrl, sasToken, keyName)

diff --git a/sdk/keyvault/azure-security-keyvault-administration/assets.json b/sdk/keyvault/azure-security-keyvault-administration/assets.json
@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "java",
   "TagPrefix": "java/keyvault/azure-security-keyvault-administration",
-  "Tag": "java/keyvault/azure-security-keyvault-administration_95d2cbb133"
+  "Tag": "java/keyvault/azure-security-keyvault-administration_18fc6d4e27"
 }
diff --git a/...java/com/azure/security/keyvault/administration/KeyVaultAdministrationServiceVersion.java b/...java/com/azure/security/keyvault/administration/KeyVaultAdministrationServiceVersion.java
@@ -27,7 +27,12 @@ public enum KeyVaultAdministrationServiceVersion implements ServiceVersion {
     /**
      * Service version {@code 7.5}.
      */
-    V7_5("7.5");
+    V7_5("7.5"),
+
+    /**
+     * Service version {@code 7.6-preview.1}.
+     */
+    V7_6_PREVIEW_1("7.6-preview.1");
 
     private final String version;
 
@@ -46,6 +51,6 @@ public String getVersion() {
      * @return The latest {@link KeyVaultAdministrationServiceVersion}.
      */
     public static KeyVaultAdministrationServiceVersion getLatest() {
-        return V7_5;
+        return V7_6_PREVIEW_1;
     }
 }