Hochladen eines Blockblobs mit Java

  • Artikel

In diesem Artikel wird beschrieben, wie ein Blockblob mithilfe der Azure Storage-Clientbibliothek für Java hochgeladen wird. Sie können Daten aus einem Dateipfad, einem Stream, einem binären Objekt oder einer Textzeichenfolge in ein Blockblob hochladen. Sie können auch Blobs mit Indextags hochladen.

Voraussetzungen

Erstellen Ihrer Umgebung

Wenn Sie nicht über ein vorhandenes Projekt verfügen, wird in diesem Abschnitt gezeigt, wie Sie ein Projekt für die Arbeit mit der Azure Blob Storage-Clientbibliothek für Java einrichten. Weitere Informationen finden Sie unter Erste Schritte mit Azure Blob Storage mit Java.

Um die Codebeispiele in diesem Artikel zu verwenden, führen Sie die folgenden Schritte zum Einrichten Ihres Projekts aus.

Hinweis

In diesem Artikel wird das Maven-Buildtool verwendet, um den Beispielcode zu erstellen und auszuführen. Andere Buildtools (beispielsweise Gradle) können ebenfalls mit dem Azure SDK für Java verwendet werden.

Installieren von Paketen

Öffnen Sie die Datei pom.xml in Ihrem Text-Editor. Installieren Sie die Pakete durch Einbeziehen der BOM-Datei oder Einbeziehen einer direkten Abhängigkeit.

Hinzufügen von Importanweisungen

Fügen Sie die folgenden import -Anweisungen ein:

import com.azure.core.http.rest.*;
import com.azure.core.util.BinaryData;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.options.BlobUploadFromFileOptions;
import com.azure.storage.blob.specialized.*;

import java.io.ByteArrayInputStream;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.time.Duration;
import java.util.*;

Autorisierung

Der Autorisierungsmechanismus muss über die erforderlichen Berechtigungen zum Hochladen eines Blobs verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) benötigen Sie mindestens die integrierte Azure RBAC-Rolle Mitwirkender an Storage-Blobdaten. Weitere Informationen finden Sie im Autorisierungsleitfaden für Put Blob (REST API) und Put Block (REST API).

Erstellen eines Clientobjekts

Um eine App mit Blob Storage zu verbinden, erstellen Sie eine Instanz von BlobServiceClient.

Im folgenden Beispiel wird BlobServiceClientBuilder verwendet, um ein BlobServiceClient-Objekt mithilfe von DefaultAzureCredential zu erstellen, und zeigt, wie Container- und Blob-Clients erstellt werden, falls erforderlich:

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

Weitere Informationen zum Erstellen und Verwalten von Clientobjekten finden Sie unter Erstellen und Verwalten von Clientobjekten, die mit Datenressourcen interagieren.

Hochladen von Daten in ein Blockblob

Um ein Blockblob aus einem Stream oder einem binären Objekt hochzuladen, verwenden Sie die folgende Methode:

Um ein Blockblob aus einem Dateipfad hochzuladen, verwenden Sie die folgende Methode:

Jede dieser Methoden kann mit einem BlobClient-Objekt oder einem BlockBlobClient-Objekt aufgerufen werden.

Hochladen eines Blockblobs aus einem lokalen Dateipfad

Im folgenden Beispiel wird eine Datei mithilfe eines BlobClient-Objekts in ein Blockblob hochgeladen:

public void uploadBlobFromFile(BlobContainerClient blobContainerClient) {
    BlobClient blobClient = blobContainerClient.getBlobClient("sampleBlob.txt");

    try {
        blobClient.uploadFromFile("filepath/local-file.png");
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

Hochladen eines Blockblobs aus einem Stream

Im folgenden Beispiel wird ein Blockblob hochgeladen, indem ein ByteArrayInputStream-Objekt erstellt und dann dieses Streamobjekt hochgeladen wird:

public void uploadBlobFromStream(BlobContainerClient blobContainerClient) {
    BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("sampleBlob.txt").getBlockBlobClient();
    String sampleData = "Sample data for blob";
    try (ByteArrayInputStream dataStream = new ByteArrayInputStream(sampleData.getBytes())) {
        blockBlobClient.upload(dataStream, sampleData.length());
    } catch (IOException ex) {
        ex.printStackTrace();
    }
}

Hochladen eines Blockblobs aus einem BinaryData-Objekt

Im folgenden Beispiel wird BinaryData in ein Blockblob mithilfe eines BlobClient-Objekts hochgeladen:

public void uploadDataToBlob(BlobContainerClient blobContainerClient) {
    // Create a BlobClient object from BlobContainerClient
    BlobClient blobClient = blobContainerClient.getBlobClient("sampleBlob.txt");
    String sampleData = "Sample data for blob";
    blobClient.upload(BinaryData.fromString(sampleData));
}

Upload eines Blockblobs mit Konfigurationsoptionen

Beim Upload eines Blobs können Sie Clientbibliotheks-Konfigurationsoptionen definieren. Diese Optionen können feiner abgestimmt werden, um die Leistung und die Zuverlässigkeit zu verbessern und die Kosten zu optimieren. Die folgenden Codebeispiele zeigen, wie Sie BlobUploadFromFileOptions verwenden, um Konfigurationsoptionen beim Aufrufen einer Uploadmethode zu definieren. Wenn Sie nicht aus einer Datei hochladen, können Sie ähnliche Optionen mit BlobParallelUploadOptions für eine Uploadmethode festlegen.

Angeben von Datenübertragungsoptionen beim Upload

Sie können Werte unter ParallelTransferOptions konfigurieren, um die Leistung für Datenübertragungsvorgänge zu verbessern. Die folgenden Werte können für Uploads je nach den Bedürfnissen Ihrer Anwendung angepasst werden:

  • blockSize: Die maximale zu übertragende Blockgröße für jede Anforderung fest. Sie können diesen Wert mit der Methode setBlockSizeLong festlegen.
  • maxSingleUploadSize: Wenn die Größe der Daten kleiner oder gleich diesem Wert ist, werden sie in einem einzelnen Put hochgeladen, anstatt in Blöcke aufgeteilt zu werden. Wenn die Daten in einem einzigen Vorgang hochgeladen werden, wird die Blockgröße ignoriert. Sie können diesen Wert mit der Methode setMaxSingleUploadSizeLong festlegen.
  • maxConcurrency: Die maximale Anzahl paralleler Anforderungen, die zu einem bestimmten Zeitpunkt im Rahmen einer einzelnen parallelen Übertragung ausgegeben werden. Sie können diesen Wert mit der Methode setMaxConcurrency festlegen.

Stellen Sie sicher, dass Sie über die folgende import Anweisung für einen Upload verfügen ParallelTransferOptions:

import com.azure.storage.blob.models.*;

Im folgenden Codebeispiel wird gezeigt, wie Sie Werte für ParallelTransferOptions festlegen und die Optionen als Teil einer BlobUploadFromFileOptions-Instanz einbeziehen. Die in diesem Beispiel angegebenen Werte sind nicht als Empfehlungen zu verstehen. Zur ordnungsgemäßen Optimierung dieser Werte müssen die spezifischen Anforderungen Ihrer App berücksichtigt werden.

public void uploadBlockBlobWithTransferOptions(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
            .setBlockSizeLong((long) (4 * 1024 * 1024)) // 4 MiB block size
            .setMaxConcurrency(2)
            .setMaxSingleUploadSizeLong((long) 8 * 1024 * 1024); // 8 MiB max size for single request upload

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString());
    options.setParallelTransferOptions(parallelTransferOptions);

    try {
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, null, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

Weitere Informationen zur Feinabstimmung von Datenübertragungsoptionen finden Sie unter Leistungsoptimierung für Uploads und Downloads mit Java.

Hochladen eines Blockblobs mit Indextags

Blobindextags kategorisieren Daten in Ihrem Speicherkonto mithilfe von Schlüssel-Wert-Tagattributen. Diese Tags werden automatisch indiziert und als durchsuchbarer mehrdimensionaler Index verfügbar gemacht, um Daten einfach finden zu können.

Im folgenden Beispiel wird ein Blockblob mit festgelegten Indextags mithilfe von BlobUploadFromFileOptions hochgeladen:

public void uploadBlockBlobWithIndexTags(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    Map<String, String> tags = new HashMap<String, String>();
    tags.put("Content", "image");
    tags.put("Date", "2022-01-01");

    Duration timeout = Duration.ofSeconds(10);

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString());
    options.setTags(tags);

    try {
        // Create a new block blob, or update the content of an existing blob
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, timeout, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

Festlegen der Zugriffsebene eines Blobs während des Uploads

Beim Upload können Sie die Zugriffsebene eines Blobs festlegen, indem Sie die Klasse BlobUploadFromFileOptions verwenden. Im folgenden Codebeispiel wird gezeigt, wie die Zugriffsebene beim Upload eines Blobs festgelegt wird:

public void uploadBlobWithAccessTier(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString())
            .setTier(AccessTier.COOL);

    try {
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, null, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

Das Festlegen der Zugriffsebene ist nur für Blockblobs zulässig. Sie können die Zugriffsebene für ein Blockblob auf Hot, Cool, Cold oder Archive festlegen. Um die Zugriffsebene auf Cold festzulegen, müssen Sie mindestens die Version 12.21.0 der Clientbibliothek verwenden.

Weitere Informationen zu Zugriffsebenen finden Sie unter Übersicht über Zugriffsebenen.

Hochladen eines Blockblobs durch Stagingblöcke und Commit

Sie können die Aufteilung der Uploads in Blöcke besser kontrollieren, indem Sie einzelne Datenblöcke manuell bereitstellen. Wenn alle Blöcke, aus denen ein Blob besteht, bereitgestellt wurden, können Sie sie in Blob Storage committen. Sie können diesen Ansatz verwenden, um die Leistung zu verbessern, indem Sie Blöcke parallel hochladen.

public void uploadBlocks(BlobContainerClient blobContainerClient, Path filePath, int blockSize) throws IOException {
    String fileName = filePath.getFileName().toString();
    BlockBlobClient blobClient = blobContainerClient.getBlobClient(fileName).getBlockBlobClient();

    FileInputStream fileStream = new FileInputStream(filePath.toString());
    List<String> blockIDArrayList = new ArrayList<>();
    byte[] buffer = new byte[blockSize];
    int bytesRead;

    while ((bytesRead = fileStream.read(buffer, 0, blockSize)) != -1) {

        try (ByteArrayInputStream stream = new ByteArrayInputStream(buffer)) {
            String blockID = Base64.getEncoder().encodeToString(UUID.randomUUID().toString().getBytes(StandardCharsets.UTF_8));

            blockIDArrayList.add(blockID);
            blobClient.stageBlock(blockID, stream, buffer.length);
        }
    }

    blobClient.commitBlockList(blockIDArrayList);

    fileStream.close();
}

Ressourcen

Weitere Informationen zum Hochladen von Blobs mithilfe der Azure Blob Storage-Clientbibliothek für Java finden Sie in den folgenden Ressourcen.

Codebeispiele

REST-API-Vorgänge

Das SDK für Java enthält Bibliotheken, die auf der zugrunde liegenden Azure-REST-API basieren, und ermöglicht Ihnen dadurch die Interaktion mit REST-API-Vorgängen über vertraute Java-Paradigmen. Die Clientbibliotheksmethoden zum Hochladen von Blobs verwenden die folgenden REST-API-Vorgänge:

Ressourcen zur Clientbibliothek

Weitere Informationen

Zugehöriger Inhalt

  • Dieser Artikel ist Teil des Blob Storage-Entwicklerleitfadens für Java. Weitere Informationen finden Sie in der vollständigen Liste der Entwicklerleitfadenartikel unter Erstellen Ihrer Java-App.