Creación y administración de objetos de cliente que interactúan con los recursos de datos

Los SDK de Azure son colecciones de bibliotecas creadas para facilitar el uso de servicios de Azure de distintos lenguajes. Los SDK están diseñados para simplificar las interacciones entre la aplicación y los recursos de Azure. El trabajo con recursos de Azure mediante el SDK comienza con la creación de una instancia de cliente. En este artículo se muestra cómo crear objetos de cliente para interactuar con los recursos de datos en Azure Blob Storage y ofrece procedimientos recomendados sobre cómo administrar clientes en la aplicación.

Acerca de los objetos cliente

Las bibliotecas cliente de Azure Blob Storage le permiten interactuar con tres tipos de recursos en el servicio de almacenamiento:

• Cuentas de almacenamiento
• Contenedores de blobs
• Datos BLOB

En función de las necesidades de la aplicación, puede crear objetos de cliente en cualquiera de estos tres niveles.

En el caso de los blobs, hay un cliente de blobs general que cubre las operaciones de blob comunes en todos los tipos y hay clientes de blobs especializados para cada tipo (blob en bloques, blob en anexos y blob en páginas).

En la tabla siguiente se enumeran las distintas clases de cliente para cada idioma:

Idioma	Paquetes	Clase de cliente de servicio	Clase de cliente de contenedor	Clases de cliente de blobs
.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 incluye métodos para tipos de blobs especializados.

Se puede crear una instancia de cada tipo de cliente mediante una llamada a un constructor simple o una sobrecarga que toma varias opciones de configuración. Para Java, cada tipo de cliente tiene una clase independiente que proporciona una API de generador que ayuda con la configuración y la creación de instancias. Según el SDK de lenguaje, estas opciones de configuración de cliente se pasan al constructor de maneras diferentes. Consulte la referencia de clase de la tabla para obtener más información.

Autorizar un objeto cliente

Para que una aplicación acceda a los recursos de blob e interactúe con ellos, debe autorizarse un objeto cliente. Los ejemplos de código de este artículo usan DefaultAzureCredential para autenticarse en Azure a través de una entidad de seguridad de Microsoft Entra. El proceso de autenticación incluye la obtención de un token de acceso para la autorización. Este token de acceso se pasa como una credencial cuando se crea una instancia del cliente y la credencial persiste durante toda la duración del cliente. La entidad de seguridad de Microsoft Entra que solicita el token debe tener asignado un rol RBAC de Azure adecuado que conceda acceso a los datos de blobs. Para más información, consulte Asignación de un rol de Azure para acceder a datos de blobs.

Se pueden usar los siguientes mecanismos de autorización para conceder el nivel de acceso adecuado a un objeto de cliente:

• Microsoft Entra ID: recomendado para una seguridad óptima
• Firma de acceso compartido (SAS): compatible y más segura al usar un token de SAS de delegación de usuarios
• Clave de acceso de la cuenta (clave compartida): se admite, pero no se recomienda, ya que puede ser menos segura

Para más información sobre la autorización, consulte Autorización del acceso a datos en Azure Storage.

Creación de un objeto de cliente

Trabajar con cualquier recurso de Azure mediante el SDK comienza con la creación de un objeto de cliente. En esta sección, aprenderá a crear objetos de cliente para interactuar con los tres tipos de recursos en el servicio de almacenamiento: cuentas de almacenamiento, contenedores y blobs.

Cuando la aplicación crea un objeto de cliente, se pasa un URI que hace referencia al punto de conexión al constructor del cliente. Puede construir manualmente la cadena de punto de conexión, como se muestra en los ejemplos de este artículo, o bien puede consultar el punto de conexión en tiempo de ejecución mediante la biblioteca de administración de Azure Storage. Para obtener información sobre cómo consultar un punto de conexión, consulte Consulta de un punto de conexión de Blob Storage.

Creación de un objeto BlobServiceClient

Un objeto BlobServiceClient autorizado permite a su aplicación interactuar con los recursos a nivel de la cuenta de almacenamiento. BlobServiceClient proporciona métodos para recuperar y configurar propiedades de cuenta, así como enumerar, crear y eliminar contenedores dentro de la cuenta de almacenamiento. Este objeto de cliente es el punto de partida para interactuar con los recursos de la cuenta de almacenamiento.

Un escenario común consiste en crear instancias de un único cliente de servicio y, a continuación, crear clientes de contenedor y clientes de blobs desde el cliente de servicio, según sea necesario. Para trabajar con un contenedor o blob específico, puede utilizar el objeto BlobServiceClient para crear un cliente de contenedor o cliente de blob. Los clientes creados a partir de un elemento BlobServiceClient heredarán su configuración de cliente, incluidas las opciones de cliente y las credenciales.

En los ejemplos siguientes se muestra cómo crear un objeto BlobServiceClient:

.NET

Agregue las siguientes directivas using:

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

Agregue el siguiente código para crear el objeto cliente:

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

    return client;
}

Java

Agregue las siguientes directivas import:

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

Agregue el siguiente código para crear el 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

Agregue las instrucciones siguientes require :

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

Agregue el siguiente código para crear el objeto cliente:

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

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

Python

Agregue las instrucciones siguientes import :

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

Agregue el siguiente código para crear el 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

Creación de un objeto BlobContainerClient

Puede usar un objeto BlobServiceClient para crear un nuevo objeto BlobContainerClient (ContainerClient para JavaScript y Python). Un objeto BlobContainerClient permite interactuar con un recurso de contenedor específico. Este recurso no necesita existir en la cuenta de almacenamiento para crear el objeto de cliente. BlobContainerClient proporciona métodos para crear, eliminar o configurar un contenedor, e incluye métodos para enumerar, cargar y eliminar los blobs que contiene. Para realizar operaciones en un blob específico dentro del contenedor, puede crear un cliente de blobs.

En los ejemplos siguientes se muestra cómo crear un cliente de contenedor a partir de un objeto BlobServiceClient para interactuar con un recurso de contenedor 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

Si el trabajo está limitado a un único contenedor, puede optar por crear un objeto BlobContainerClient directamente sin usar BlobServiceClient. Todavía puede establecer opciones de cliente en un cliente de contenedor como lo haría en un cliente de servicio.

En los ejemplos siguientes se muestra cómo crear un cliente de contenedor directamente sin usar 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

Creación de un objeto BlobClient

Para interactuar con un recurso de blob específico, cree un objeto BlobClient a partir de un cliente de servicio o un cliente de contenedor. Un objeto BlobClient permite interactuar con un recurso de blob específico. Este recurso no necesita existir en la cuenta de almacenamiento para crear el objeto de cliente. BlobClient proporciona métodos para cargar, descargar, eliminar y crear instantáneas de un blob.

En los ejemplos siguientes se muestra cómo crear un cliente de blobs para interactuar con un 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

Administrar objetos de cliente

Un procedimiento recomendado para la administración de clientes del SDK de Azure es tratar a un cliente como singleton, lo que significa que una clase solo tendrá un objeto a la vez. No es necesario mantener más de una instancia de un cliente para un conjunto determinado de parámetros de constructor u opciones de cliente. Este concepto se puede implementar de muchas maneras, entre las que se incluyen:

• Crear un único objeto de cliente y pasarlo como parámetro en toda la aplicación. Este enfoque se muestra en los ejemplos de código de este artículo.
• Almacenar una instancia de cliente en un campo. Para más información sobre los campos de C#, consulte Campos (Guía de programación de C#).
• Registrar el objeto de cliente como singleton en un contenedor de inserción de dependencias de su elección. Para más información sobre la inserción de dependencias en aplicaciones de ASP.NET Core, consulte Inserción de dependencias con Azure SDK para .NET.

Este enfoque es mucho más eficaz a escala que llamar a un constructor para cada cliente que necesite.

Inmutabilidad del cliente y seguridad de subprocesos

Los clientes del SDK de Azure son inmutables después de crearlos, lo que significa que no se puede cambiar el punto de conexión al que se conecta, la credencial usada para la autorización u otros valores pasados como opciones de cliente. La inmutabilidad del cliente también significa que los clientes son seguros para compartir y reutilizar en toda la aplicación.

Si la aplicación necesita usar configuraciones o credenciales diferentes para los clientes del mismo tipo, puede crear una instancia de un cliente para cada conjunto de opciones de configuración.

El SDK de Azure garantiza que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí. Este diseño garantiza que compartir y reutilizar instancias de cliente sea siempre seguro, incluso entre subprocesos.

Pasos siguientes

Para más información sobre el uso de las bibliotecas cliente de Azure Storage para trabajar con recursos de datos, consulte los siguientes artículos:

• Introducción a Azure Blob Storage y .NET
• Comenzar con Azure Blob Storage y Java
• Introducción a Azure Blob Storage y JavaScript
• Comenzar con Azure Blob Storage y Python