Introdução ao Armazenamento de Blobs do Azure e Java

Artigo
01/19/2024

Este artigo mostra como se conectar ao Armazenamento de Blobs do Azure usando a biblioteca de cliente do Armazenamento de Blobs do Azure para Java. Uma vez conectado, seu código pode operar em contêineres, blobs e recursos do serviço de Armazenamento de Blobs.

Pacote de referência | da API (Maven) | Exemplos de código-fonte | da | biblioteca Dar feedback

Pré-requisitos

Subscrição do Azure - crie uma gratuitamente
Conta de armazenamento do Azure - criar uma conta de armazenamento
Java Development Kit (JDK) versão 8 ou superior
O Apache Maven é usado para gerenciamento de projetos neste exemplo

Configure o seu projeto

Nota

Este artigo usa a ferramenta de compilação Maven para criar e executar o código de exemplo. Outras ferramentas de compilação, como o Gradle, também funcionam com o SDK do Azure para Java.

Use o Maven para criar um novo aplicativo de console ou abrir um projeto existente. Siga estas etapas para instalar pacotes e adicionar as diretivas necessárias import .

Instalar pacotes

Abra o arquivo no editor de pom.xml texto. Instale os pacotes incluindo o arquivo BOM ou incluindo uma dependência direta.

Incluir o arquivo BOM

Adicione azure-sdk-bom para depender da versão mais recente da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número da versão. Usar azure-sdk-bom evita que você precise especificar a versão de cada dependência individual. Para saber mais sobre a lista técnica, consulte o Leiame da lista técnica 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>

Adicione os seguintes elementos de dependência ao grupo de dependências. A dependência azure-identity é necessária para conexões sem senha com os serviços do Azure.

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

Incluir uma dependência direta

Para assumir a dependência de uma versão específica da biblioteca, adicione a dependência direta ao seu projeto:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>{package_version_to_target}</version>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
      <version>{package_version_to_target}</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{package_version_to_target}</version>
</dependency>

Incluir diretivas de importação

Em seguida, abra o arquivo de código e adicione as diretivas necessárias import . Neste exemplo, adicionamos as seguintes diretivas no arquivo App.java :

import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.specialized.*;
import com.azure.storage.common.*;

Informações da biblioteca do cliente Blob:

com.azure.storage.blob: contém as classes primárias (objetos de cliente) que você pode usar para operar no serviço, contêineres e blobs.
com.azure.storage.blob.models: contém classes de utilitários, estruturas e tipos de enumeração.
com.azure.storage.blob.specialized: contém classes que você pode usar para executar operações específicas de um tipo de blob (por exemplo: acrescentar blobs).

Autorize o acesso e conecte-se ao Armazenamento de Blobs

Para conectar um aplicativo ao Armazenamento de Blob, crie uma instância da classe BlobServiceClient . Você também pode usar a classe BlobServiceAsyncClient para programação assíncrona. Este objeto é o seu ponto de partida para interagir com recursos de dados no nível da conta de armazenamento. Você pode usá-lo para operar na conta de armazenamento e seus contêineres. Você também pode usar o cliente de serviço para criar clientes de contêiner ou clientes de blob, dependendo do recurso com o qual você precisa trabalhar.

Para saber mais sobre como criar e gerenciar objetos de cliente, consulte Criar e gerenciar objetos de cliente que interagem com recursos de dados.

Você pode autorizar um objeto usando um BlobServiceClient token de autorização do Microsoft Entra, uma chave de acesso de conta ou uma assinatura de acesso compartilhado (SAS).

Para autorizar com o Microsoft Entra ID, você precisará usar uma entidade de segurança. O tipo de entidade de segurança de que você precisa depende de onde seu aplicativo é executado. Use a tabela a seguir como guia:

Onde o aplicativo é executado	Principal de segurança	Orientação
Máquina local (desenvolvimento e testes)	Service principal (Principal de serviço)	Para saber como registrar o aplicativo, configurar um grupo do Microsoft Entra, atribuir funções e configurar variáveis de ambiente, consulte Autorizar acesso usando entidades de serviço de desenvolvedor.
Máquina local (desenvolvimento e testes)	Identidade do utilizador	Para saber como configurar um grupo do Microsoft Entra, atribuir funções e entrar no Azure, consulte Autorizar acesso usando credenciais de desenvolvedor.
Hospedado no Azure	Identidade gerida	Para saber como habilitar a identidade gerenciada e atribuir funções, consulte Autorizar o acesso de aplicativos hospedados no Azure usando uma identidade gerenciada.
Hospedado fora do Azure (por exemplo, aplicativos locais)	Service principal (Principal de serviço)	Para saber como registrar o aplicativo, atribuir funções e configurar variáveis de ambiente, consulte Autorizar acesso de aplicativos locais usando uma entidade de serviço de aplicativo

Autorizar o acesso usando DefaultAzureCredential

Uma maneira fácil e segura de autorizar o acesso e se conectar ao Armazenamento de Blob é obter um token OAuth criando uma instância DefaultAzureCredential . Em seguida, você pode usar essa credencial para criar um objeto BlobServiceClient .

Verifique se você tem as dependências corretas no pom.xml e as diretivas de importação necessárias, conforme descrito em Configurar seu projeto.

O exemplo a seguir usa BlobServiceClientBuilder para criar um BlobServiceClient objeto usando DefaultAzureCredential:

public static BlobServiceClient GetBlobServiceClientTokenCredential() {
    TokenCredential credential = new DefaultAzureCredentialBuilder().build();

    // Azure SDK client builders accept the credential as a parameter
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .credential(credential)
            .buildClient();

    return blobServiceClient;
}

Use BlobServiceClientBuilder para criar um objeto BlobServiceClient usando um token SAS:

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .sasToken(sasToken)
            .buildClient();

    return blobServiceClient;
}

Para saber mais sobre como gerar e gerenciar tokens SAS, consulte os seguintes artigos:

Crie um StorageSharedKeyCredential usando o nome da conta de armazenamento e a chave da conta. Em seguida, use esse objeto para inicializar um objeto BlobServiceClient .

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Azure SDK client builders accept the credential as a parameter
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))
            .credential(credential)
            .buildClient();

    return blobServiceClient;        
}

Você também pode criar um BlobServiceClient objeto usando uma cadeia de conexão.

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {
    // Azure SDK client builders accept the credential as a parameter
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .connectionString(connectionString)
            .buildClient();

    return blobServiceClient;        
}

Para obter informações sobre como obter chaves de conta e diretrizes de práticas recomendadas para gerenciar e proteger adequadamente suas chaves, consulte Gerenciar chaves de acesso de conta de armazenamento.

Importante

A chave de acesso à conta deve ser usada com cuidado. Se a chave de acesso da sua conta for perdida ou acidentalmente colocada num local inseguro, o seu serviço poderá ficar vulnerável. Qualquer pessoa que tenha a chave de acesso é capaz de autorizar solicitações contra a conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential fornece recursos e benefícios de segurança aprimorados e é a abordagem recomendada para gerenciar a autorização para serviços do Azure.

Compilar a aplicação

À medida que você cria aplicativos para trabalhar com recursos de dados no Armazenamento de Blobs do Azure, seu código interage principalmente com três tipos de recursos: contas de armazenamento, contêineres e blobs. Para saber mais sobre esses tipos de recursos, como eles se relacionam entre si e como os aplicativos interagem com os recursos, consulte Compreender como os aplicativos interagem com os recursos de dados do Armazenamento de Blobs.

Os guias a seguir mostram como trabalhar com recursos de dados e executar ações específicas usando a biblioteca de cliente do Armazenamento do Azure para Java:

Guia	Description
Criar um contêiner	Crie contêineres.
Excluir e restaurar contêineres	Exclua contêineres e, se a exclusão suave estiver habilitada, restaure os contêineres excluídos.
Listar contêineres	Liste contêineres em uma conta e as várias opções disponíveis para personalizar uma listagem.
Gerenciar propriedades e metadados (contêineres)	Obtenha e defina propriedades e metadados para contêineres.
Criar e gerenciar concessões de contêiner	Estabeleça e gerencie um bloqueio em um contêiner.
Criar e gerenciar concessões de blob	Estabeleça e gerencie um bloqueio em um blob.
Carregar blobs	Saiba como carregar blobs usando cadeias de caracteres, fluxos, caminhos de arquivo e outros métodos.
Baixar blobs	Baixe blobs usando cadeias de caracteres, fluxos e caminhos de arquivo.
Copiar blobs	Copie um blob de um local para outro.
Listar blobs	Liste blobs de maneiras diferentes.
Excluir e restaurar	Exclua blobs e, se a exclusão suave estiver habilitada, restaure os blobs excluídos.
Localizar blobs usando tags	Defina e recupere tags, bem como use tags para encontrar blobs.
Gerenciar propriedades e metadados (blobs)	Obtenha e defina propriedades e metadados para blobs.
Definir ou alterar a camada de acesso de um blob	Defina ou altere a camada de acesso para um blob de bloco.

Share via