Udostępnij za pośrednictwem

Przekazywanie blokowego obiektu blob przy użyciu języka Java

W tym artykule pokazano, jak przekazać blokowy obiekt blob przy użyciu biblioteki klienta usługi Azure Storage dla języka Java. Dane można przekazać do blokowego obiektu blob ze ścieżki pliku, strumienia, obiektu binarnego lub ciągu tekstowego. Można również przekazywać obiekty blob za pomocą tagów indeksu.

Wymagania wstępne

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla języka Java. Aby uzyskać więcej informacji, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i Java.

Aby pracować z przykładami kodu w tym artykule, wykonaj następujące kroki, aby skonfigurować projekt.

Uwaga

W tym artykule użyto narzędzia kompilacji maven do skompilowania i uruchomienia przykładowego kodu. Inne narzędzia kompilacji, takie jak Gradle, współpracują również z zestawem Azure SDK dla języka Java.

Instalowanie pakietów

pom.xml Otwórz plik w edytorze tekstów. Zainstaluj pakiety, dołączając plik BOM lub uwzględniając bezpośrednią zależność.

Dodaj instrukcje importu

Dodaj następujące instrukcje 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.*;

Autoryzacja

Mechanizm autoryzacji musi mieć niezbędne uprawnienia do przesyłania obiektu typu blob. Aby uzyskać autoryzację przy użyciu Microsoft Entra ID (zalecane), potrzebujesz wbudowanej roli Azure RBAC Współtwórca danych obiektów blob usługi Storage lub wyższej. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla funkcji Put Blob (interfejs API REST) i Put Block (interfejs API REST).

Tworzenie obiektu klienta

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie BlobServiceClient.

W poniższym przykładzie użyto BlobServiceClientBuilder do skonstruowania obiektu BlobServiceClient przy użyciu DefaultAzureCredential, i pokazano, jak utworzyć klientów dla kontenerów i blobów, w razie potrzeby:

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

Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Przekazywanie danych do blobu blokowego

Aby przesłać blokowy blob ze strumienia lub obiektu binarnego, użyj następującej metody:

Aby przekazać blokowy obiekt blob ze ścieżki pliku, użyj następującej metody:

Każda z tych metod może być wywoływana przy użyciu obiektu BlobClient lub obiektu BlockBlobClient.

Uwaga

Biblioteki klienckie Azure Storage nie obsługują równoczesnego zapisu do tego samego obiektu blob. Jeśli Twoja aplikacja wymaga wielu procesów zapisujących do tego samego obiektu blob, należy zaimplementować strategię kontroli współbieżności, aby zapewnić przewidywalne doświadczenie. Aby dowiedzieć się więcej na temat strategii współbieżności, zobacz Zarządzanie współbieżnością w usłudze Blob Storage.

Prześlij blokowy blob z lokalnej ścieżki pliku

Poniższy przykład przesyła plik do blokowego obiektu blob za pomocą obiektu 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());
    }
}

Przekazywanie obiektu blob typu blokowego ze strumienia

Poniższy przykład przesyła obiekt blob jako blok, tworząc obiekt ByteArrayInputStream, a następnie przesyłając ten obiekt strumienia.

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

Załaduj blokowy blob z obiektu BinaryData

Poniższy przykład przesyła BinaryData do obiektu blokowego blob przy użyciu BlobClient obiektu.

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

Prześlij blokowy obiekt BLOB z opcjami konfiguracji

Opcje konfiguracji biblioteki klienta można zdefiniować podczas przesyłania obiektu blob. Te opcje można dostosować, aby zwiększyć wydajność, zwiększyć niezawodność i zoptymalizować koszty. W poniższych przykładach kodu pokazano, jak używać obiektu BlobUploadFromFileOptions do definiowania opcji konfiguracji podczas wywoływania metody przekazywania. Jeśli nie przesyłasz z pliku, możesz ustawić podobne opcje korzystając z BlobParallelUploadOptions w metodzie przesyłania.

Określanie opcji transferu danych podczas przekazywania

Można skonfigurować wartości w elemencie ParallelTransferOptions, aby zwiększyć wydajność operacji transferu danych. Następujące wartości można dostosować do wysyłania, w zależności od potrzeb aplikacji:

  • blockSize: maksymalny rozmiar bloku do przeniesienia dla każdego żądania. Tę wartość można ustawić przy użyciu metody setBlockSizeLong .
  • maxSingleUploadSize: Jeśli rozmiar danych jest mniejszy lub równy tej wartości, zostanie przekazany w jednym miejscu, a nie podzielony na fragmenty. Jeśli dane są przekazywane za jednym razem, rozmiar bloku jest ignorowany. Tę wartość można ustawić przy użyciu metody setMaxSingleUploadSizeLong .
  • maxConcurrency: maksymalna liczba żądań równoległych wydanych w danym momencie w ramach pojedynczego transferu równoległego. Tę wartość można ustawić przy użyciu metody setMaxConcurrency .

Upewnij się, że masz następującą import dyrektywę, aby używać ParallelTransferOptions do przesyłania plików.

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

Poniższy przykład kodu pokazuje, jak ustawić wartości dla parallelTransferOptions i uwzględnić opcje w ramach wystąpienia BlobUploadFromFileOptions . Wartości podane w tym przykładzie nie są przeznaczone do zalecenia. Aby prawidłowo dostosować te wartości, należy wziąć pod uwagę konkretne potrzeby aplikacji.

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

Aby dowiedzieć się więcej na temat dostrajania opcji transferu danych, zobacz Dostosowywanie wydajności przekazywania i pobierania za pomocą języka Java.

Prześlij blokowy blob z indeksującymi tagami

Tagi indeksu obiektów blob kategoryzują dane w Twoim koncie magazynowym za pomocą atrybutów tagów klucz-wartość. Te tagi są automatycznie indeksowane i uwidaczniane jako indeks wielowymiarowy z możliwością wyszukiwania w celu łatwego znajdowania danych.

Poniższy przykład przesyła blok blob z tagami indeksu ustawionymi przy użyciu 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());
    }
}

Ustaw warstwę dostępu obiektu blob podczas przesyłania

Poziom dostępu obiektu blob można ustawić w trakcie przesyłania przy użyciu klasy BlobUploadFromFileOptions. W poniższym przykładzie kodu pokazano, jak ustawić warstwę dostępu podczas przesyłania obiektu 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());
    }
}

Ustawienie warstwy dostępu jest dozwolone tylko dla blobów blokowych. Warstwę dostępu dla blokowego obiektu blob można ustawić na Hot, Cool, Cold lub Archive. Aby ustawić warstwę dostępu na Cold, należy użyć minimalnej wersji biblioteki klienta 12.21.0.

Aby dowiedzieć się więcej na temat warstw dostępu, zobacz Omówienie warstw dostępu.

Przekazywanie blokowego obiektu blob poprzez etapowanie bloków i ich zatwierdzanie

Możesz mieć większą kontrolę nad sposobem dzielenia przesyłania na bloki, ręcznie organizując poszczególne bloki danych. Gdy wszystkie bloki tworzące obiekt blob są przygotowane, można je zatwierdzić w usłudze Blob Storage. Za pomocą tego podejścia można zwiększyć wydajność, przekazując bloki równolegle.

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

Zasoby

Aby dowiedzieć się więcej na temat przekazywania obiektów blob przy użyciu biblioteki klienta usługi Azure Blob Storage dla języka Java, zobacz następujące zasoby.

Przykłady kodu

Operacje interfejsu API REST

Zestaw Azure SDK dla języka Java zawiera biblioteki, które bazują na interfejsie API REST platformy Azure, co umożliwia interakcję z operacjami interfejsu API REST za pomocą znanych paradygmatów języka Java. Metody biblioteki klienta do przekazywania obiektów blob używają następujących operacji interfejsu API REST:

Zasoby biblioteki klienta

Zobacz też

Powiązana zawartość

  • Ten artykuł jest częścią przewodnika dla deweloperów usługi Blob Storage dla języka Java. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów w temacie Tworzenie aplikacji Java.