Criar e gerenciar objetos cliente que interagem com recursos de dados

Os SDKs do Azure são coleções de bibliotecas criadas para facilitar o uso dos serviços do Azure em diferentes linguagens. Os SDKs foram projetados para simplificar as interações entre seu aplicativo e os recursos do Azure. O trabalho com os recursos do Azure usando o SDK começa com a criação de uma instância cliente. Esse artigo mostra como criar objetos cliente para interagir com recursos de dados no Armazenamento de Blobs do Azure e oferece práticas recomendadas sobre como gerenciar os clientes no seu aplicativo.

Sobre objetos cliente

As bibliotecas de cliente do Armazenamento de Blobs do Azure permitem interagir com três tipos de recursos no serviço de armazenamento:

• Contas de armazenamento
• Contêineres de blob
• Blobs

Dependendo das necessidades do seu aplicativo, você pode criar objetos cliente em qualquer um desses três níveis.

Para blobs, há um cliente de blob geral que abrange as operações de blob comuns em todos os tipos e há clientes de blob especializados para cada tipo (blob de bloco, blob de acréscimo e blob de página).

A tabela a seguir lista as diferentes classes cliente para cada linguagem:

Linguagem	Pacotes	Serviço de classe cliente	Contêiner de classe cliente	Blob de classes cliente
.NET	Azure.Storage.Blobs Azure.Storage.Blobs.Models Azure.Storage.Blobs.Specialized	BlobServiceClient	BlobContainerClient	BlobClient BlockBlobClient AppendBlobClient PageBlobClient
Java	com.azure.storage.blob com.azure.storage.blob.models com.azure.storage.blob.specialized	BlobServiceClient BlobServiceAsyncClient BlobServiceClientBuilder	BlobContainerClient BlobContainerAsyncClient BlobContainerClientBuilder	BlobClient BlobAsyncClient BlobClientBuilder BlockBlobClient AppendBlobClient PageBlobClient
JavaScript	@azure/storage-blob	BlobServiceClient	ContainerClient	BlobClient BlockBlobClient AppendBlobClient PageBlobClient
Python	azure.storage.blob	BlobServiceClient	ContainerClient	BlobClient1

¹ Para Python, BlobClient inclui métodos para tipos de blob especializados.

Cada tipo de cliente pode ser instanciado chamando um construtor simples ou uma sobrecarga que leva várias opções de configuração. Para Java, cada tipo de cliente tem uma classe separada que fornece uma API de construção para ajudar na configuração e instanciação. Dependendo do SDK da linguagem, essas opções de configuração do cliente são passadas para o construtor de diferentes maneiras. Consulte a referência da classe na tabela para obter os detalhes.

Autorizar um objeto cliente

Para que um aplicativo acesse os recursos do blob e interaja com eles, um objeto cliente precisa ser autorizado. Os exemplos de código neste artigo utilizam DefaultAzureCredential para se autenticar no Azure por meio de uma entidade de segurança do Microsoft Entra. O processo de autenticação inclui a obtenção de um token de acesso para autorização. O token de acesso é passado como uma credencial quando o cliente é instanciado e a credencial persiste durante toda a vida do cliente. A entidade de segurança do Microsoft Entra que solicita o token deve receber uma função RBAC do Azure apropriada que conceda acesso a dados de blob. Para saber mais, confira Atribuir uma função do Azure para acesso aos dados do blob.

Os mecanismos de autorização a seguir podem ser utilizados para conceder o nível apropriado de acesso a um objeto cliente:

• Microsoft Entra ID: recomendado para uma segurança ideal
• Assinatura de acesso compartilhado (SAS): suportada e mais segura ao usar um token SAS de delegação do usuário
• Chave de acesso à conta (Chave Compartilhada): suportada, mas não recomendada, pois pode ser menos segura

Para saber mais sobre a autorização, confira Autorizar o acesso aos dados no Armazenamento do Microsoft Azure.

Criar um objeto cliente

O trabalho com qualquer recurso do Azure usando o SDK começa com a criação de um objeto cliente. Nesta seção, você aprenderá como criar objetos cliente para interagir com os três tipos de recursos no serviço de armazenamento: contas de armazenamento, contêineres e blobs.

Quando o aplicativo cria um objeto cliente, você passa um URI referenciando o ponto de extremidade para o construtor do cliente. Você pode construir a cadeia de caracteres do ponto de extremidade manualmente, conforme mostrado nos exemplos deste artigo, ou pode consultar o ponto de extremidade em runtime usando a biblioteca de gerenciamento do Armazenamento do Microsoft Azure. Para saber como consultar um ponto de extremidade, confira Consultar um ponto de extremidade do Armazenamento de Blobs.

Criar um objeto BlobServiceClient

Um objeto BlobServiceClient autorizado permite que seu aplicativo interaja com recursos no nível da conta de armazenamento. BlobServiceClient fornece métodos para recuperar e configurar as propriedades da conta, bem como listar, criar e excluir contêineres na conta de armazenamento. Esse objeto cliente é o ponto de partida para interagir com os recursos na conta de armazenamento.

Um cenário comum é instanciar um único cliente de serviço e, em seguida, criar clientes de contêiner e clientes de blob a partir do cliente de serviço, conforme necessário. Para trabalhar com um contêiner ou blob específico, você pode usar o objeto BlobServiceClient para criar um cliente de contêiner ou cliente de blob. Os clientes criados a partir de um BlobServiceClient herdarão sua configuração de cliente, incluindo as opções e credenciais de cliente.

Os exemplos a seguir mostram como criar um objeto BlobServiceClient:

.NET

Adicione as seguintes diretivas using:

using Azure.Identity;
using Azure.Storage.Blobs;

Adicione o código a seguir para criar o objeto cliente:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Java

Adicione as seguintes diretivas import:

import com.azure.identity.*;
import com.azure.storage.blob.*;

Adicione o código a seguir para criar o objeto cliente:

public BlobServiceClient GetBlobServiceClient(String accountName) {
    String endpointString = String.format("https://%s.blob.core.windows.net", accountName);
    BlobServiceClient client = new BlobServiceClientBuilder()
            .endpoint(endpointString)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();

    return client;
}

JavaScript

Adicione as seguintes declarações de require :

const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');

Adicione o código a seguir para criar o objeto cliente:

const accountName = "<storage-account-name>";

const blobServiceClient = new BlobServiceClient(
    `https://${accountName}.blob.core.windows.net`,
    new DefaultAzureCredential()
);

Python

Adicione as seguintes declarações de import :

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

Adicione o código a seguir para criar o objeto cliente:

def get_blob_service_client(self, account_name):
    account_url = f"https://{account_name}.blob.core.windows.net"
    credential = DefaultAzureCredential()

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

Criar um objeto BlobContainerClient

Você pode utilizar um objeto BlobServiceClient para criar um novo objeto BlobContainerClient (ContainerClient para JavaScript e Python). Um objeto BlobContainerClient permite interagir com um recurso de contêiner específico. Esse recurso não precisa existir na conta de armazenamento para que você possa criar o objeto cliente. BlobContainerClient fornece métodos para criar, excluir ou configurar um contêiner e inclui métodos para listar, carregar e excluir os blobs dentro dele. Para executar operações em um blob específico dentro do contêiner, você pode criar um cliente de blob.

Os exemplos a seguir mostram como criar um cliente de contêiner a partir de um objeto BlobServiceClient para interagir com um recurso de contêiner específico:

.NET

public BlobContainerClient GetBlobContainerClient(
    BlobServiceClient blobServiceClient,
    string containerName)
{
    // Create the container client using the service client object
    BlobContainerClient client = blobServiceClient.GetBlobContainerClient(containerName);
    return client;
}

Java

public BlobContainerClient getBlobContainerClient(
        BlobServiceClient blobServiceClient,
        String containerName) {
    // Create the container client using the service client object
    BlobContainerClient client = blobServiceClient.getBlobContainerClient(containerName);
    return client;
}

JavaScript

const containerName = "sample-container";
let containerClient = blobServiceClient.getContainerClient(containerName);

Python

def get_blob_container_client(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)
    return container_client

Se seu trabalho tiver um escopo restrito a um único contêiner, você pode optar por criar um objeto BlobContainerClient diretamente sem usar o BlobServiceClient. Você ainda pode definir as opções do cliente em um cliente de contêiner, da mesma forma que faria em um cliente de serviço.

Os exemplos a seguir mostram como criar um cliente de contêiner diretamente sem usando BlobServiceClient:

.NET

public BlobContainerClient GetBlobContainerClient(
    string accountName,
    string containerName,
    BlobClientOptions clientOptions)
{
    // Append the container name to the end of the URI
    BlobContainerClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net/{containerName}"),
        new DefaultAzureCredential(),
        clientOptions);

    return client;
}

Java

public BlobContainerClient getBlobContainerClient(
        String accountName,
        String containerName) {
    // Append the container name to the URI
    String endpointString = String.format("https://%s.blob.core.windows.net/%s",
            accountName, containerName);

    BlobContainerClient client = new BlobContainerClientBuilder()
            .endpoint(endpointString)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();

    return client;
}

JavaScript

const accountName = "<storage-account-name>";
const containerName = "sample-container";

// Append the container name to the URI
const containerClient = new ContainerClient(
    `https://${accountName}.blob.core.windows.net/${containerName}`,
    new DefaultAzureCredential()

Python

def get_blob_container_client(self, account_name, container_name):
    # Append the container name to the URI
    account_url = f"https://{account_name}.blob.core.windows.net/{container_name}"
    credential = DefaultAzureCredential()

    # Create the client object
    container_client = ContainerClient(account_url, credential=credential)

    return container_client

Criar um objeto BlobClient

Para interagir com um recurso de blob específico, crie um objeto BlobClient a partir de um cliente de serviço ou cliente de contêiner. Um objeto BlobClient permite que você interaja com um recurso de blob específico. Esse recurso não precisa existir na conta de armazenamento para que você possa criar o objeto cliente. BlobClient fornece métodos para carregar, baixar, excluir e criar instantâneos de um blob.

Os exemplos a seguir mostram como criar um cliente de blob para interagir com um recurso de blob específico:

.NET

public BlobClient GetBlobClient(
    BlobServiceClient blobServiceClient,
    string containerName,
    string blobName)
{
    BlobClient client =
        blobServiceClient.GetBlobContainerClient(containerName).GetBlobClient(blobName);
    return client;
}

Java

public BlobClient getBlobClient(
        BlobServiceClient blobServiceClient,
        String containerName,
        String blobName) {
    // Create a blob client using the service client object
    BlobClient client = blobServiceClient.getBlobContainerClient(containerName).getBlobClient(blobName);
    return client;
}

JavaScript

const containerName = "sample-container";
const blobName = "sample-blob";
let blobClient = blobServiceClient.getContainerClient(containerName).getBlobClient(blobName);

Python

def get_blob_client(self, blob_service_client: BlobServiceClient, container_name, blob_name):
    # Create a blob client using the service client object
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    return blob_client

Gerenciar objetos cliente

Uma prática recomendada para o gerenciamento de clientes do SDK do Azure é tratar um cliente como um singleton, o que significa que uma classe terá apenas um objeto de cada vez. Não há necessidade de manter mais de uma instância de um cliente para um determinado conjunto de parâmetros do construtor ou opções do cliente. Esse conceito pode ser implementado de várias maneiras, incluindo:

• Criando um único objeto cliente e passando-o como um parâmetro em todo o aplicativo. Essa abordagem é mostrada nos exemplos de código neste artigo.
• Armazenar uma instância cliente em um campo. Para saber mais sobre os campos C#, confira Campos (Guia de Programação C#).
• Registrando o objeto cliente como um singleton em um contêiner de injeção de dependência de sua escolha. Para obter mais informações sobre a injeção de dependência em aplicativos ASP.NET Core, consulte Injeção de dependência com o SDK do Azure para .NET.

Essa abordagem é muito mais eficiente em escala do que chamar um construtor para cada cliente que você precisar.

Imutabilidade do cliente e acesso thread-safe

Os clientes SDK do Azure são imutáveis após serem criados, o que significa que você não pode alterar o ponto de extremidade ao qual ele se conecta, a credencial usada para autorização ou outros valores passados como opções do cliente. A imutabilidade do cliente também significa que os clientes estão seguros para compartilhar e reutilizar em todo o aplicativo.

Se seu aplicativo precisar usar diferentes configurações ou credenciais para clientes do mesmo tipo, você pode instanciar um cliente para cada conjunto de opções de configuração.

O SDK do Azure garante que todos os métodos da instância cliente sejam thread-safes e independentes uns dos outros. Esse design garante que o compartilhamento e a reutilização de instâncias cliente sejam sempre seguras, mesmo entre threads.

Próximas etapas

Para saber mais sobre como usar as bibliotecas cliente do Armazenamento do Microsoft Azure para trabalhar com recursos de dados, confira os seguintes artigos:

• Introdução ao Armazenamento de Blobs do Azure e .NET
• Introdução ao Armazenamento de Blobs do Azure e ao Java
• Introdução ao Armazenamento de Blobs do Azure e ao JavaScript
• Introdução ao Armazenamento de Blobs do Azure e ao Python