Compartilhar via


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

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 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:

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:

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

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:

public BlobContainerClient GetBlobContainerClient(
    BlobServiceClient blobServiceClient,
    string containerName)
{
    // Create the container client using the service client object
    BlobContainerClient client = blobServiceClient.GetBlobContainerClient(containerName);
    return 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:

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

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:

public BlobClient GetBlobClient(
    BlobServiceClient blobServiceClient,
    string containerName,
    string blobName)
{
    BlobClient client =
        blobServiceClient.GetBlobContainerClient(containerName).GetBlobClient(blobName);
    return 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: