Inicio rápido: Módulo cliente de Azure Blob Storage para Go

  • Artículo

Introducción al módulo cliente de Azure Blob Storage para que Go administre blobs y contenedores. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (pkg.go.dev)

Prerrequisitos

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con el módulo cliente de Azure Blob Storage para Go.

Descarga de la aplicación de ejemplo

La aplicación de ejemplo utilizada en esta guía de inicio rápido es una aplicación Go básica.

Use git para descargar una copia de la aplicación en su entorno de desarrollo.

git clone https://github.com/Azure-Samples/storage-blobs-go-quickstart

Este comando clona el repositorio en la carpeta git local. Para abrir el ejemplo de Go para Blob Storage, busque el nombre de archivo storage-quickstart.go.

Instalación de los paquetes

Para trabajar con recursos de blob y contenedor en una cuenta de almacenamiento, instale el paquete azblob mediante el siguiente comando:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Para autenticarse con Microsoft Entra ID (recomendado), instale el módulo azidentity mediante el siguiente comando:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Autenticación en Azure y autorización del acceso a datos de blobs

Las solicitudes de aplicación a Azure Blob Storage deben estar autorizadas. El uso de DefaultAzureCredential y de la biblioteca cliente de Identidad de Azure es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código, incluido Blob Storage.

También puede autorizar las solicitudes a Azure Blob Storage mediante la clave de acceso de la cuenta. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser diligentes para no exponer nunca las claves de acceso en una ubicación que no sea segura. Cualquier persona que tenga la clave de acceso puede autorizar las solicitudes en la cuenta de almacenamiento y tiene acceso eficaz a todos los datos. DefaultAzureCredential ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

DefaultAzureCredential es una implementación de cadena de credenciales proporcionada por la biblioteca cliente de Identidad de Azure para Go. DefaultAzureCredential admite varios métodos de autenticación y determina qué método se usa en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

Para conocer mejor el orden y las ubicaciones en las que DefaultAzureCredential busca credenciales, consulte la información general de la biblioteca de Azure Identity.

Por ejemplo, la aplicación puede autenticarse con las credenciales de inicio de sesión de la CLI de Azure cuando se desarrolla en el entorno local. Una vez implementado en Azure, la aplicación puede usar una identidad administrada. Esta transición entre entornos no requiere ningún cambio de código.

Asignación de roles a la cuenta de usuario de Microsoft Entra

Al desarrollar localmente, asegúrese de que la cuenta de usuario que accede a los datos de blob tenga los permisos correctos. Necesitará el Colaborador de datos de blobs de almacenamiento para leer y escribir datos de blob. Para asignarse este rol a sí mismo, necesitará que se le asigne el rol Administrador de acceso de usuario u otro rol que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En este escenario, asignará permisos a la cuenta de usuario, cuyo ámbito es la cuenta de almacenamiento, a fin de seguir el principio de privilegios mínimos. Esta práctica solo proporciona a los usuarios los permisos mínimos necesarios y crea entornos de producción más seguros.

En el ejemplo siguiente se asignará el rol Colaborador de datos de blobs de almacenamiento a la cuenta de usuario, que proporciona acceso de lectura y escritura a los datos de blobs de la cuenta de almacenamiento.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure, pero en casos excepcionales puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

    Una captura de pantalla que muestra cómo asignar un rol.

  5. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Colaborador de datos de blobs de almacenamiento y seleccione el resultado coincidente y, a continuación, elija Siguiente.

  6. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  7. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  8. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Inicio de sesión y conexión del código de la aplicación a Azure mediante DefaultAzureCredential

Puede autorizar el acceso a los datos de la cuenta de almacenamiento mediante los siguientes pasos:

  1. Asegúrese de que esté autenticado con la misma cuenta de Microsoft Entra a la que asignó el rol en la cuenta almacenamiento. En el ejemplo siguiente se muestra cómo autenticarse a través de la CLI de Azure:

    az login

  2. Para usarlo DefaultAzureCredential en una aplicación Go, instale el módulo azidentity mediante el siguiente comando:

    go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

La autenticación con la CLI de Azure no se recomienda para las aplicaciones que se ejecutan en Azure. Cuando se implementa en Azure, se puede usar este mismo código para autorizar solicitudes a Azure Storage desde una aplicación que se ejecute en Azure. Sin embargo, debe habilitar la identidad administrada en la aplicación en Azure y configurar la cuenta de almacenamiento para permitir que esa identidad administrada se conecte. Para obtener instrucciones detalladas sobre la configuración de esta conexión entre los servicios de Azure, consulte el tutorial Autenticación desde aplicaciones hospedadas en Azure.

Para más información sobre los diferentes métodos de autenticación, consulte Autenticación de Azure con Azure SDK para Go.

Ejecución del ejemplo

El ejemplo del código realiza las siguientes acciones:

  • Crea un objeto de cliente autorizado para el acceso a datos a través de DefaultAzureCredential
  • Crea un contenedor en una cuenta de almacenamiento
  • Carga un blob en el contenedor
  • Enumera los blobs del contenedor
  • Descarga los datos del blob en un búfer
  • Elimina los recursos de blob y contenedor creados por la aplicación

Antes de ejecutar el ejemplo, abra el archivo storage-quickstart.go. Reemplace <storage-account-name> por el nombre de la cuenta de Azure Storage.

Después, ejecute la aplicación con el comando siguiente:

go run storage-quickstart.go

La salida de la aplicación es similar a la del ejemplo siguiente:

Azure Blob storage quick start sample
Creating a container named quickstart-sample-container
Uploading a blob named sample-blob
Listing the blobs in the container:
sample-blob
Blob contents:

Hello, world! This is a blob.

Press enter key to delete resources and exit the application.

Cleaning up.
Deleting the blob sample-blob
Deleting the container quickstart-sample-container

Al presionar la tecla ENTRAR en el símbolo del sistema, el programa de ejemplo elimina los recursos de blob y contenedor creados por la aplicación.

Sugerencia

También puede usar una herramienta como Explorador de Azure Storage para ver los archivos de Blob Storage. El Explorador de Azure Storage es una herramienta gratuita multiplataforma que permite acceder a la información de la cuenta de almacenamiento.

Descripción del código de ejemplo

Después, vemos el código de ejemplo para reconocer cómo funciona.

Autorización del acceso y 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. Para crear el objeto de cliente, el ejemplo de código llama a azblob.NewClient con los siguientes valores:

  • serviceURL: la dirección URL de la cuenta de almacenamiento
  • cred: una credencial de Microsoft Entra obtenida mediante el módulo azidentity
  • options: opciones de cliente; dejad en cero para aceptar los valores predeterminados

En el ejemplo de código siguiente se crea un objeto de cliente para interactuar con los recursos de contenedor y blob en una cuenta de almacenamiento:

// TODO: replace <storage-account-name> with your actual storage account name
url := "https://<storage-account-name>.blob.core.windows.net/"
ctx := context.Background()

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

client, err := azblob.NewClient(url, credential, nil)
handleError(err)

Crear un contenedor

El ejemplo de código crea un nuevo recurso de contenedor en la cuenta de almacenamiento. Si ya existe un contenedor con el mismo nombre, se genera ResourceExistsError.

Importante

Los nombres de contenedor deben estar en minúsculas. Para conocer mejor los requisitos de nomenclatura para contenedores y los blobs, consulte Asignación de nombres y realización de referencias a contenedores, blobs y metadatos.

En el ejemplo de código siguiente se crea un contenedor denominado quickstart-sample-container en la cuenta de almacenamiento:

// Create the container
containerName := "quickstart-sample-container"
fmt.Printf("Creating a container named %s\n", containerName)
_, err = client.CreateContainer(ctx, containerName, nil)
handleError(err)

Para obtener más información sobre cómo crear un contenedor y explorar más ejemplos de código, consulte Creación de un contenedor de blobs con Go.

Carga de blobs al contenedor

El ejemplo de código crea una matriz de bytes con algunos datos y carga los datos como un búfer en un nuevo recurso de blob en el contenedor especificado.

En el ejemplo de código siguiente se cargan los datos de blob en el contenedor especificado mediante el método UploadBuffer:

data := []byte("\nHello, world! This is a blob.\n")
blobName := "sample-blob"

// Upload to data to blob storage
fmt.Printf("Uploading a blob named %s\n", blobName)
_, err = client.UploadBuffer(ctx, containerName, blobName, data, &azblob.UploadBufferOptions{})
handleError(err)

Para obtener más información sobre cómo cargar blobs y explorar más ejemplos de código, consulte Carga de un blob con Go.

Enumerar los blobs de un contenedor

En el ejemplo de código se enumeran los blobs del contenedor especificado. En este ejemplo se usa NewListBlobsFlatPager, que devuelve un buscapersonas para blobs a partir del marcador especificado. Aquí, usamos un marcador vacío para iniciar la enumeración desde el principio y continuar paginando hasta que no haya más resultados. Este método devuelve nombres de blob en orden lexicográfico.

En el ejemplo de código siguiente se enumeran los blobs del contenedor especificado:

// List the blobs in the container
fmt.Println("Listing the blobs in the container:")

pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
	Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
})

for pager.More() {
	resp, err := pager.NextPage(context.TODO())
	handleError(err)

	for _, blob := range resp.Segment.BlobItems {
		fmt.Println(*blob.Name)
	}
}

Para obtener más información sobre cómo enumerar blobs y explorar más ejemplos de código, consulte Enumeración de blobs con Go.

Descarga del blob

El ejemplo de código descarga un blob mediante el método DownloadStream y crea un lector de reintento para leer datos. Si se produce un error durante una lectura, el lector de reintentos realizará solicitudes adicionales para restablecer una conexión y continuar la lectura. Puede especificar opciones de lector de reintentos mediante la estructura RetryReaderOptions.

En el ejemplo de código siguiente se descarga un blob y se escribe el contenido en la consola:

// Download the blob
get, err := client.DownloadStream(ctx, containerName, blobName, nil)
handleError(err)

downloadedData := bytes.Buffer{}
retryReader := get.NewRetryReader(ctx, &azblob.RetryReaderOptions{})
_, err = downloadedData.ReadFrom(retryReader)
handleError(err)

err = retryReader.Close()
handleError(err)

// Print the contents of the blob we created
fmt.Println("Blob contents:")
fmt.Println(downloadedData.String())

Para obtener más información sobre cómo descargar blobs y explorar más ejemplos de código, consulte Descarga de un blob con Go.

Limpieza de recursos

Si ya no necesita los blobs cargados en este inicio rápido, puede eliminar el blob individual mediante el método DeleteBlob o todo el contenedor y su contenido mediante el método DeleteContainer.

// Delete the blob
fmt.Printf("Deleting the blob " + blobName + "\n")

_, err = client.DeleteBlob(ctx, containerName, blobName, nil)
handleError(err)

// Delete the container
fmt.Printf("Deleting the container " + containerName + "\n")
_, err = client.DeleteContainer(ctx, containerName, nil)
handleError(err)

Para obtener más información sobre cómo eliminar blobs y contenedores, y explorar más ejemplos de código, consulte Eliminación de un blob con Go y Eliminación de un contenedor con Go.

Paso siguiente

Guías para desarrolladores de Azure Blob Storage para Go