Creación y administración de objetos de cliente que interactúan con los recursos de datos
Artículo
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:
1 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:
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:
Agregue el siguiente código para crear el objeto cliente:
func getClient(accountName string) *azblob.Client {
accountURL := fmt.Printf("https://%s.blob.core.windows.net", accountName)
// Create a new service client with token credential
credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)
client, err := azblob.NewClient(accountURL, credential, nil)
handleError(err)
return client
}
Las instancias de azblob.Client proporcionan métodos para trabajar con contenedores y blobs dentro de una cuenta de almacenamiento. Especifique el punto de conexión de la cuenta de almacenamiento al construir el objeto de cliente.
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:
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);
Agregue el código siguiente para crear el objeto de cliente contenedor:
func getBlobContainerClient(client *azblob.Client, containerName string) *container.Client {
// Create the container client using the azblob client object
containerClient := client.ServiceClient().NewContainerClient(containerName)
return containerClient
}
Las instancias de azblob.Client proporcionan métodos para trabajar con contenedores y blobs dentro de una cuenta de almacenamiento. Para la mayoría de las operaciones, puede usar la instancia azblob.Client en lugar de crear una instancia de container.Client independiente.
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:
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
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:
Agregue el código siguiente para crear el objeto de cliente de blobs:
func getBlobClient(client *azblob.Client, containerName string, blobName string) *blob.Client {
// Create the blob client using the azblob client object
blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)
return blobClient
}
Las instancias de azblob.Client proporcionan métodos para trabajar con contenedores y blobs dentro de una cuenta de almacenamiento. Para la mayoría de las operaciones, puede usar la instancia azblob.Client en lugar de crear una instancia de blob.Client independiente.
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.
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:
Cree soluciones de un extremo a otro en Microsoft Azure para crear Azure Functions, implementar y administrar aplicaciones web, desarrollar soluciones que usen Azure Storage, etc.