Nahrání objektu blob bloku pomocí Javy

  • Článek

Tento článek ukazuje, jak nahrát objekt blob bloku pomocí klientské knihovny služby Azure Storage pro Javu. Data můžete nahrát do objektu blob bloku z cesty k souboru, datového proudu, binárního objektu nebo textového řetězce. Objekty blob můžete také nahrát se značkami indexu.

Požadavky

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro Javu. Další informace najdete v tématu Začínáme se službou Azure Blob Storage a Javou.

Pokud chcete pracovat s příklady kódu v tomto článku, nastavte projekt pomocí následujícího postupu.

Poznámka:

Tento článek používá nástroj pro sestavení Maven k sestavení a spuštění ukázkového kódu. Další nástroje sestavení, jako je Gradle, také pracují se sadou Azure SDK pro Javu.

Instalace balíčků

Otevřete soubor v textovém pom.xml editoru. Nainstalujte balíčky zahrnutím souboru kusovníku nebo zahrnutím přímé závislosti.

Přidání příkazů importu

Přidejte následující příkazy import:

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.*;

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k nahrání objektu blob. K autorizaci pomocí Microsoft Entra ID (doporučeno) potřebujete předdefinovanou roli Přispěvatel dat objektů blob služby Azure RBAC nebo vyšší. Další informace najdete v pokynech k autorizaci pro Put Blob (REST API) a Put Block (REST API).

Vytvoření objektu klienta

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci BlobServiceClient.

Následující příklad používá BlobServiceClientBuilder k sestavení BlobServiceClient objektu pomocí DefaultAzureCredentiala ukazuje, jak vytvořit kontejner a klienty objektů blob v případě potřeby:

// 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>");

Další informace o vytváření a správě klientských objektů najdete v tématu Vytváření a správa klientských objektů, které pracují s datovými prostředky.

Nahrání dat do objektu blob bloku

K nahrání objektu blob bloku ze streamu nebo binárního objektu použijte následující metodu:

K nahrání objektu blob bloku z cesty k souboru použijte následující metodu:

Každá z těchto metod se dá volat pomocí objektu BlobClient nebo objektu BlockBlobClient .

Nahrání objektu blob bloku z místní cesty k souboru

Následující příklad nahraje soubor do objektu blob bloku pomocí objektu BlobClient :

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());
    }
}

Nahrání objektu blob bloku ze streamu

Následující příklad nahraje objekt blob bloku vytvořením objektu ByteArrayInputStream a následným nahráním objektu streamu:

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();
    }
}

Nahrání objektu blob bloku z objektu BinaryData

Následující příklad se nahraje BinaryData do objektu blob bloku pomocí objektu BlobClient :

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));
}

Nahrání objektu blob bloku s možnostmi konfigurace

Při nahrávání objektu blob můžete definovat možnosti konfigurace klientské knihovny. Tyto možnosti je možné ladit, aby se zlepšil výkon, zlepšila spolehlivost a optimalizovala náklady. Následující příklady kódu ukazují, jak pomocí BlobUploadFromFileOptions definovat možnosti konfigurace při volání metody upload. Pokud soubor nenahráváte, můžete u metody nahrávání nastavit podobné možnosti pomocí BlobParallelUploadOptions .

Určení možností přenosu dat při nahrání

Hodnoty v ParallelTransferOptions můžete nakonfigurovat tak, aby se zlepšil výkon operací přenosu dat. Následující hodnoty je možné ladit pro nahrávání na základě potřeb vaší aplikace:

  • blockSize: Maximální velikost bloku, která se má přenést pro každou žádost. Tuto hodnotu můžete nastavit pomocí setBlockSizeLong metoda.
  • maxSingleUploadSize: Pokud je velikost dat menší nebo rovna této hodnotě, nahraje se do jediného umístění, nikoli do bloků dat. Pokud se data nahrají na jeden snímek, velikost bloku se ignoruje. Tuto hodnotu můžete nastavit pomocí setMaxSingleUploadSizeLong metoda.
  • maxConcurrency: Maximální počet paralelních požadavků vydaných v libovolném okamžiku jako součást jednoho paralelního přenosu. Tuto hodnotu můžete nastavit pomocí metody setMaxConcurrency .

Ujistěte se, že máte k nahrání následující import direktivu ParallelTransferOptions :

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

Následující příklad kódu ukazuje, jak nastavit hodnoty ParallelTransferOptions a zahrnout možnosti jako součást BlobUploadFromFileOptions instance. Hodnoty uvedené v této ukázce nejsou určené jako doporučení. Pokud chcete tyto hodnoty správně vyladit, musíte zvážit konkrétní potřeby vaší aplikace.

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());
    }
}

Další informace o ladění možností přenosu dat najdete v tématu Ladění výkonu pro nahrávání a stahování pomocí Javy.

Nahrání objektu blob bloku se značkami indexu

Značky indexu objektů blob kategorizují data v účtu úložiště pomocí atributů značek klíč-hodnota. Tyto značky se automaticky indexují a zveřejňují jako prohledávatelný multidimenzionální index, aby bylo možné snadno najít data.

Následující příklad nahraje objekt blob bloku se značkami indexu nastavenými pomocí BlobUploadFromFileOptions:

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());
    }
}

Nastavení úrovně přístupu k objektu blob při nahrání

Úroveň přístupu objektu blob můžete nastavit při nahrávání pomocí třídy BlobUploadFromFileOptions . Následující příklad kódu ukazuje, jak nastavit úroveň přístupu při nahrávání objektu blob:

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());
    }
}

Nastavení úrovně přístupu je povolené jenom pro objekty blob bloku. Úroveň přístupu objektu blob bloku můžete nastavit na Hot, Cool, Coldnebo Archive. Pokud chcete nastavit úroveň Coldpřístupu, musíte použít minimální verzi klientské knihovny 12.21.0.

Další informace o úrovních přístupu najdete v tématu Přehled úrovní přístupu.

Nahrání objektu blob bloku přípravými bloky a potvrzením

Můžete mít větší kontrolu nad tím, jak rozdělit nahrávání do bloků ručním přípravou jednotlivých bloků dat. Když jsou všechny bloky, které tvoří objekt blob, připravené, můžete je potvrdit do služby Blob Storage. Tento přístup můžete použít k vylepšení výkonu paralelním nahráváním bloků.

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();
}

Zdroje informací

Další informace o nahrávání objektů blob pomocí klientské knihovny Azure Blob Storage pro Javu najdete v následujících zdrojích informací.

Ukázky kódu

Operace rozhraní REST API

Sada Azure SDK pro Javu obsahuje knihovny, které jsou postavené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých paradigmat Javy. Metody klientské knihovny pro nahrávání objektů blob používají následující operace rozhraní REST API:

Prostředky klientské knihovny

Viz také

Související obsah

  • Tento článek je součástí příručky pro vývojáře služby Blob Storage pro Javu. Další informace najdete v úplném seznamu článků příručky pro vývojáře na webu Sestavení aplikace v Javě.