Skip to content

Latest commit

 

History

History
167 lines (127 loc) · 6.28 KB

README.md

File metadata and controls

167 lines (127 loc) · 6.28 KB
Raw

Azure Storage Blobs Cryptography client library for Java

Azure Blob storage is Microsoft's object storage solution for the cloud. Blob storage is optimized for storing massive amounts of unstructured data. Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. This package supports client side encryption for blob storage.

Getting started

Prerequisites

  • Java Development Kit (JDK) with version 8 or above
  • [Azure Subscription][azure_subscription]
  • [Create Storage Account][storage_account]

Adding the package to your product

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob-cryptography</artifactId>
  <version>12.0.0-preview.5</version>
</dependency>

Default HTTP Client

All client libraries, by default, use Netty HTTP client. Adding the above dependency will automatically configure Storage Blob to use Netty HTTP client.

Alternate HTTP client

If, instead of Netty it is preferable to use OkHTTP, there is a HTTP client available for that too. Exclude the default Netty and include OkHTTP client in your pom.xml.

<!-- Add Storage Blob cryptography dependency without Netty HTTP client -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.0.0-preview.5</version>
    <exclusions>
      <exclusion>
        <groupId>com.azure</groupId>
        <artifactId>azure-core-http-netty</artifactId>
      </exclusion>
    </exclusions>
</dependency>
<!-- Add OkHTTP client to use with Storage Blob -->
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-okhttp</artifactId>
  <version>1.0.0</version>
</dependency>

Configuring HTTP Clients

When an HTTP client is included on the classpath, as shown above, it is not necessary to specify it in the client library builders, unless you want to customize the HTTP client in some fashion. If this is desired, the httpClient builder method is often available to achieve just this, by allowing users to provide a custom (or customized) com.azure.core.http.HttpClient instances.

For starters, by having the Netty or OkHTTP dependencies on your classpath, as shown above, you can create new instances of these HttpClient types using their builder APIs. For example, here is how you would create a Netty HttpClient instance:

HttpClient client = new NettyAsyncHttpClientBuilder()
    .port(8080)
    .wiretap(true)
    .build();

Create a Storage Account

To create a Storage Account you can use the Azure Portal or [Azure CLI][storage_account_create_cli].

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Authenticate the client

In order to interact with the Storage service (Blob, Queue, Message, MessageId, File) you'll need to create an instance of the Service Client class. To make this possible you'll need the Account SAS (shared access signature) string of Storage account. Learn more at [SAS Token][sas_token]

Get credentials

  • SAS Token

a. Use the [Azure CLI][azure_cli] snippet below to get the SAS token from the Storage account.

az storage blob generate-sas
    --name {queue name}
    --expiry {date/time to expire SAS token}
    --permission {permission to grant}
    --connection-string {connection string of the storage account}
    --services {storage services the SAS allows}
    --resource-types {resource types the SAS allows}
CONNECTION_STRING=<connection-string>

az storage blob generate-sas
    --name javasdksas
    --expiry 2019-06-05
    --permission rpau
    --connection-string $CONNECTION_STRING

b. Alternatively, get the Account SAS Token from the Azure Portal.

Go to your storage account -> Shared access signature -> Click on Generate SAS and connection string (after setup)
  • Shared Key Credential

a. Use account name and account key. Account name is your storage account name.

// Here is where we get the key
Go to your storage account -> Access keys -> Key 1/ Key 2 -> Key

b. Use the connection string

// Here is where we get the key
Go to your storage account -> Access Keys -> Keys 1/ Key 2 -> Connection string

Key concepts

Blob storage is designed for:

  • Serving images or documents directly to a browser.
  • Storing files for distributed access.
  • Streaming video and audio.
  • Writing to log files.
  • Storing data for backup and restore, disaster recovery, and archiving.
  • Storing data for analysis by an on-premises or Azure-hosted service.

Examples

Troubleshooting

When interacting with blobs using this Java client library, errors returned by the service correspond to the same HTTP status codes returned for [REST API][error_codes] requests. For example, if you try to retrieve a container or blob that doesn't exist in your Storage Account, a 404 error is returned, indicating Not Found.

Next steps

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Impressions