Dateien aus Backblaze in PHP mit der Native API importieren

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Die Native API von Backblaze B2 ist eine HTTP-API. Daher reicht die Open-Source-Erweiterung cURL für PHP aus, um ein Objekt ohne Wrapper zu importieren. Dieses Beispiel nutzt API v4 zur Autorisierung und streamt ein privates Objekt auf die Festplatte. Es begrenzt den Umfang beider Antworten und stellt die Zieldatei erst nach dem vollständigen Download bereit.

Voraussetzungen

PHP 8.1 oder neuer mit ext-curl
Ein B2-Anwendungsschlüssel mit Zugriff auf readFiles
Die Anwendungsschlüssel-ID und der Anwendungsschlüssel; dies sind unterschiedliche Werte

$ php -r "exit(extension_loaded('curl') ? 0 : 1);"

Die B2 Native API verwenden

Speichern Sie den Code als import-b2.php. Er folgt niemals Weiterleitungen, sodass Zugangsdaten nicht an ein Weiterleitungsziel übermittelt werden können. Er akzeptiert HTTPS-Endpunkte sowie HTTP-Endpunkte über Loopback für lokale Tests.

Ein Objekt importieren

<?php
declare(strict_types=1);

final class CurlTransport
{
    private const MAX_AUTH_BYTES = 1_048_576;

    /** @return array<string, mixed> */
    public function authorize(string $url, string $keyId, string $applicationKey): array
    {
        $this->assertSafeUrl($url);
        $body = '';
        $curl = curl_init($url);
        if ($curl === false) {
            throw new RuntimeException('Could not initialize cURL');
        }
        try {
            if (!curl_setopt_array($curl, [
                CURLOPT_FOLLOWLOCATION => false,
                CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
                CURLOPT_PROTOCOLS => CURLPROTO_HTTP | CURLPROTO_HTTPS,
                CURLOPT_TIMEOUT => 20,
                CURLOPT_USERPWD => $keyId . ':' . $applicationKey,
                CURLOPT_WRITEFUNCTION => static function ($handle, string $chunk) use (&$body): int {
                    if (strlen($body) + strlen($chunk) > self::MAX_AUTH_BYTES) {
                        return 0;
                    }
                    $body .= $chunk;
                    return strlen($chunk);
                },
            ])) {
                throw new RuntimeException('Could not configure cURL');
            }
            $ok = curl_exec($curl);
            $status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
            if ($ok !== true || $status !== 200) {
                throw new RuntimeException("B2 authorization failed with HTTP {$status}");
            }
        } finally {
            unset($curl);
        }
        $decoded = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
        if (!is_array($decoded)) {
            throw new RuntimeException('B2 returned an invalid authorization response');
        }
        return $decoded;
    }

    /** @param resource $output */
    public function download(string $url, string $token, $output, int $maxBytes): void
    {
        $this->assertSafeUrl($url);
        $written = 0;
        $curl = curl_init($url);
        if ($curl === false) {
            throw new RuntimeException('Could not initialize cURL');
        }
        try {
            if (!curl_setopt_array($curl, [
                CURLOPT_FOLLOWLOCATION => false,
                CURLOPT_HTTPHEADER => ['Authorization: ' . $token],
                CURLOPT_PROTOCOLS => CURLPROTO_HTTP | CURLPROTO_HTTPS,
                CURLOPT_TIMEOUT => 300,
                CURLOPT_WRITEFUNCTION => static function ($handle, string $chunk) use (
                    $output,
                    $maxBytes,
                    &$written,
                ): int {
                    $length = strlen($chunk);
                    if ($written + $length > $maxBytes) {
                        return 0;
                    }
                    $result = fwrite($output, $chunk);
                    if ($result !== $length) {
                        return 0;
                    }
                    $written += $result;
                    return $result;
                },
            ])) {
                throw new RuntimeException('Could not configure cURL');
            }
            $ok = curl_exec($curl);
            $status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
            if ($ok !== true || $status !== 200) {
                throw new RuntimeException("B2 download failed with HTTP {$status}");
            }
        } finally {
            unset($curl);
        }
    }

    private function assertSafeUrl(string $url): void
    {
        $scheme = parse_url($url, PHP_URL_SCHEME);
        $host = parse_url($url, PHP_URL_HOST);
        $loopback = $scheme === 'http' && in_array($host, ['127.0.0.1', '::1'], true);
        if ($scheme !== 'https' && !$loopback) {
            throw new RuntimeException('B2 endpoints must use HTTPS');
        }
    }
}

/** @param array<string, mixed> $authorization */
function requiredString(array $authorization, string $key): string
{
    $value = $authorization[$key] ?? null;
    if (!is_string($value) || $value === '') {
        throw new RuntimeException("B2 authorization response is missing {$key}");
    }
    return $value;
}

function encodeObjectName(string $objectName): string
{
    $segments = explode('/', $objectName);
    if (in_array('.', $segments, true) || in_array('..', $segments, true)) {
        throw new InvalidArgumentException('Object names cannot contain dot path segments');
    }
    return implode('/', array_map('rawurlencode', $segments));
}

function importB2Object(
    CurlTransport $transport,
    string $authorizeUrl,
    string $keyId,
    string $applicationKey,
    string $bucket,
    string $objectName,
    string $destination,
    int $maxBytes,
): void {
    if ($maxBytes < 1 || $bucket === '' || $objectName === '') {
        throw new InvalidArgumentException('Bucket, object name, and a positive limit are required');
    }
    $authorization = $transport->authorize($authorizeUrl, $keyId, $applicationKey);
    $apiInfo = $authorization['apiInfo'] ?? null;
    $storageApi = is_array($apiInfo) ? ($apiInfo['storageApi'] ?? null) : null;
    if (!is_array($storageApi)) {
        throw new RuntimeException('B2 authorization response is missing storageApi');
    }
    $downloadUrl = requiredString($storageApi, 'downloadUrl');
    $token = requiredString($authorization, 'authorizationToken');
    $url = rtrim($downloadUrl, '/') . '/file/' . rawurlencode($bucket) . '/'
        . encodeObjectName($objectName);

    $directory = dirname($destination);
    $realDirectory = realpath($directory);
    if ($realDirectory === false || !is_dir($realDirectory) || !is_writable($realDirectory)) {
        throw new RuntimeException('Destination directory must exist and be writable');
    }
    $temporary = tempnam($realDirectory, '.b2-');
    if ($temporary === false) {
        throw new RuntimeException('Could not create a temporary destination');
    }
    if (dirname($temporary) !== $realDirectory) {
        @unlink($temporary);
        throw new RuntimeException('Temporary file was not created beside the destination');
    }
    $output = fopen($temporary, 'wb');
    if ($output === false) {
        @unlink($temporary);
        throw new RuntimeException('Could not open the temporary destination');
    }
    try {
        $transport->download($url, $token, $output, $maxBytes);
        $flushed = fflush($output);
        $closed = fclose($output);
        $output = null;
        if (!$flushed || !$closed) {
            throw new RuntimeException('Could not finish writing the downloaded object');
        }
        if (!rename($temporary, $destination)) {
            throw new RuntimeException('Could not publish the downloaded object');
        }
    } finally {
        if (is_resource($output)) {
            fclose($output);
        }
        if (file_exists($temporary)) {
            unlink($temporary);
        }
    }
}

function main(array $arguments): void
{
    foreach (['B2_KEY_ID', 'B2_APPLICATION_KEY', 'B2_BUCKET', 'B2_OBJECT'] as $name) {
        if (getenv($name) === false || getenv($name) === '') {
            throw new RuntimeException("Missing environment variable: {$name}");
        }
    }
    $configuredMaxBytes = getenv('B2_MAX_BYTES');
    $maxBytes = filter_var(
        $configuredMaxBytes === false ? 100 * 1024 * 1024 : $configuredMaxBytes,
        FILTER_VALIDATE_INT,
        ['options' => ['min_range' => 1]],
    );
    if ($maxBytes === false) {
        throw new RuntimeException('B2_MAX_BYTES must be a positive integer');
    }
    importB2Object(
        new CurlTransport(),
        getenv('B2_AUTHORIZE_URL') ?: 'https://api.backblazeb2.com/b2api/v4/b2_authorize_account',
        (string) getenv('B2_KEY_ID'),
        (string) getenv('B2_APPLICATION_KEY'),
        (string) getenv('B2_BUCKET'),
        (string) getenv('B2_OBJECT'),
        $arguments[1] ?? (__DIR__ . '/imported-object'),
        $maxBytes,
    );
}

try {
    main($argv);
} catch (Throwable) {
    error_log('B2 import failed');
    exit(1);
}

B2_KEY_ID='your-key-id' \
B2_APPLICATION_KEY='your-application-key' \
B2_BUCKET='my-bucket' \
B2_OBJECT='photos/sunset.jpg' \
php import-b2.php ./sunset.jpg

Die Grenze von 100 MiB ist eine Vorgabe der Anwendung. Der Code erhält eine vorhandene Zieldatei, wenn die Autorisierung, der Download, die Größenprüfung, das Schreiben auf die Festplatte oder das Umbenennen fehlschlägt.

Den Importer anpassen

Dieser auf den Import ausgerichtete Code listet keine Objekte auf und prüft nicht deren Existenz. B2 bietet diese Vorgänge über b2_list_file_names und eine Anfrage mit HEAD an. Ein Dienst, der beide Namen kennt, kann jedoch direkt herunterladen.

Dateien sicher und effizient verarbeiten

Beschränken Sie den Schlüssel auf den erforderlichen Bucket, das Dateinamenpräfix und die Berechtigung readFiles.
Die Schlüssel-ID dient als Benutzername für Basic Auth; der Anwendungsschlüssel ist das Passwort.
Ergänzen Sie in einem Worker begrenzte Retries mit Jitter für 429 und vorübergehende Antworten vom Typ 5xx.
Halten Sie die temporäre Datei und die Zieldatei im selben Dateisystem, damit rename() die Datei atomar bereitstellt.

Fazit

Mit der Native API bleibt dieser PHP-Importer schlank und nutzt zugleich die aktuellen v4-Autorisierungsvorgaben von Backblaze. Für Verzeichnisse oder Verarbeitungspipelines kann der Backblaze-Import-Robot von Transloadit den Ablauf übernehmen.