Criar e gerenciar objetos de 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 de diferentes idiomas. Os SDKs são projetados para simplificar as interações entre seu aplicativo e os recursos do Azure. O trabalho com recursos do Azure usando o SDK começa com a criação de uma instância de cliente. Este artigo mostra como criar objetos de cliente para interagir com recursos de dados no Armazenamento de Blobs do Azure e oferece práticas recomendadas sobre como gerenciar clientes em seu aplicativo.

Sobre objetos de cliente

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

• Contas de armazenamento
• Contentores de blobs
• 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 cobre 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 de cliente para cada idioma:

1 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 usa várias opções de configuração. Para Java, cada tipo de cliente tem uma classe separada que fornece uma API de construtor para ajudar com a 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 maneiras diferentes. Consulte a referência de classe da tabela para obter detalhes.

Autorizar um objeto de cliente

Para que um aplicativo acesse recursos de blob e interaja com eles, um objeto cliente deve ser autorizado. Os exemplos de código neste artigo usam DefaultAzureCredential para 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. Esse token de acesso é passado como uma credencial quando o cliente é instanciado e a credencial persiste durante todo o tempo de 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 aos dados de blob. Para saber mais, consulte Atribuir uma função do Azure para acesso a dados de blob.

Os seguintes mecanismos de autorização podem ser usados 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 de usuário
• Chave de acesso à conta (Chave Partilhada): suportada, mas não recomendada, pois pode ser menos segura

Para saber mais sobre autorização, consulte Autorizar acesso a dados no Armazenamento do 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á a criar objetos de cliente para interagir com os três tipos de recursos no serviço de armazenamento: contas de armazenamento, contêineres e blobs.

Quando seu aplicativo cria um objeto cliente, você passa um URI fazendo referência ao ponto de extremidade para o construtor cliente. Você pode construir a cadeia de caracteres de ponto de extremidade manualmente, conforme mostrado nos exemplos deste artigo, ou pode consultar o ponto de extremidade em tempo de execução usando a biblioteca de gerenciamento de Armazenamento do Azure. Para saber como consultar um ponto de extremidade, consulte Consultar um ponto de extremidade de armazenamento de Blob.

Criar um objeto BlobServiceClient

Um objeto autorizado BlobServiceClient permite que seu aplicativo interaja com recursos no nível da conta de armazenamento. BlobServiceClient Fornece métodos para recuperar e configurar propriedades de conta, bem como listar, criar e excluir contêineres dentro da conta de armazenamento. Este objeto de cliente é o ponto de partida para interagir com 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 BlobServiceClient objeto 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 opções e credenciais do cliente.

Os exemplos a seguir mostram como criar um BlobServiceClient objeto:

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

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

    return client;
}

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

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;
}

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

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

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

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

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 usar um objeto para criar um BlobServiceClient novo BlobContainerClient objeto (ContainerClient para JavaScript e Python). Um BlobContainerClient objeto permite que você interaja com um recurso de contêiner específico. Esse recurso não precisa existir na conta de armazenamento para você 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 para interagir com um BlobServiceClient recurso de contêiner específico:

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

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

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

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 o seu trabalho tiver um escopo restrito a um único contêiner, você poderá optar por criar um BlobContainerClient objeto diretamente sem usar BlobServiceCliento . Você ainda pode definir opções de 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 usar BlobServiceClient:

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;
}

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;
}

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()

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 a partir de um BlobClient cliente de serviço ou cliente de contêiner. Um BlobClient objeto permite que você interaja com um recurso de blob específico. Esse recurso não precisa existir na conta de armazenamento para você 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:

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

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;
}

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

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 de 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. Este conceito pode ser implementado de várias formas, incluindo:

• Criar um único objeto cliente e passá-lo como um parâmetro em todo o aplicativo. Essa abordagem é mostrada nos exemplos de código neste artigo.
• Armazenando uma instância de cliente em um campo. Para saber mais sobre campos C#, consulte Campos (Guia de Programação em 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ê precisa.

Imutabilidade do cliente e segurança da rosca

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

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

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

Próximos passos

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

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