Exportar archivos a Backblaze B2 en .NET con código abierto

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos · Mostrar bio

Exporta un archivo local a un bucket existente de B2 con el SDK de AWS de código abierto para .NET. Este ejemplo completo de consola usa la API de B2 compatible con S3 y limita cada archivo a 64 MiB.

Introducción al almacenamiento en la nube de Backblaze B2

B2 ofrece una API nativa y una API compatible con S3⁠. Aquí usamos operaciones de S3, nombres de buckets y la implementación de firma y reintentos del SDK de AWS.

Configura una cuenta de Backblaze B2

Crea un bucket y una clave de aplicación dedicada con permiso para escribir en él. Anota el endpoint de S3 y la región del bucket. Usa el ID de la clave de aplicación como clave de acceso y la clave de aplicación como secreto; un ID de cuenta no sustituye al ID de la clave. Usa una clave de aplicación estándar, no la clave maestra, para la API compatible con S3.

Instala las bibliotecas de .NET necesarias

Instala el SDK de .NET 10 y luego crea el proyecto con estos paquetes de versiones fijadas:

dotnet new console --framework net10.0 --name B2Export
cd B2Export
dotnet add package AWSSDK.Core --version 4.0.102.6
dotnet add package AWSSDK.S3 --version 4.0.103.3

Autentícate con la API de Backblaze B2 en .NET

Proporciona estas variables de entorno mediante tu shell o gestor de secretos antes de ejecutar el programa:

Las credenciales explícitas que aparecen a continuación evitan que el SDK busque en un perfil de AWS o en los metadatos de la instancia. Backblaze documenta esta configuración del SDK de AWS⁠.

Sube archivos a Backblaze B2 con C#

Reemplaza Program.cs por este programa completo. La clave del objeto se proporciona independientemente del nombre del archivo local; pásala sin escapar para que el SDK pueda codificar los espacios, los caracteres Unicode y los caracteres reservados.

using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

public static class B2Exporter
{
    public static async Task<int> Main(string[] args)
    {
        using var deadline = new CancellationTokenSource(TimeSpan.FromMinutes(5));
        Console.CancelKeyPress += (_, e) => { e.Cancel = true; deadline.Cancel(); };
        try
        {
            if (args.Length != 2) throw new ArgumentException("Pass a local file and an object key.");
            var endpoint = new Uri(Required("B2_ENDPOINT"));
            if (endpoint.Scheme != "https" || endpoint.UserInfo.Length != 0 ||
                endpoint.AbsolutePath != "/" || endpoint.Query.Length != 0 || endpoint.Fragment.Length != 0)
                throw new ArgumentException("Use the HTTPS regional endpoint without a bucket or path.");
            var config = new AmazonS3Config
            {
                ServiceURL = endpoint.AbsoluteUri,
                AuthenticationRegion = Required("B2_REGION"),
                ForcePathStyle = true,
                MaxErrorRetry = 2,
                RequestChecksumCalculation = RequestChecksumCalculation.WHEN_REQUIRED,
                ResponseChecksumValidation = ResponseChecksumValidation.WHEN_REQUIRED
            };
            using var client = new AmazonS3Client(
                Required("B2_KEY_ID"), Required("B2_APPLICATION_KEY"), config);
            await UploadAsync(client, Required("B2_BUCKET"), args[0], args[1], deadline.Token);
            Console.WriteLine("Uploaded.");
            return 0;
        }
        catch (OperationCanceledException) { Console.Error.WriteLine("Upload canceled or timed out."); }
        catch (AmazonS3Exception error) { Console.Error.WriteLine($"Storage returned HTTP {(int)error.StatusCode}."); }
        catch (Exception) { Console.Error.WriteLine("Upload failed. Check the file and storage configuration."); }
        return 1;
    }

    private static string Required(string name) =>
        Environment.GetEnvironmentVariable(name) is { Length: > 0 } value
            ? value : throw new ArgumentException($"Missing {name}.");

    public static async Task UploadAsync(IAmazonS3 client, string bucket, string path,
        string key, CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(key)) throw new ArgumentException("An object key is required.");
        await using var input = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read);
        if (input.Length > 64L * 1024 * 1024) throw new IOException("This example accepts at most 64 MiB.");
        await client.PutObjectAsync(new PutObjectRequest
        {
            BucketName = bucket,
            Key = key,
            InputStream = input,
            AutoCloseStream = false,
            ContentType = "application/octet-stream",
            UseChunkEncoding = false
        }, cancellationToken);
    }
}

Integra las subidas a Backblaze en tu aplicación

Crea un archivo de entrada pequeño y ejecuta el programa desde el directorio del proyecto:

printf 'example export\n' > report.txt
dotnet run -- report.txt 'reports/report #1.txt'

UploadAsync acepta una instancia de IAmazonS3 y un token de cancelación, por lo que una aplicación puede reutilizar su cliente y propagar la cancelación de la solicitud. Quien realiza la llamada es responsable del cliente; el método cierra su flujo de archivo tanto si tiene éxito como si falla. Mantén el archivo de origen sin cambios hasta que termine la subida.

Solución de problemas y buenas prácticas

El SDK gestiona los errores de almacenamiento que permiten reintentos con un máximo de dos reintentos. Los errores de autenticación y permisos requieren cambios de configuración. Una solicitud cancelada o fallida puede tener un resultado remoto incierto, así que comprueba el objeto antes de volver a ejecutar el programa si es importante evitar crear otra versión del archivo en B2.

Este ejemplo envía una única solicitud PUT mediante un flujo, incluso para archivos vacíos. Para exportaciones más grandes, usa las funciones de carga multiparte del SDK y planifica la limpieza de las cargas multiparte abandonadas. Solo se deshabilitan las sumas de verificación opcionales del SDK por motivos de interoperabilidad; HTTPS y la firma de solicitudes permanecen habilitados.

Conclusión

El SDK de AWS ofrece un mecanismo completo y con soporte para firmar y subir archivos sin un adaptador independiente de inyección de dependencias para B2. Para combinar las exportaciones con el procesamiento, consulta el servicio de exportación de archivos de Transloadit.