KeyVaultBackupClient.java
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.security.keyvault.administration;
import com.azure.core.annotation.ReturnType;
import com.azure.core.annotation.ServiceClient;
import com.azure.core.annotation.ServiceMethod;
import com.azure.core.util.polling.SyncPoller;
import com.azure.security.keyvault.administration.models.KeyVaultAdministrationException;
import com.azure.security.keyvault.administration.models.KeyVaultBackupOperation;
import com.azure.security.keyvault.administration.models.KeyVaultRestoreOperation;
import com.azure.security.keyvault.administration.models.KeyVaultRestoreResult;
import com.azure.security.keyvault.administration.models.KeyVaultSelectiveKeyRestoreOperation;
import com.azure.security.keyvault.administration.models.KeyVaultSelectiveKeyRestoreResult;
/**
* The {@link KeyVaultBackupClient} provides synchronous methods to perform backup and restore operations of an Azure
* Key Vault.
*
* <p>Instances of this client are obtained by calling the {@link KeyVaultBackupClientBuilder#buildClient()}
* method on a {@link KeyVaultBackupClientBuilder} object.</p>
*
* <p><strong>Samples to construct a sync client</strong></p>
* <!-- src_embed com.azure.security.keyvault.administration.keyVaultBackupClient.instantiation -->
* <pre>
* KeyVaultBackupClient keyVaultBackupClient = new KeyVaultBackupClientBuilder()
* .vaultUrl("https://myaccount.managedhsm.azure.net/")
* .credential(new DefaultAzureCredentialBuilder().build())
* .buildClient();
* </pre>
* <!-- end com.azure.security.keyvault.administration.keyVaultBackupClient.instantiation -->
*
* @see KeyVaultBackupClientBuilder
*/
@ServiceClient(builder = KeyVaultBackupClientBuilder.class)
public final class KeyVaultBackupClient {
private final KeyVaultBackupAsyncClient asyncClient;
/**
* Creates an {@link KeyVaultBackupClient} that uses a {@code pipeline} to service requests
*
* @param asyncClient The {@link KeyVaultBackupAsyncClient} that the client routes its request through.
*/
KeyVaultBackupClient(KeyVaultBackupAsyncClient asyncClient) {
this.asyncClient = asyncClient;
}
/**
* Get the vault endpoint URL.
*
* @return The vault endpoint URL.
*/
public String getVaultUrl() {
return asyncClient.getVaultUrl();
}
/**
* Initiates a full backup of the Key Vault.
*
* <p><strong>Code Samples</strong></p>
* <p>Starts a {@link KeyVaultBackupOperation backup operation}, polls for its status and waits for it to complete.
* Prints out the details of the operation's final result in case of success or prints out error details in case the
* operation fails.</p>
* <!-- src_embed com.azure.security.keyvault.administration.keyVaultBackupClient.beginBackup#String-String -->
* <pre>
* 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";
*
* SyncPoller<KeyVaultBackupOperation, String> backupPoller = client.beginBackup(blobStorageUrl, sasToken);
*
* PollResponse<KeyVaultBackupOperation> pollResponse = backupPoller.poll();
*
* System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
*
* PollResponse<KeyVaultBackupOperation> finalPollResponse = backupPoller.waitForCompletion();
*
* if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
* String folderUrl = backupPoller.getFinalResult();
*
* System.out.printf("Backup completed. The storage location of this backup is: %s.%n", folderUrl);
* } else {
* KeyVaultBackupOperation operation = backupPoller.poll().getValue();
*
* System.out.printf("Backup failed with error: %s.%n", operation.getError().getMessage());
* }
* </pre>
* <!-- end com.azure.security.keyvault.administration.keyVaultBackupClient.beginBackup#String-String -->
*
* @param blobStorageUrl The URL for the Blob Storage resource where the backup will be located.
* @param sasToken A Shared Access Signature (SAS) token to authorize access to the blob.
*
* @return A {@link SyncPoller} polling on the {@link KeyVaultBackupOperation backup operation} status.
*
* @throws KeyVaultAdministrationException If the given {@code blobStorageUrl} or {@code sasToken} are invalid.
* @throws NullPointerException If the {@code blobStorageUrl} or {@code sasToken} are {@code null}.
*/
@ServiceMethod(returns = ReturnType.LONG_RUNNING_OPERATION)
public SyncPoller<KeyVaultBackupOperation, String> beginBackup(String blobStorageUrl, String sasToken) {
return asyncClient.beginBackup(blobStorageUrl, sasToken).getSyncPoller();
}
/**
* Initiates a full restore of the Key Vault.
*
* <p><strong>Code Samples</strong></p>
* <p>Starts a {@link KeyVaultRestoreOperation restore operation}, polls for its status and waits for it to
* complete. Prints out error details in case the operation fails.</p>
* <!-- src_embed com.azure.security.keyvault.administration.keyVaultBackupClient.beginBackup#String-String -->
* <pre>
* 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";
*
* SyncPoller<KeyVaultBackupOperation, String> backupPoller = client.beginBackup(blobStorageUrl, sasToken);
*
* PollResponse<KeyVaultBackupOperation> pollResponse = backupPoller.poll();
*
* System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
*
* PollResponse<KeyVaultBackupOperation> finalPollResponse = backupPoller.waitForCompletion();
*
* if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
* String folderUrl = backupPoller.getFinalResult();
*
* System.out.printf("Backup completed. The storage location of this backup is: %s.%n", folderUrl);
* } else {
* KeyVaultBackupOperation operation = backupPoller.poll().getValue();
*
* System.out.printf("Backup failed with error: %s.%n", operation.getError().getMessage());
* }
* </pre>
* <!-- end com.azure.security.keyvault.administration.keyVaultBackupClient.beginBackup#String-String -->
*
* @param folderUrl The URL for the Blob Storage resource where the backup is located, including the path to
* the blob container where the backup resides. This would be the exact value that is returned as the result of a
* backup operation. An example of such a URL may look like the following:
* https://contoso.blob.core.windows.net/backup/mhsm-contoso-2020090117323313.
* @param sasToken A Shared Access Signature (SAS) token to authorize access to the blob.
*
* @return A {@link SyncPoller} to poll on the {@link KeyVaultRestoreOperation restore operation} status.
*
* @throws KeyVaultAdministrationException If the given {@code folderUrl} or {@code sasToken} are invalid.
* @throws NullPointerException If the {@code folderUrl} or {@code sasToken} are {@code null}.
*/
@ServiceMethod(returns = ReturnType.LONG_RUNNING_OPERATION)
public SyncPoller<KeyVaultRestoreOperation, KeyVaultRestoreResult> beginRestore(String folderUrl, String sasToken) {
return asyncClient.beginRestore(folderUrl, sasToken).getSyncPoller();
}
/**
* Restores all versions of a given key using the supplied SAS token pointing to a previously stored Azure Blob
* storage backup folder.
*
* <p><strong>Code Samples</strong></p>
* <p>Starts a {@link KeyVaultSelectiveKeyRestoreOperation selective key restore operation}, polls for its status
* and waits for it to complete. Prints out error details in case the operation fails.</p>
* <!-- src_embed com.azure.security.keyvault.administration.keyVaultBackupClient.beginSelectiveKeyRestore#String-String-String -->
* <pre>
* 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 keyName = "myKey";
*
* SyncPoller<KeyVaultSelectiveKeyRestoreOperation, KeyVaultSelectiveKeyRestoreResult> backupPoller =
* client.beginSelectiveKeyRestore(folderUrl, sasToken, keyName);
*
* PollResponse<KeyVaultSelectiveKeyRestoreOperation> pollResponse = backupPoller.poll();
*
* System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
*
* PollResponse<KeyVaultSelectiveKeyRestoreOperation> finalPollResponse = backupPoller.waitForCompletion();
*
* if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
* System.out.printf("Key restored successfully.%n");
* } else {
* KeyVaultSelectiveKeyRestoreOperation operation = backupPoller.poll().getValue();
*
* System.out.printf("Key restore failed with error: %s.%n", operation.getError().getMessage());
* }
* </pre>
* <!-- end com.azure.security.keyvault.administration.keyVaultBackupClient.beginSelectiveKeyRestore#String-String-String -->
*
* @param keyName The name of the key to be restored.
* @param folderUrl The URL for the Blob Storage resource where the backup is located, including the path to
* the blob container where the backup resides. This would be the exact value that is returned as the result of a
* backup operation. An example of such a URL may look like the following:
* https://contoso.blob.core.windows.net/backup/mhsm-contoso-2020090117323313.
* @param sasToken A Shared Access Signature (SAS) token to authorize access to the blob.
*
* @return A {@link SyncPoller} to poll on the {@link KeyVaultRestoreOperation restore operation} status.
*
* @throws KeyVaultAdministrationException If the given {@code folderUrl} or {@code sasToken} are invalid.
* @throws NullPointerException If the {@code keyName}, {@code folderUrl} or {@code sasToken} are {@code
* null}.
*/
@ServiceMethod(returns = ReturnType.LONG_RUNNING_OPERATION)
public SyncPoller<KeyVaultSelectiveKeyRestoreOperation, KeyVaultSelectiveKeyRestoreResult> beginSelectiveKeyRestore(String keyName, String folderUrl, String sasToken) {
return asyncClient.beginSelectiveKeyRestore(keyName, folderUrl, sasToken).getSyncPoller();
}
}