ShareServiceClient Class

Package:: com.azure.storage.file.share

Maven Artifact:: com.azure:azure-storage-file-share:12.29.2

java.lang.Object
- com.azure.storage.file.share.ShareServiceClient

public final class ShareServiceClient

This class provides a shareServiceAsyncClient that contains all the operations for interacting with a file account in Azure Storage. Operations allowed by the shareServiceAsyncClient are creating, listing, and deleting shares and retrieving and updating properties of the account.

Instantiating a Synchronous File Service Client

ShareServiceClient client = new ShareServiceClientBuilder()
     .connectionString("${connectionString}")
     .endpoint("${endpoint}")
     .buildClient();

View ShareServiceClientBuilder for additional ways to construct the shareServiceAsyncClient.

Method Summary

Modifier and Type	Method and Description
ShareClient	createShare(String shareName) Creates a share in the storage account with the specified name and returns a ShareClient to interact with it.
Response<ShareClient>	createShareWithResponse(String shareName, Map<String,String> metadata, Integer quotaInGB, Duration timeout, Context context) Creates a share in the storage account with the specified name and metadata and returns a ShareClient to interact with it.
Response<ShareClient>	createShareWithResponse(String shareName, ShareCreateOptions options, Duration timeout, Context context) Creates a share in the storage account with the specified name and options and returns a ShareClient to interact with it.
void	deleteShare(String shareName) Deletes the share in the storage account with the given name
Response<Void>	deleteShareWithResponse(String shareName, String snapshot, Duration timeout, Context context) Deletes the specific snapshot of the share in the storage account with the given name.
String	generateAccountSas(AccountSasSignatureValues accountSasSignatureValues) Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.
String	generateAccountSas(AccountSasSignatureValues accountSasSignatureValues, Consumer<String> stringToSignHandler, Context context) Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.
String	generateAccountSas(AccountSasSignatureValues accountSasSignatureValues, Context context) Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.
String	getAccountName() Get associated account name.
String	getFileServiceUrl() Get the url of the storage file service client.
HttpPipeline	getHttpPipeline() Gets the HttpPipeline powering this client.
ShareServiceProperties	getProperties() Retrieves the properties of the storage account's File service.
Response<ShareServiceProperties>	getPropertiesWithResponse(Duration timeout, Context context) Retrieves the properties of the storage account's File service.
ShareServiceVersion	getServiceVersion() Gets the service version the client is using.
ShareClient	getShareClient(String shareName) Constructs a ShareClient that interacts with the specified share.
UserDelegationKey	getUserDelegationKey(OffsetDateTime start, OffsetDateTime expiry) Gets a user delegation key for use with this account's share.
Response<UserDelegationKey>	getUserDelegationKeyWithResponse(OffsetDateTime start, OffsetDateTime expiry, Duration timeout, Context context) Gets a user delegation key for use with this account's share.
PagedIterable<ShareItem>	listShares() Lists all shares in the storage account without their metadata or snapshots.
PagedIterable<ShareItem>	listShares(ListSharesOptions options, Duration timeout, Context context) Lists the shares in the Storage account that pass the options filter.
void	setProperties(ShareServiceProperties properties) Sets the properties for the storage account's File service.
Response<Void>	setPropertiesWithResponse(ShareServiceProperties properties, Duration timeout, Context context) Sets the properties for the storage account's File service.
ShareClient	undeleteShare(String deletedShareName, String deletedShareVersion) Restores a previously deleted share.
Response<ShareClient>	undeleteShareWithResponse(String deletedShareName, String deletedShareVersion, Duration timeout, Context context) Restores a previously deleted share.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Method Details

public ShareClient createShare(String shareName)

Creates a share in the storage account with the specified name and returns a ShareClient to interact with it.

Code Samples

Create the share with share name of "myshare"

fileServiceClient.createShare("myshare");
 System.out.println("Creating the share completed.");

For more information, see the Azure Docs.

Parameters:

shareName - Name of the share

Returns:

The ShareClient

public Response<ShareClient> createShareWithResponse(String shareName, Map<String,String> metadata, Integer quotaInGB, Duration timeout, Context context)

Creates a share in the storage account with the specified name and metadata and returns a ShareClient to interact with it.

Code Samples

Create the share "test" with a quota of 10 GB

Response<ShareClient> response = fileServiceClient.createShareWithResponse("test",
     Collections.singletonMap("share", "metadata"), null, Duration.ofSeconds(5),
     new Context(key1, value1));
 System.out.printf("Creating the share completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.

For more information on updated max file share size values, see the Azure Docs.

Parameters:

shareName - Name of the share

metadata - Optional metadata to associate with the share

quotaInGB - Optional maximum size the share is allowed to grow to in GB. The default value is 5120. Refer to the Azure Docs for updated values.

timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response containing the ShareClient and the status of creating the share.

public Response<ShareClient> createShareWithResponse(String shareName, ShareCreateOptions options, Duration timeout, Context context)

Creates a share in the storage account with the specified name and options and returns a ShareClient to interact with it.

Code Samples

Response<ShareClient> response = fileServiceClient.createShareWithResponse("test",
     new ShareCreateOptions().setMetadata(Collections.singletonMap("share", "metadata")).setQuotaInGb(1)
     .setAccessTier(ShareAccessTier.HOT), Duration.ofSeconds(5), new Context(key1, value1));
 System.out.printf("Creating the share completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.

Parameters:

shareName - Name of the share

options - ShareCreateOptions

timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response containing the ShareClient and the status of creating the share.

public void deleteShare(String shareName)

Deletes the share in the storage account with the given name

Code Samples

Delete the share "test"

fileServiceClient.deleteShare("myshare");

For more information, see the Azure Docs.

Parameters:

shareName - Name of the share

public Response<Void> deleteShareWithResponse(String shareName, String snapshot, Duration timeout, Context context)

Deletes the specific snapshot of the share in the storage account with the given name. Snapshot are identified by the time they were created.

Code Samples

Delete the snapshot of share "test" that was created at current time.

OffsetDateTime midnight = OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.UTC);
 Response<Void> response = fileServiceClient.deleteShareWithResponse("test", midnight.toString(),
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Deleting the snapshot completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.

Parameters:

shareName - Name of the share

snapshot - Identifier of the snapshot

timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response that only contains headers and response status code

public String generateAccountSas(AccountSasSignatureValues accountSasSignatureValues)

Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.

Note : The client must be authenticated via StorageSharedKeyCredential

See AccountSasSignatureValues for more information on how to construct an account SAS.

Generating an account SAS

The snippet below generates an AccountSasSignatureValues object that lasts for two days and gives the user read and list access to blob and file shares.

AccountSasPermission permissions = new AccountSasPermission()
     .setListPermission(true)
     .setReadPermission(true);
 AccountSasResourceType resourceTypes = new AccountSasResourceType().setContainer(true);
 AccountSasService services = new AccountSasService().setBlobAccess(true).setFileAccess(true);
 OffsetDateTime expiryTime = OffsetDateTime.now().plus(Duration.ofDays(2));

 AccountSasSignatureValues sasValues =
     new AccountSasSignatureValues(expiryTime, permissions, services, resourceTypes);

 // Client must be authenticated via StorageSharedKeyCredential
 String sas = fileServiceClient.generateAccountSas(sasValues);

Parameters:

accountSasSignatureValues - AccountSasSignatureValues

Returns:

A String representing the SAS query parameters.

public String generateAccountSas(AccountSasSignatureValues accountSasSignatureValues, Consumer<String> stringToSignHandler, Context context)

Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.

Note : The client must be authenticated via StorageSharedKeyCredential

See AccountSasSignatureValues for more information on how to construct an account SAS.

Parameters:

accountSasSignatureValues - AccountSasSignatureValues

stringToSignHandler - For debugging purposes only. Returns the string to sign that was used to generate the signature.

context - Additional context that is passed through the code when generating a SAS.

Returns:

A String representing the SAS query parameters.

public String generateAccountSas(AccountSasSignatureValues accountSasSignatureValues, Context context)

Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.

Note : The client must be authenticated via StorageSharedKeyCredential

See AccountSasSignatureValues for more information on how to construct an account SAS.

The snippet below generates a SAS that lasts for two days and gives the user read and list access to blob containers and file shares.

AccountSasPermission permissions = new AccountSasPermission()
     .setListPermission(true)
     .setReadPermission(true);
 AccountSasResourceType resourceTypes = new AccountSasResourceType().setContainer(true);
 AccountSasService services = new AccountSasService().setBlobAccess(true).setFileAccess(true);
 OffsetDateTime expiryTime = OffsetDateTime.now().plus(Duration.ofDays(2));

 AccountSasSignatureValues sasValues =
     new AccountSasSignatureValues(expiryTime, permissions, services, resourceTypes);

 // Client must be authenticated via StorageSharedKeyCredential
 String sas = fileServiceClient.generateAccountSas(sasValues, new Context("key", "value"));

Parameters:

accountSasSignatureValues - AccountSasSignatureValues

context - Additional context that is passed through the code when generating a SAS.

Returns:

A String representing the SAS query parameters.

public String getAccountName()

Get associated account name.

Returns:

account name associated with this storage resource.

public String getFileServiceUrl()

Get the url of the storage file service client.

Returns:

the url of the Storage File service.

public HttpPipeline getHttpPipeline()

Gets the HttpPipeline powering this client.

Returns:

The pipeline.

public ShareServiceProperties getProperties()

Retrieves the properties of the storage account's File service. The properties range from storage analytics and metrics to CORS (Cross-Origin Resource Sharing).

Code Samples

Retrieve File service properties

ShareServiceProperties properties = fileServiceClient.getProperties();
 System.out.printf("Hour metrics enabled: %b, Minute metrics enabled: %b", properties.getHourMetrics().isEnabled(),
     properties.getMinuteMetrics().isEnabled());

For more information, see the Azure Docs.

Returns:

Storage account ShareServiceProperties

public Response<ShareServiceProperties> getPropertiesWithResponse(Duration timeout, Context context)

Retrieves the properties of the storage account's File service. The properties range from storage analytics and metrics to CORS (Cross-Origin Resource Sharing).

Code Samples

Retrieve File service properties

ShareServiceProperties properties = fileServiceClient.getPropertiesWithResponse(
     Duration.ofSeconds(1), new Context(key1, value1)).getValue();
 System.out.printf("Hour metrics enabled: %b, Minute metrics enabled: %b", properties.getHourMetrics().isEnabled(),
     properties.getMinuteMetrics().isEnabled());

For more information, see the Azure Docs.

Parameters:

timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response containing the Storage account ShareServiceProperties with headers and response status code

public ShareServiceVersion getServiceVersion()

Gets the service version the client is using.

Returns:

the service version the client is using.

public ShareClient getShareClient(String shareName)

Constructs a ShareClient that interacts with the specified share.

If the share doesn't exist in the storage account create() in the shareServiceAsyncClient will need to be called before interaction with the share can happen.

Parameters:

shareName - Name of the share

Returns:

a ShareClient that interacts with the specified share

public UserDelegationKey getUserDelegationKey(OffsetDateTime start, OffsetDateTime expiry)

Gets a user delegation key for use with this account's share. Note: This method call is only valid when using TokenCredential in this object's HttpPipeline.

Parameters:

start - Start time for the key's validity. Null indicates immediate start.

expiry - Expiration of the key's validity.

Returns:

The user delegation key.

public Response<UserDelegationKey> getUserDelegationKeyWithResponse(OffsetDateTime start, OffsetDateTime expiry, Duration timeout, Context context)

Gets a user delegation key for use with this account's share. Note: This method call is only valid when using TokenCredential in this object's HttpPipeline.

Parameters:

start - Start time for the key's validity. Null indicates immediate start.

expiry - Expiration of the key's validity.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A Response<T> whose value contains the user delegation key.

public PagedIterable<ShareItem> listShares()

Lists all shares in the storage account without their metadata or snapshots.

Code Samples

List all shares in the account

fileServiceClient.listShares().forEach(
     shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName())
 );

For more information, see the Azure Docs.

Returns:

ShareItem in the storage account without their metadata or snapshots

public PagedIterable<ShareItem> listShares(ListSharesOptions options, Duration timeout, Context context)

Lists the shares in the Storage account that pass the options filter.

Set starts with name filter using setPrefix(String prefix) to filter shares that are listed.

Pass true to setIncludeMetadata(boolean includeMetadata) to have metadata returned for the shares.

Pass true to setIncludeSnapshots(boolean includeSnapshots) to have snapshots of the shares listed.

Code Samples

List all shares that begin with "azure"

fileServiceClient.listShares(new ListSharesOptions().setPrefix("azure"), Duration.ofSeconds(1),
     new Context(key1, value1)).forEach(
         shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName())
 );

List all shares including their snapshots and metadata

fileServiceClient.listShares(new ListSharesOptions().setIncludeMetadata(true)
     .setIncludeSnapshots(true), Duration.ofSeconds(1), new Context(key1, value1)).forEach(
         shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName())
 );

For more information, see the Azure Docs.

Parameters:

options - Options for listing shares. If iterating by page, the page size passed to byPage methods such as PagedIterable#iterableByPage(int) will be preferred over the value set on these options.

timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

ShareItem in the storage account that satisfy the filter requirements

public void setProperties(ShareServiceProperties properties)

Sets the properties for the storage account's File service. The properties range from storage analytics and metric to CORS (Cross-Origin Resource Sharing).

To maintain the CORS in the Share service pass a null value for getCors(). To disable all CORS in the Share service pass an empty list for getCors().

Code Sample

Clear CORS in the File service

ShareServiceProperties properties = fileServiceClient.getProperties();
 properties.setCors(Collections.emptyList());

 Response<Void> response = fileServiceClient.setPropertiesWithResponse(properties,
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting File service properties completed with status code %d", response.getStatusCode());

Enable Minute and Hour Metrics

ShareServiceProperties properties = fileServiceClient.getProperties();

 properties.getMinuteMetrics().setEnabled(true);
 properties.getHourMetrics().setEnabled(true);

 fileServiceClient.setProperties(properties);
 System.out.println("Setting File service properties completed.");

For more information, see the Azure Docs.

Parameters:

properties - Storage account File service properties

public Response<Void> setPropertiesWithResponse(ShareServiceProperties properties, Duration timeout, Context context)

Sets the properties for the storage account's File service. The properties range from storage analytics and metric to CORS (Cross-Origin Resource Sharing). To maintain the CORS in the Share service pass a null value for getCors(). To disable all CORS in the Share service pass an empty list for getCors().

Code Sample

Clear CORS in the File service

ShareServiceProperties properties = fileServiceClient.getProperties();
 properties.setCors(Collections.emptyList());

 Response<Void> response = fileServiceClient.setPropertiesWithResponse(properties,
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting File service properties completed with status code %d", response.getStatusCode());

Enable Minute and Hour Metrics

ShareServiceProperties properties = fileServiceClient.getPropertiesWithResponse(
     Duration.ofSeconds(1), new Context(key1, value1)).getValue();

 properties.getMinuteMetrics().setEnabled(true);
 properties.getHourMetrics().setEnabled(true);

 Response<Void> response = fileServiceClient.setPropertiesWithResponse(properties,
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting File service properties completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.

Parameters:

properties - Storage account File service properties

timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response that only contains headers and response status code

public ShareClient undeleteShare(String deletedShareName, String deletedShareVersion)

Restores a previously deleted share.

If the share associated with provided deletedShareName already exists, this call will result in a 409 (conflict).

This API is only functional if Share Soft Delete is enabled for the storage account associated with the share. For more information, see the Azure Docs.

Code Samples

ListSharesOptions listSharesOptions = new ListSharesOptions();
 listSharesOptions.setIncludeDeleted(true);
 fileServiceClient.listShares(listSharesOptions, Duration.ofSeconds(1), context).forEach(
     deletedShare -> {
         ShareClient shareClient = fileServiceClient.undeleteShare(
             deletedShare.getName(), deletedShare.getVersion());
     }
 );

For more information, see the Azure Docs.

Parameters:

deletedShareName - The name of the previously deleted share.

deletedShareVersion - The version of the previously deleted share.

Returns:

A ShareClient used to interact with the restored share.

public Response<ShareClient> undeleteShareWithResponse(String deletedShareName, String deletedShareVersion, Duration timeout, Context context)

Restores a previously deleted share.

If the share associated with provided deletedShareName already exists, this call will result in a 409 (conflict).

This API is only functional if Share Soft Delete is enabled for the storage account associated with the share. For more information, see the Azure Docs.

Code Samples

ListSharesOptions listSharesOptions = new ListSharesOptions();
 listSharesOptions.setIncludeDeleted(true);
 fileServiceClient.listShares(listSharesOptions, Duration.ofSeconds(1), context).forEach(
     deletedShare -> {
         ShareClient shareClient = fileServiceClient.undeleteShareWithResponse(
             deletedShare.getName(), deletedShare.getVersion(), Duration.ofSeconds(1), context).getValue();
     }
 );

For more information, see the Azure Docs.

Parameters:

deletedShareName - The name of the previously deleted share.

deletedShareVersion - The version of the previously deleted share.

timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A Response<T> whose value contains the ShareClient used to interact with the restored share.

Applies to

Opinia

Czy ta strona była pomocna?

Udostępnij za pośrednictwem

ShareServiceClient Class

Method Summary

Methods inherited from java.lang.Object

Method Details

createShare

createShareWithResponse

createShareWithResponse

deleteShare

deleteShareWithResponse

generateAccountSas

generateAccountSas

generateAccountSas

getAccountName

getFileServiceUrl

getHttpPipeline

getProperties

getPropertiesWithResponse

getServiceVersion

getShareClient

getUserDelegationKey

getUserDelegationKeyWithResponse

listShares

listShares

setProperties

setPropertiesWithResponse

undeleteShare

undeleteShareWithResponse

Applies to

Opinia