Transloadit
Última actualización:

Exporta archivos a Microsoft Azure de forma eficiente con cURL

Tim Koschützki
Tim Koschützki
Cofundador · Berlín, Alemania ·

Exportar archivos a Microsoft Azure Storage con cURL ofrece una forma flexible y eficiente de interactuar con el almacenamiento en la nube directamente desde la línea de comandos. Esta guía muestra cómo exportar archivos a Azure Blob Storage con cURL y destaca el uso recomendado de la autenticación de Microsoft Entra ID, la gestión segura de tokens y prácticas sólidas de manejo de errores.

Los ejemplos de shell usan Bash y cURL 7.76.0 o posterior para --fail-with-body.

Configurar la cuenta de almacenamiento de Azure

Antes de usar cURL con Azure Storage, crea una cuenta de almacenamiento de Azure y un contenedor desde el Azure Portal o la Azure CLI. Recomendamos habilitar la autenticación de Microsoft Entra ID (antes Azure AD) para obtener una seguridad superior y una gestión de tokens más ágil.

Métodos de autenticación

Azure Blob Storage admite dos métodos de autenticación principales:

Obtén un token de acceso con la Azure CLI. Asegúrate de haber iniciado sesión con az login y de tener un rol de plano de datos como Storage Blob Data Contributor con alcance en el contenedor de destino.

token=$(az account get-access-token --resource https://storage.azure.com/ --query accessToken -o tsv) || exit 1
: "${token:?Azure returned no access token}"

Usa el token en las solicitudes de cURL:

curl --fail-with-body --show-error -X PUT \
  -H "Authorization: Bearer $token" \
  -H "x-ms-version: 2023-11-03" \
  -H "x-ms-blob-type: BlockBlob" \
  -H "Content-Type: application/octet-stream" \
  --upload-file "localfile.txt" \
  "https://youraccount.blob.core.windows.net/container/remotefile.txt"

Shared Access Signature (alternativa)

Para escenarios en los que Microsoft Entra ID no es viable, usa tokens SAS con controles de seguridad estrictos. Este método también admite comprobaciones de integridad adicionales mediante el encabezado Content-MD5:

set -o pipefail
content_md5=$(openssl dgst -md5 -binary localfile.txt | base64) || exit 1
curl --fail-with-body --show-error -X PUT \
  -H "x-ms-blob-type: BlockBlob" \
  -H "x-ms-version: 2023-11-03" \
  -H "Content-Type: application/octet-stream" \
  -H "Content-MD5: $content_md5" \
  --upload-file "localfile.txt" \
  "https://youraccount.blob.core.windows.net/container/remotefile.txt?your_sas_token"

Gestionar subidas de archivos grandes

Para los archivos que superan el límite de 5.000 MiB por operación de escritura, usa la API de Block Blob para subir archivos grandes en fragmentos. Con las versiones de API 2019-12-12 y posteriores, el tamaño máximo de bloque es de 4.000 MiB, lo que permite un tamaño máximo de blob de casi 190,7 TiB cuando se usan hasta 50.000 bloques.

#!/bin/bash
set -euo pipefail
: "${token:?Acquire an Azure access token first}"

file="largefile.txt"
block_size=$((4000*1024*1024))  # 4,000 MiB blocks
base_url="https://youraccount.blob.core.windows.net/container/largefile.txt"
[ -s "$file" ] || { echo 'Use a single PUT for an empty file.' >&2; exit 1; }
temp_dir=$(mktemp -d)
trap 'rm -rf -- "$temp_dir"' EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
run_id=$(openssl rand -hex 8)

# Isolate this run's parts so retries cannot pick up stale files.
split -a 5 -b "$block_size" "$file" "$temp_dir/block_"
blocks=("$temp_dir"/block_*)
[ "${#blocks[@]}" -le 50000 ] || { echo 'Too many blocks.' >&2; exit 1; }
printf '%s\n' '<?xml version="1.0" encoding="utf-8"?><BlockList>' > "$temp_dir/blocklist.xml"
index=0

# Upload blocks
for block in "${blocks[@]}"; do
    block_id=$(printf '%s%08d' "$run_id" "$index" | base64 | tr -d '\n')
    encoded_id=${block_id//+/%2B}
    encoded_id=${encoded_id//\//%2F}
    encoded_id=${encoded_id//=/%3D}
    curl --fail-with-body --show-error --retry 3 --upload-file "$block" \
        -H "Authorization: Bearer $token" \
        -H "x-ms-version: 2023-11-03" \
        "$base_url?comp=block&blockid=$encoded_id"
    printf '<Latest>%s</Latest>\n' "$block_id" >> "$temp_dir/blocklist.xml"
    index=$((index + 1))
done

printf '%s\n' '</BlockList>' >> "$temp_dir/blocklist.xml"

# Commit only after every block succeeded.
curl --fail-with-body --show-error --upload-file "$temp_dir/blocklist.xml" \
    -H "Authorization: Bearer $token" \
    -H "x-ms-version: 2023-11-03" \
    -H "Content-Type: application/xml" \
    "$base_url?comp=blocklist"

--upload-file transmite cada PUT; --data-binary @file lo cargaría primero en memoria. Este ejemplo necesita un espacio temporal en disco aproximadamente igual al tamaño de la entrada. Mantén la entrada sin cambios durante la ejecución. Los identificadores de bloque deben tener la misma longitud y estar codificados en URL dentro de la cadena de consulta; la lista XML usa su forma original en Base64. Las ejecuciones fallidas eliminan sus partes locales y nunca confirman una lista parcial. Los nombres de blob que contienen espacios o caracteres reservados también necesitan codificación de URL.

Manejo de errores y reintentos

Implementa un manejo de errores sólido con retroceso exponencial para los errores transitorios. La siguiente función reintenta los PUT de un solo archivo ante los códigos HTTP 408, 429, 500, 502, 503 y 504, y se interrumpe de inmediato ante los fallos de autenticación (HTTP 401 o 403). Informa como fallos los demás errores de transporte o de HTTP:

upload_with_retry() {
    local url="$1"
    local file="$2"
    local max_attempts=5
    local attempt=1
    local wait_time=2
    local status
    local curl_status

    while [ $attempt -le $max_attempts ]; do
        curl_status=0
        status=$(curl --fail-with-body --silent --show-error -o /dev/null -w "%{http_code}" \
            -H "Authorization: Bearer $token" \
            -H "x-ms-version: 2023-11-03" \
            -H "x-ms-blob-type: BlockBlob" \
            --upload-file "$file" \
            "$url") || curl_status=$?
        if [ "$curl_status" -eq 0 ] && [ "$status" = 201 ]; then
            return 0
        elif [ "$status" = 401 ] || [ "$status" = 403 ]; then
            echo "Authentication failed. Check credentials."
            return 1
        elif [ "$status" = 408 ] || [ "$status" = 429 ] || [ "$status" = 500 ] || [ "$status" = 502 ] || [ "$status" = 503 ] || [ "$status" = 504 ]; then
            echo "Transient error $status encountered. Retrying in $wait_time seconds..."
        else
            echo "Upload failed with HTTP status $status and curl exit code $curl_status."
            return 1
        fi
        attempt=$((attempt + 1))
        [ "$attempt" -le "$max_attempts" ] || break
        sleep $wait_time
        wait_time=$((wait_time * 2))
    done

    echo "File upload failed after $max_attempts attempts."
    return 1
}

Monitoreo y validación

Consulta el estado de la subida y los metadatos del blob con el siguiente comando:

curl --fail-with-body --silent --show-error --head \
  -H "Authorization: Bearer $token" \
  -H "x-ms-version: 2023-11-03" \
  "https://youraccount.blob.core.windows.net/container/file.txt"

Monitorea el progreso de la transferencia con la opción de barra de progreso:

curl --fail-with-body --show-error --progress-bar \
  -H "Authorization: Bearer $token" \
  -H "x-ms-version: 2023-11-03" \
  -H "x-ms-blob-type: BlockBlob" \
  --upload-file "largefile.txt" \
  "https://youraccount.blob.core.windows.net/container/largefile.txt"

Prácticas recomendadas de seguridad

  • Usa la autenticación de Microsoft Entra ID siempre que sea posible para aprovechar una mayor seguridad y una mejor gestión de tokens.
  • Usa siempre HTTPS para realizar transferencias de datos seguras con Azure Storage.
  • Restringe los permisos que otorgan los tokens SAS y usa tiempos de expiración cortos.
  • Aplica restricciones de dirección IP para limitar el acceso a tu cuenta de almacenamiento.
  • Establece los permisos mínimos necesarios para cada operación.
  • Monitorea y registra todas las operaciones con fines de auditoría y resolución de problemas.
  • Rota las credenciales con regularidad para mitigar posibles brechas de seguridad.
  • Valida la integridad de los archivos con el encabezado Content-MD5.

Optimización del rendimiento

Para maximizar el rendimiento de las transferencias:

  • Elige tamaños de bloque adecuados (hasta 4.000 MiB por bloque).
  • Habilita subidas simultáneas siempre que sea posible para varios archivos.
  • Selecciona la región de Azure más cercana para reducir la latencia.
  • Monitorea el ancho de banda y la latencia de la red para optimizar las transferencias.
  • Usa compresión cuando sea adecuado, teniendo en cuenta que algunos archivos ya están comprimidos.
  • Implementa un manejo de errores y reintentos exhaustivos para lograr subidas sólidas.

Conclusión

Integrar Azure Blob Storage con cURL ofrece una estrategia potente para gestionar las operaciones de almacenamiento en la nube. Si sigues estos métodos de autenticación actualizados, las prácticas recomendadas de seguridad y los consejos de optimización del rendimiento, podrás crear una solución de transferencia de archivos fiable y segura. Para obtener capacidades avanzadas adicionales de manejo de archivos, considera explorar los servicios de Transloadit, que admiten funciones como Uppy y el protocolo tus para mejorar el procesamiento de archivos.

#curl#azure#blob-storage#file-exporting-service

👩‍💻 Únete a más de 20k desarrolladores

Suscríbete a nuestro boletín mensual  (English) para recibir enlaces directos a 3 artículos exclusivos sobre tecnología y 2 actualizaciones de producto. Ni más ni menos.

Subida y encoding de archivos. Sin complicaciones.

Transloadit optimiza el manejo de archivos para desarrolladores, con la confianza de marcas como Coursera y The New York Times. Somos reconocidos por una API confiable, soporte de primer nivel y un firme compromiso con el código abierto, con proyectos como Uppy y el protocolo tus que marcan estándares en el procesamiento de archivos.

RegístrateAgenda una demo

No necesitas tarjeta de crédito

Cancela en cualquier momento