Biblioteca de clientes do Blob de Armazenamento do Azure para Java – versão 12.24.1

Artigo
10/25/2023

O Armazenamento de Blobs do Azure é uma solução de armazenamento de objetos da Microsoft para a nuvem. O Armazenamento de Blobs é otimizado para armazenar grandes quantidades de dados não estruturados. Dados não estruturados são dados que não estão de acordo com uma definição ou um modelo de dados específico, como texto ou dados binários.

Código-fonte | Documentação | de referência da APIDocumentação | da API REST Documentação do produto | Amostras

Introdução

Pré-requisitos

JDK (Java Development Kit) com a versão 8 ou superior
Assinatura do Azure
Criar conta de armazenamento

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente na BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.24.1</version>
</dependency>

Criar uma conta de armazenamento

Para criar uma Conta de Armazenamento, você pode usar o Portal do Azure ou a CLI do Azure.

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

A URL da conta de armazenamento, posteriormente identificada como <your-storage-account-url>, seria formatada da seguinte maneira: http(s)://<storage-account-name>.blob.core.windows.net

Autenticar o cliente

Para interagir com o Serviço de Armazenamento (Blob, Fila, Mensagem, MessageId, Arquivo), você precisará criar uma instância da classe Cliente de Serviço. Para tornar isso possível, você precisará da cadeia de caracteres SAS da conta (assinatura de acesso compartilhado) da Conta de Armazenamento. Saiba mais em Token SAS.

Obter credenciais

Token SAS

a. Use o snippet da CLI do Azure abaixo para obter o token SAS da Conta de Armazenamento.

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

Exemplo:

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. Como alternativa, obtenha o token SAS da conta no Portal do Azure.

Vá para sua conta de armazenamento
Selecione Shared access signature no menu à esquerda
Clique em Generate SAS and connection string (após a instalação)

Credencial de chave compartilhada

a. Use o Nome da conta e a Chave de conta. O nome da conta é o nome da conta de armazenamento.

Vá para sua conta de armazenamento
Selecione Access keys no menu à esquerda
Em key1/key2 copiar o conteúdo do Key campo

b. Use o cadeia de conexão.

Vá para sua conta de armazenamento
Selecione Access keys no menu à esquerda
Em key1/key2 copiar o conteúdo do Connection string campo

Principais conceitos

O Armazenamento de Blobs foi projetado para:

Fornecer imagens ou documentos diretamente a um navegador
O armazenamento de arquivos para acesso distribuído
Transmitir áudio e vídeo por streaming
Gravando em arquivos de log
O armazenamento de dados para backup e restauração, recuperação de desastre e arquivamento
O armazenamento de dados para análise por um serviço local ou hospedado no Azure

Formato de URL

Os blobs são endereçáveis usando o seguinte formato de URL: a seguinte URL aborda um blob:

https://myaccount.blob.core.windows.net/mycontainer/myblob

Sintaxe do URI de recurso

Para a conta de armazenamento, o URI base para operações de blob inclui apenas o nome da conta:

https://myaccount.blob.core.windows.net

Para um contêiner, o URI base inclui o nome da conta e o nome do contêiner:

https://myaccount.blob.core.windows.net/mycontainer

Para um blob, o URI base inclui o nome da conta, o nome do contêiner e o nome do blob:

https://myaccount.blob.core.windows.net/mycontainer/myblob

Observe que os URIs acima podem não conter cenários mais avançados, como nomes de domínio personalizados.

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Blob de Armazenamento do Azure, incluindo:

Criar um BlobServiceClient
Criar um BlobContainerClient
Criar um BlobClient
Criar um contêiner
Carregar dados em um blob
Carregar um blob de um fluxo
Carregar um blob do caminho local
Carregar um blob se ainda não existir um
Carregar um blob e substituir se já existir um
Carregar um blob por meio de um OutputStream
Baixar dados de um blob
Baixar um blob em um fluxo
Baixar um blob para o caminho local
Ler um blob por meio de um InputStream
Enumerar blobs
Copiar um blob
Gerar um token SAS
Autenticar com a Identidade do Azure
Definir um proxy ao criar um cliente

Criar um `BlobServiceClient`

Crie um BlobServiceClient usando o sasToken gerado acima.

BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

Criar um `BlobContainerClient`

Crie um BlobContainerClient usando um BlobServiceClient.

BlobContainerClient blobContainerClient = blobServiceClient.getBlobContainerClient("mycontainer");

Crie um BlobContainerClient do construtor sasToken gerado acima.

BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .containerName("mycontainer")
    .buildClient();

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "mycontainer" + "?" + "<your-sasToken>")
    .buildClient();

Criar um `BlobClient`

Crie um BlobClient usando um BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblob");

Crie um BlobClient do construtor sasToken gerado acima.

BlobClient blobClient = new BlobClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .containerName("mycontainer")
    .blobName("myblob")
    .buildClient();

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobClient blobClient = new BlobClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "mycontainer" + "/" + "myblob" + "?" + "<your-sasToken>")
    .buildClient();

Criar um contêiner

Crie um contêiner usando um BlobServiceClient.

blobServiceClient.createBlobContainer("mycontainer");

Crie um contêiner usando um BlobContainerClient.

blobContainerClient.create();

Carregar dados em um blob

Carregue BinaryData em um blob usando um BlobClient gerado de um BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
String dataSample = "samples";
blobClient.upload(BinaryData.fromString(dataSample));

Carregar um blob de um fluxo

Carregue de um InputStream para um blob usando um BlockBlobClient gerado de um BlobContainerClient.

BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("myblockblob").getBlockBlobClient();
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blockBlobClient.upload(dataStream, dataSample.length());
} catch (IOException e) {
    e.printStackTrace();
}

Carregar um blob do caminho local

Carregue um arquivo em um blob usando um BlobClient gerado de um BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
blobClient.uploadFromFile("local-file.jpg");

Carregar um blob se ainda não existir um

Carregue dados em um blob e falhe se já existir um.

/*
 * Rather than use an if block conditioned on an exists call, there are three ways to upload-if-not-exists using
 * one network call instead of two. Equivalent options are present on all upload methods.
 */
// 1. The minimal upload method defaults to no overwriting
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length());
} catch (IOException e) {
    e.printStackTrace();
}

// 2. The overwrite flag can explicitly be set to false to make intention clear
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length(), false /* overwrite */);
} catch (IOException e) {
    e.printStackTrace();
}

// 3. If the max overload is needed, access conditions must be used to prevent overwriting
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    // Setting IfNoneMatch="*" ensures the upload will fail if there is already a blob at the destination.
    options.setRequestConditions(new BlobRequestConditions().setIfNoneMatch("*"));
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

Carregar um blob e substituir se já existir um

Carregue dados em um blob e substitua todos os dados existentes no destino.

/*
 * Rather than use an if block conditioned on an exists call, there are three ways to upload-if-exists in one
 * network call instead of two. Equivalent options are present on all upload methods.
 */
String dataSample = "samples";

// 1. The overwrite flag can explicitly be set to true. This will succeed as a create and overwrite.
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length(), true /* overwrite */);
} catch (IOException e) {
    e.printStackTrace();
}

/*
 * 2. If the max overload is needed and no access conditions are passed, the upload will succeed as both a
 * create and overwrite.
 */
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

/*
 * 3. If the max overload is needed, access conditions may be used to assert that the upload is an overwrite and
 * not simply a create.
 */
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    // Setting IfMatch="*" ensures the upload will succeed only if there is already a blob at the destination.
    options.setRequestConditions(new BlobRequestConditions().setIfMatch("*"));
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

Carregar um blob por meio de um `OutputStream`

Carregue um blob abrindo um BlobOutputStream e gravando nele por meio de APIs de fluxo padrão.

/*
 * Opening a blob input stream allows you to write to a blob through a normal stream interface. It will not be
 * committed until the stream is closed.
 * This option is convenient when the length of the data is unknown.
 * This can only be done for block blobs. If the target blob already exists as another type of blob, it will
 * fail.
 */
try (BlobOutputStream blobOS = blobClient.getBlockBlobClient().getBlobOutputStream()) {
    blobOS.write(new byte[0]);
} catch (IOException e) {
    e.printStackTrace();
}

Baixar dados de um blob

Baixe um blob em um OutputStream usando um BlobClient.

BinaryData content = blobClient.downloadContent();

Baixar um blob em um fluxo

Baixe um blob em um OutputStream usando um BlobClient.

try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
    blobClient.downloadStream(outputStream);
} catch (IOException e) {
    e.printStackTrace();
}

Baixar um blob para o caminho local

Baixe o blob em um arquivo local usando um BlobClient.

blobClient.downloadToFile("downloaded-file.jpg");

Ler um blob por meio de um `InputStream`

Baixe um blob abrindo um BlobInputStream e lendo-o por meio de APIs de fluxo padrão.

/*
 * Opening a blob input stream allows you to read from a blob through a normal stream interface. It is also
 * mark-able.
*/
try (BlobInputStream blobIS = blobClient.openInputStream()) {
    blobIS.read();
} catch (IOException e) {
    e.printStackTrace();
}

Enumerar blobs

Enumerando todos os blobs usando um BlobContainerClient.

for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("This is the blob name: " + blobItem.getName());
}

Enumerar todos os blobs e criar novos clientes apontando para os itens.

for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    BlobClient blobClient;
    if (blobItem.getSnapshot() != null) {
        blobClient = blobContainerClient.getBlobClient(blobItem.getName(), blobItem.getSnapshot());
    } else {
        blobClient = blobContainerClient.getBlobClient(blobItem.getName());
    }
    System.out.println("This is the new blob uri: " + blobClient.getBlobUrl());
}

Copiar um blob

Copiando um blob. Consulte os javadocs em cada um desses métodos para obter mais informações sobre os requisitos sobre a origem da cópia e sua autenticação.

SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<url-to-blob>", Duration.ofSeconds(1));
poller.waitForCompletion();

blobClient.copyFromUrl("url-to-blob");

Gerar um token SAS

Use uma instância de um cliente para gerar um novo token SAS.

/*
 * Generate an account sas. Other samples in this file will demonstrate how to create a client with the sas
 * token.
 */
// Configure the sas parameters. This is the minimal set.
OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);
AccountSasPermission accountSasPermission = new AccountSasPermission().setReadPermission(true);
AccountSasService services = new AccountSasService().setBlobAccess(true);
AccountSasResourceType resourceTypes = new AccountSasResourceType().setObject(true);

// Generate the account sas.
AccountSasSignatureValues accountSasValues =
    new AccountSasSignatureValues(expiryTime, accountSasPermission, services, resourceTypes);
String sasToken = blobServiceClient.generateAccountSas(accountSasValues);

// Generate a sas using a container client
BlobContainerSasPermission containerSasPermission = new BlobContainerSasPermission().setCreatePermission(true);
BlobServiceSasSignatureValues serviceSasValues =
    new BlobServiceSasSignatureValues(expiryTime, containerSasPermission);
blobContainerClient.generateSas(serviceSasValues);

// Generate a sas using a blob client
BlobSasPermission blobSasPermission = new BlobSasPermission().setReadPermission(true);
serviceSasValues = new BlobServiceSasSignatureValues(expiryTime, blobSasPermission);
blobClient.generateSas(serviceSasValues);

Autenticar com a Identidade do Azure

A biblioteca de Identidade do Azure fornece suporte ao Azure Active Directory para autenticação com o Armazenamento do Azure.

BlobServiceClient blobStorageClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Definir um proxy ao criar um cliente

ProxyOptions options = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 888));
BlobServiceClient client = new BlobServiceClientBuilder()
    .httpClient(new NettyAsyncHttpClientBuilder().proxy(options).build())
    .buildClient();

Permitir que o construtor de cliente determine o HttpClient tipo a ser usado, mas construa-o com configurações passadas.

HttpClientOptions clientOptions = new HttpClientOptions()
    .setProxyOptions(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 888)));
BlobServiceClient client = new BlobServiceClientBuilder()
    .clientOptions(clientOptions)
    .buildClient();

Solução de problemas

Ao interagir com blobs usando essa biblioteca de clientes Java, os erros retornados pelo serviço correspondem aos mesmos códigos de status HTTP retornados para solicitações da API REST. Por exemplo, se você tentar recuperar um contêiner ou blob que não existe em sua Conta de Armazenamento, um 404 erro será retornado, indicando Not Found.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL é um uber jar que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

Vários exemplos do SDK do Java de blob de armazenamento estão disponíveis para você no repositório GitHub do SDK. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com Key Vault:

Exemplos das próximas etapas

Os exemplos são explicados em detalhes aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Compartilhar via