Rychlý start: Klientská knihovna Azure Blob Storage pro Javu SE

Poznámka:

Možnost Build from Scratch vás provede vytvořením projektu, instalací balíčků, psaním kódu a spuštěním základní konzolové aplikace. Vyberte tuto možnost, abyste pochopili, jak vytvořit aplikaci, která se připojí k Azure Blob Storage. Pro automatizaci úkolů nasazení a zahájení s dokončeným projektem zvolte Začít s šablonou.

Poznámka:

Možnost Start with the template využívá Azure Developer CLI k automatizaci úloh nasazení a poskytuje dokončený projekt. Zvolte tuto možnost pro prozkoumání kódu bez dokončení nastavovacích úkolů. Pro podrobné instrukce k vytvoření aplikace zvolte Build from scratch.

Začínáme s klientskou knihovnou Azure Blob Storage pro Javu pro správu objektů blob a kontejnerů

V tomto článku provedete instalaci balíčku a vyzkoušení ukázkového kódu pro základní úlohy.

V tomto článku pomocí Azure Developer CLI nasadíte prostředky Azure a spustíte dokončenou konzolovou aplikaci pomocí několika příkazů.

Tip

Pro Spring aplikace, které využívají zdroje Azure Storage, zvažte Spring Cloud Azure. Tento open-source projekt integruje Spring se službami Azure. Pro příklad Blob Storage viz Nahrat soubor do Azure Storage Blob.

Referenční dokumentace k rozhraní API | Zdrojový kód knihovny | Balíček (Maven) | Ukázky

Požadavky

Nastavení

Tato část vás provede přípravou projektu pro práci s klientskou knihovnou Azure Blob Storage pro Javu.

Vytvoření projektu

Vytvořte aplikaci v Javě s názvem blob-quickstart.

  1. V okně konzoly (například PowerShell nebo Bash) pomocí Mavenu vytvořte novou konzolovou aplikaci s názvem blob-quickstart. Zadáním následujícího příkazu mvn vytvořte "Hello world!" Projekt Java.

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.blobs.quickstart `
    --define artifactId=blob-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. Zkontrolujte výstupy z generování projektu.

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.056 s
[INFO] Finished at: 2019-10-23T11:09:21-07:00
[INFO] ------------------------------------------------------------------------
    ```

  3. Přepněte do nově vytvořené složky blob-quickstart .

    cd blob-quickstart

  4. Uvnitř adresáře blob-quickstart vytvořte další adresář nazvaný data. Tato složka slouží k vytváření a ukládání datových souborů blobů.

    mkdir data

Instalace balíčků

Otevřete soubor v textovém pom.xml editoru.

Přidejte azure-sdk-bom , abyste mohli využívat závislost na nejnovější verzi knihovny. V následujícím fragmentu {bom_version_to_target} kódu nahraďte zástupný symbol číslem verze. Použitím azure-sdk-bom nemusíte specifikovat verzi každé jednotlivé závislosti. Další informace o BOM najdete v souboru README pro Azure SDK.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Potom do skupiny závislostí přidejte následující prvky závislostí. Potřebujete závislost Azure-identity pro bezheslové připojení k Azure službám.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Nastavení architektury aplikace

V adresáři projektu vytvořte základní strukturu aplikace pomocí následujícího postupu:

  1. Přejděte k adresáři /src/main/java/com/blobs/quickstart.
  2. Otevřete soubor App.java ve vašem editoru
  3. Odstranění řádku System.out.println("Hello world!");
  4. Přidání nezbytných import direktiv

Kód by měl vypadat přibližně takto:

package com.blobs.quickstart;

/**
 * Azure Blob Storage quickstart
 */
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Použitím Azure Developer CLI můžete vytvořit úložný účet a spustit ukázkový kód jen několika příkazy. Projekt můžete spustit ve svém lokálním vývojovém prostředí nebo v DevContaineru.

Inicializace šablony Azure Developer CLI a nasazení prostředků

Z prázdného adresáře pomocí těchto kroků inicializujete azd šablonu, zřídíte prostředky Azure a začnete s kódem:

  • Naklonujte prostředky úložiště pro rychlý start z GitHubu a inicializujte šablonu místně:

    azd init --template blob-storage-quickstart-java

    Zobrazí se výzva k zadání následujících informací:

    • Název prostředí: Azure Developer CLI používá tuto hodnotu jako předponu pro všechny prostředky Azure, které vytváří. Název musí být jedinečný pro všechna předplatná Azure a musí mít délku 3 až 24 znaků. Název může obsahovat pouze číslice a malá písmena.

  • Přihlaste se k Azure:

    azd auth login

  • Zřízení a nasazení prostředků na Azure.

    azd up

    Zobrazí se výzva k zadání následujících informací:

    • Předplatné: Azure předplatné pro nasazení vašich zdrojů.
    • Lokalita: Oblast Azure pro nasazení vašich zdrojů.

    Dokončení nasazení může trvat několik minut. Výstup příkazu azd up obsahuje název nově vytvořeného účtu úložiště, který budete potřebovat později ke spuštění kódu.

Spuštění ukázkového kódu

V tomto okamžiku se prostředky nasadí do Azure a kód je téměř připravený ke spuštění. Následujícím postupem aktualizujte název účtu úložiště v kódu a spusťte ukázkovou konzolovou aplikaci:

  • Aktualizujte název účtu úložiště:
    1. V místním adresáři přejděte do adresáře blob-quickstart/src/main/java/com/blobs/quickstart .
    2. Otevřete soubor s názvem App.java v editoru. <storage-account-name> Vyhledejte zástupný symbol a nahraďte ho skutečným názvem účtu úložiště vytvořeného příkazemazd up.
    3. Uložte změny.
  • Spusťte projekt:
    1. Přejděte do adresáře blob-quickstart, který obsahuje soubor pom.xml. Zkompilujte projekt pomocí následujícího mvn příkazu: 
      mvn compile
    2. Zabalte kompilovaný kód v distribuovatelném formátu: 
      mvn package
    3. Spuštěním následujícího mvn příkazu spusťte aplikaci: 
      mvn exec:java
  • Prohlédněte si výstup: Tato aplikace vytvoří testovací soubor ve složce místních dat a nahraje ho do kontejneru v účtu úložiště. Příklad pak vypíše objekty blob v kontejneru a stáhne soubor s novým názvem, abyste mohli porovnat staré a nové soubory.

Další informace o tom, jak ukázkový kód funguje, najdete v příkladech kódu.

Po dokončení testování kódu se podívejte do části Vyčištění prostředků a odstraňte prostředky vytvořené příkazem azd up .

Objektový model

Azure Blob Storage je optimalizovaná pro ukládání obrovských objemů nestrukturovaných dat. Nestrukturovaná data nedodržují konkrétní datový model nebo definici, jako jsou textová nebo binární data. Blob Storage nabízí tři typy prostředků:

  • Účet úložiště
  • Kontejner v účtu úložiště
  • Objekt blob v kontejneru

Na následujícím diagramu jsou vztahy těchto prostředků.

Diagram zobrazující úložný účet, který obsahuje blob kontejner a blob.

K interakci s těmito prostředky použijte následující třídy Javy:

  • BlobServiceClient: Třída BlobServiceClient spravuje zdroje Azure Storage a blob kontejnery. Účet úložiště poskytuje obor názvů nejvyšší úrovně pro službu Blob.
  • BlobServiceClientBuilder: Třída BlobServiceClientBuilder poskytuje plynulé API pro konfiguraci a vytváření BlobServiceClient objektů.
  • BlobContainerClient: Třída BlobContainerClient spravuje Azure Storage kontejnery a jejich bloby.
  • BlobClient: Třída BlobClient spravuje Azure Storage bloby.
  • BlobItem: Třída BlobItem představuje jednotlivé objekty blob vrácené voláním listBlobs.

Příklady kódu

Tyto ukázkové fragmenty kódu ukazují, jak provádět následující akce s klientskou knihovnou služby Azure Blob Storage pro Javu:

Důležité

Přidejte závislosti a směrnice popsané v Nastavování , než použijete ukázky kódu.

Poznámka:

Šablona Azure Developer CLI obsahuje soubor s ukázkovým kódem, který už je zavedený. Následující příklady obsahují podrobnosti pro každou část vzorového kódu. Šablona implementuje doporučenou metodu ověřování bez hesla, jak je popsáno v části Ověřování v Azure . Použití připojovacího řetězce je uvedeno jako alternativa, ale v šabloně se nepoužívá a není doporučeno pro produkční kód.

Ověřování v Azure a autorizace přístupu k datům objektů blob

Žádosti aplikací do služby Azure Blob Storage musí být autorizované. Použití třídy poskytované klientskou knihovnou Azure Identity je doporučeným přístupem k implementaci připojení bez hesla ke službám Azure ve vašem kódu, včetně Blob Storage.

Žádosti o službu Azure Blob Storage můžete také autorizovat pomocí přístupového klíče účtu. Tento přístup by však měl být používán s opatrností. Vývojáři musí být pečliví, aby nikdy nezpřístupnili přístupový klíč v nezabezpečeném umístění. Každý, kdo má přístupový klíč, může autorizovat požadavky na účet úložiště a efektivně má přístup ke všem datům. DefaultAzureCredential nabízí vylepšené výhody správy a zabezpečení oproti klíči účtu, které umožňují ověřování bez hesla. Obě možnosti jsou demonstrována v následujícím příkladu.

DefaultAzureCredential je třída poskytovaná klientskou knihovnou Azure Identity pro Javu. DefaultAzureCredential podporuje více metod ověřování a určuje, kterou metodu použít za běhu. Tento přístup umožňuje vaší aplikaci používat různé metody ověřování v různých prostředích (místní a produkční) bez implementace kódu specifického pro prostředí.

V jakém pořadí a v jakých umístěních DefaultAzureCredential hledá přihlašovací údaje, najdete v přehledu knihovny Azure Identity.

Například vaše aplikace se může autentizovat pomocí přihlašovacích údajů do Visual Studio Code při lokálním vývoji. Vaše aplikace pak může po nasazení na Azure používat spravovanou identitu. Pro tento přechod nejsou vyžadovány žádné změny kódu.

Přiřazení rolí k uživatelskému účtu Microsoft Entra

Při místním vývoji se ujistěte, že uživatelský účet, který přistupuje k datům objektů blob, má správná oprávnění. K čtení a zápisu dat objektů blob budete potřebovat roli Storage Blob Data Contributor. Abyste mohli tuto roli přiřadit sami sobě, musíte mít přiřazenou roli Správce uživatelských přístupů nebo jinou roli, která zahrnuje akci Microsoft.Authorization/roleAssignments/write . Role Azure RBAC můžete uživateli přiřadit pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu. Další informace o roli Přispěvatel dat v objektech blob služby Storage najdete v tématu Přispěvatel dat objektů blob služby Storage. Další informace o dostupných oborech pro přiřazení rolí najdete v tématu Vysvětlení oboru pro Azure RBAC.

V tomto scénáři přiřadíte oprávnění k vašemu uživatelskému účtu, omezeného na účet úložiště, abyste postupovali podle zásady nejnižších oprávnění. Tento postup poskytuje uživatelům jenom minimální potřebná oprávnění a vytváří bezpečnější produkční prostředí.

Následující příklad přiřadí roli Přispěvatel dat v objektech blob služby Storage k vašemu uživatelskému účtu, který poskytuje přístup ke čtení i zápisu k datům objektů blob v účtu úložiště.

Důležité

Ve většině případů bude trvat minutu nebo dvě, než se přiřazení role rozšíří v Azure, ale ve výjimečných případech může trvat až osm minut. Pokud při prvním spuštění kódu dojde k chybám ověřování, chvíli počkejte a zkuste to znovu.

  1. Na webu Azure Portal vyhledejte svůj účet úložiště pomocí hlavního panelu hledání nebo levé navigace.

  2. Na stránce přehledu účtu úložiště v nabídce vlevo vyberte Řízení přístupu (IAM ).

  3. Na stránce Řízení přístupu (IAM) vyberte kartu Přiřazení rolí.

  4. V horní nabídce vyberte + Přidat a potom z výsledné rozevírací nabídky vyberte Přidat přiřazení role.

    Snímek obrazovky znázorňující, jak přiřadit roli

  5. Pomocí vyhledávacího pole vyfiltrujte výsledky podle požadované role. V tomto příkladu vyhledejte Úložiště Blob Data Contributor, vyberte odpovídající výsledek a poté zvolte Další.

  6. V části Přiřadit přístup vyberte Uživatel, skupina nebo instanční objekt a pak zvolte + Vybrat členy.

  7. V dialogovém okně vyhledejte své uživatelské jméno Microsoft Entra (obvykle vaše user@domain e-mailová adresa) a pak v dolní části dialogového okna zvolte Vybrat .

  8. Vyberte Zkontrolovat a přiřadit, abyste přešli na poslední stránku, a poté znovu vyberte Zkontrolovat a přiřadit, abyste proces dokončili.

Přihlášení a připojení kódu aplikace k Azure pomocí DefaultAzureCredential

Autorizujte přístup k datům ve svém úložném účtu podle následujících kroků:

  1. Autentizujte se pomocí stejného Microsoft Entra účtu, ke kterému jste přiřadili roli úložného účtu. Použijte Azure CLI, Visual Studio Code nebo Azure PowerShell.

    Přihlaste se k Azure přes Azure CLI pomocí následujícího příkazu:

    az login

  2. Pro použití DefaultAzureCredential, přidejte závislost azure-identity do pom.xml:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

  3. Přidejte tento kód do main metody. Když kód běží na vaší lokální pracovní stanici, používá vývojářské přihlašovací údaje prioritního nástroje, do kterého jste přihlášeni, k autentizaci v Azure, například Azure CLI nebo Visual Studio Code.

    /*
 * The default credential first checks environment variables for configuration
 * If environment configuration is incomplete, it will try managed identity
 */
DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

// 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(defaultCredential)
        .buildClient();

  4. Aktualizujte název úložného účtu v URI vašeho BlobServiceClient. Název úložného účtu najděte na přehledové stránce v portálu Azure.

    Snímek obrazovky znázorňující, jak najít název účtu úložiště

    Poznámka:

    Při nasazení do Azure se tento stejný kód dá použít k autorizaci požadavků na Azure Storage z aplikace spuštěné v Azure. V aplikaci ale musíte povolit spravovanou identitu v Azure. Pak nakonfigurujte účet úložiště tak, aby se tato spravovaná identita mohla připojit. Podrobné pokyny ke konfiguraci tohoto připojení mezi službami Azure najdete v kurzu ověřování z aplikací hostovaných v Azure.

Vytvoření kontejneru

Ve svém účtu úložiště vytvořte nový kontejner voláním metody createBlobContainer objektu blobServiceClient . V tomto příkladu kód připojí k názvu kontejneru hodnotu GUID, aby se zajistilo, že je jedinečný.

Přidejte tento kód na konec main metody:

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

Pro více informací a příklady viz Vytvořit blob kontejner v Javě.

Důležité

Názvy kontejnerů musí být malými písmeny. Další informace o pojmenování kontejnerů a objektů blob najdete v tématu Názvy kontejnerů, objektů blob a metadat a odkazování na ně.

Nahrát datové bloky do kontejneru

Objekt blob nahrajte do kontejneru, a to voláním metody uploadFromFile. Ukázkový kód vytvoří textový soubor v místním datovém adresáři pro nahrání do kontejneru.

Přidejte tento kód na konec main metody:

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

Pro více informací a příklady viz Nahrajte blob pomocí Java.

Seznam objektů blob v kontejneru

Voláním metody listBlobs vypište objekty blob v kontejneru. V tomto případě jste do kontejneru přidali pouze jeden blob, takže operace listing vrací jen ten jeden blob.

Přidejte tento kód na konec main metody:

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

Pro více informací a příklady viz Seznam blobů v Javě.

Stáhnout objekty blob

Stáhněte dříve vytvořený objekt blob voláním metody downloadToFile . Ukázkový kód přidává k názvu souboru příponu , DOWNLOAD abyste mohli vidět oba soubory v lokálním souborovém systému.

Přidejte tento kód na konec main metody:

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

Pro více informací a příklady viz Stáhněte blob pomocí Java.

Odstranění kontejneru

Následující kód čistí zdroje, které aplikace vytvořila, odstraněním celého kontejneru pomocí metody mazání . Odstraní také místní soubory vytvořené aplikací.

Aplikace se pozastaví, aby uživatel mohl zadat vstup, voláním System.console().readLine() před odstraněním blobu, kontejneru a místních souborů. Tato pauza vám dává možnost ověřit, že aplikace zdroje vytvořila správně, než je smaže.

Přidejte tento kód na konec main metody:

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

Pro více informací a příklady viz Smazat a obnovit blob kontejner v Javě.

Spuštění kódu

Tato aplikace vytvoří testovací soubor ve vaší místní složce a nahraje ho do úložiště objektů blob. Příklad pak vypíše objekty blob v kontejneru a stáhne soubor s novým názvem, abyste mohli porovnat staré a nové soubory.

Postupujte podle těchto kroků pro kompilaci, zabalení a spuštění kódu:

  1. Pomocí následujícího pom.xml příkazu přejděte do adresáře obsahujícího mvn soubor a zkompilujte projekt:
    mvn compile
  2. Zabalte kompilovaný kód v distribuovatelném formátu: 
    mvn package
  3. Spuštěním následujícího mvn příkazu spusťte aplikaci: 
    mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
    Pro zjednodušení kroku spuštění přidejte exec-maven-plugin do pom.xml a nakonfigurujte jej, jak je znázorněno v následujícím kódu: 
    <plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>1.4.0</version>
  <configuration>
    <mainClass>com.blobs.quickstart.App</mainClass>
    <cleanupDaemonThreads>false</cleanupDaemonThreads>
  </configuration>
</plugin>
    S touto konfigurací spusťte aplikaci následujícím příkazem: 
    mvn exec:java

Výstup aplikace je podobný následujícímu příkladu (hodnoty UUID vynechané pro čitelnost):

Azure Blob Storage - Java quickstart sample

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Než začnete s procesem čištění, zkontrolujte , jestli složka dat obsahuje dva soubory. Můžete je porovnat a sledovat, že jsou identické.

Vyčištění zdrojů

Po ověření souborů a dokončení testování stisknutím klávesy Enter odstraňte testovací soubory spolu s kontejnerem, který jste vytvořili v účtu úložiště. K odstranění prostředků můžete také použít Azure CLI.

Po dokončení tohoto rychlého startu vyčistěte prostředky, které jste vytvořili spuštěním následujícího příkazu:

azd down

Obdržíte výzvu k potvrzení smazání zdrojů. Potvrďte akci zadáním y .

Další krok

Ukázky Azure Storage a příručky pro vývojáře v JavěRychlý start: Rozšíření Quarkus pro Azure Blob StoragePoužití Spring Boot k nahrání souboru do Azure Blob Storage

  • Last updated on