Začínáme se službou Azure Blob Storage a Javou

Článek
10/22/2024

V tomto článku se dozvíte, jak se připojit ke službě Azure Blob Storage pomocí klientské knihovny azure Blob Storage pro Javu. Po připojení se pomocí příruček pro vývojáře dozvíte, jak váš kód funguje s kontejnery, objekty blob a funkcemi služby Blob Storage.

Pokud chcete začít s úplným příkladem, podívejte se na rychlý start: Klientská knihovna Azure Blob Storage pro Javu.

Referenční | balíček rozhraní API (Maven) | Ukázky | zdrojového kódu | knihovny zpětnou vazbu

Požadavky

Předplatné Azure – vytvoření bezplatného předplatného
Účet úložiště Azure – Vytvoření účtu úložiště
Java Development Kit (JDK) verze 8 nebo novější
Apache Maven se používá pro řízení projektů v tomto příkladu.

Nastavení projektu

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.

Pomocí Mavenu vytvořte novou konzolovou aplikaci nebo otevřete existující projekt. Podle těchto kroků nainstalujte balíčky a přidejte potřebné import direktivy.

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.

Zahrnutí souboru kusovníku

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í azure-sdk-bom vám umožní určit verzi jednotlivých závislostí. Další informace o kusovníku 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>

Do skupiny závislostí přidejte následující prvky závislostí. Závislost azure-identity je potřebná pro připojení bez hesla ke službám Azure.

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

Zahrnutí přímé závislosti

Pokud chcete závislosti na konkrétní verzi knihovny, přidejte do projektu přímou závislost:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>{package_version_to_target}</version>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
      <version>{package_version_to_target}</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{package_version_to_target}</version>
</dependency>

Zahrnout direktivy importu

Pak otevřete soubor kódu a přidejte potřebné import direktivy. V tomto příkladu přidáme do souboru App.java následující direktivy:

import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.specialized.*;
import com.azure.storage.common.*;

Informace o klientské knihovně objektů blob:

com.azure.storage.blob: Obsahuje primární třídy (klientské objekty), které můžete použít k provozu se službou, kontejnery a objekty blob.
com.azure.storage.blob.models: Obsahuje třídy nástrojů, struktury a typy výčtů.
com.azure.storage.blob.specialized: Obsahuje třídy, které můžete použít k provádění operací specifických pro typ objektu blob (například: doplňovací objekty blob).

Autorizace přístupu a připojení ke službě Blob Storage

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci třídy BlobServiceClient . K asynchronnímu programování můžete použít také třídu BlobServiceAsyncClient. Tento objekt je vaším výchozím bodem pro interakci s datovými prostředky na úrovni účtu úložiště. Můžete ho použít k provozu s účtem úložiště a jeho kontejnery. Klienta služby můžete také použít k vytvoření klientů kontejnerů nebo klientů objektů blob v závislosti na prostředku, se kterým potřebujete pracovat.

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.

Objekt můžete autorizovat BlobServiceClient pomocí autorizačního tokenu Microsoft Entra, přístupového klíče účtu nebo sdíleného přístupového podpisu (SAS). Pro zajištění optimálního zabezpečení microsoft doporučuje Microsoft Entra ID se spravovanými identitami autorizovat požadavky na data objektů blob. Další informace naleznete v tématu Autorizace přístupu k objektům blob pomocí Microsoft Entra ID.

Pokud chcete autorizovat s ID Microsoft Entra, budete muset použít objekt zabezpečení. Jaký typ objektu zabezpečení potřebujete, závisí na tom, kde vaše aplikace běží. Jako vodítko použijte následující tabulku:

Kde aplikace běží	Objekt zabezpečení	Pokyny
Místní počítač (vývoj a testování)	Instanční objekt	Pokud chcete zjistit, jak aplikaci zaregistrovat, nastavte skupinu Microsoft Entra, přiřaďte role a nakonfigurujte proměnné prostředí, přečtěte si téma Autorizace přístupu pomocí instančních objektů pro vývojáře.
Místní počítač (vývoj a testování)	Identita uživatele	Informace o nastavení skupiny Microsoft Entra, přiřazení rolí a přihlášení k Azure najdete v tématu Autorizace přístupu pomocí přihlašovacích údajů vývojáře.
Hostované v Azure	Spravovaná identita	Informace o povolení spravované identity a přiřazování rolí najdete v tématu Autorizace přístupu z aplikací hostovaných v Azure pomocí spravované identity.
Hostované mimo Azure (například místní aplikace)	Instanční objekt	Informace o registraci aplikace, přiřazení rolí a konfiguraci proměnných prostředí najdete v tématu Autorizace přístupu z místních aplikací pomocí instančního objektu aplikace.

Autorizace přístupu pomocí DefaultAzureCredential

Snadným a bezpečným způsobem autorizace přístupu a připojení ke službě Blob Storage je získání tokenu OAuth vytvořením instance DefaultAzureCredential . Tyto přihlašovací údaje pak můžete použít k vytvoření objektu BlobServiceClient .

Ujistěte se, že máte v pom.xml správné závislosti a potřebné direktivy importu, jak je popsáno v tématu Nastavení projektu.

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

Použití BlobServiceClientBuilder k sestavení objektu BlobServiceClient pomocí tokenu SAS:

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .sasToken(sasToken)
            .buildClient();

    return blobServiceClient;
}

Další informace o generování a správě tokenů SAS najdete v následujících článcích:

Poznámka:

Ve scénářích, ve kterých se používají sdílené přístupové podpisy (SAS), microsoft doporučuje používat SAS delegování uživatele. Sas delegování uživatele je zabezpečený pomocí přihlašovacích údajů Microsoft Entra místo klíče účtu.

Vytvořte StorageSharedKeyCredential pomocí názvu účtu úložiště a klíče účtu. Potom tento objekt použijte k inicializaci objektu BlobServiceClient .

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Azure SDK client builders accept the credential as a parameter
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))
            .credential(credential)
            .buildClient();

    return blobServiceClient;        
}

Objekt můžete vytvořit BlobServiceClient také pomocí připojovací řetězec.

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {
    // 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/")
            .connectionString(connectionString)
            .buildClient();

    return blobServiceClient;        
}

Informace o tom, jak získat klíče účtu a osvědčené postupy pro správnou správu a ochranu klíčů, najdete v tématu Správa přístupových klíčů k účtu úložiště.

Důležité

Přístupový klíč účtu by se měl používat s opatrností. Pokud dojde ke ztrátě nebo náhodnému umístění přístupového klíče k účtu do nezabezpečeného umístění, může být vaše služba zranitelná. 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 poskytuje vylepšené funkce a výhody zabezpečení a je doporučeným přístupem ke správě autorizace služeb Azure.

Konfigurace hodnoty TTL JVM pro vyhledávání názvů DNS

Virtuální počítač Java (JVM) ukládá odpovědi z úspěšných vyhledávání názvů DNS za určité časové období, označované jako TTL (time-to-live). Výchozí hodnota TTL pro mnoho virtuálních počítačů JVM je -1, což znamená, že JVM ukládá odpověď do mezipaměti po neomezenou dobu nebo dokud se počítač JVM nerestartuje.

Vzhledem k tomu, že prostředky Azure používají položky názvu DNS, které se můžou změnit, doporučujeme nastavit hodnotu TTL JVM na 10 sekund. Tato konfigurace zajišťuje, že se aktualizovaná IP adresa prostředku vrátí s dalším dotazem DNS.

Pokud chcete změnit hodnotu TTL globálně pro všechny aplikace používající JVM, nastavte networkaddress.cache.ttl vlastnost v java.security souboru.

networkaddress.cache.ttl=10

Pro Javu 8 java.security se soubor nachází v $JAVA_HOME/jre/lib/security adresáři. Pro Javu 11 a vyšší se soubor nachází v $JAVA_HOME/conf/security adresáři.

Sestavte aplikaci

Při vytváření aplikací pro práci s datovými prostředky ve službě Azure Blob Storage váš kód primárně komunikuje se třemi typy prostředků: účty úložiště, kontejnery a objekty blob. Další informace otěchtoch materiálech najdete v tématu Vysvětlení způsobu interakce aplikací s datovými prostředky blob Storage.

Následující příručky ukazují, jak získat přístup k datům a provádět konkrétní akce pomocí klientské knihovny Azure Storage pro Javu:

Průvodce	Popis
Konfigurace zásad opakování	Implementujte zásady opakování pro klientské operace.
Kopírování objektů blob	Zkopírujte objekt blob z jednoho umístění do druhého.
Vytvoření kontejneru	Vytvořte kontejnery objektů blob.
Vytvoření SAS delegování uživatele	Vytvořte SAS delegování uživatele pro kontejner nebo objekt blob.
Vytváření a správa zapůjčení objektů blob	Vytvořte a spravujte zámek objektu blob.
Vytváření a správa zapůjčení kontejnerů	Vytvořte a spravujte zámek kontejneru.
Odstranění a obnovení objektů blob	Odstraňte objekty blob a pokud je povolené obnovitelné odstranění, obnovte odstraněné objekty blob.
Odstranění a obnovení kontejnerů	Odstraňte kontejnery a pokud je povolené obnovitelné odstranění, obnovte odstraněné kontejnery.
Stažení objektů blob	Stáhněte objekty blob pomocí řetězců, datových proudů a cest k souborům.
Vyhledání objektů blob pomocí značek	Nastavte a načtěte značky a použijte značky k vyhledání objektů blob.
Výpis objektů blob	Výpis objektů blob různými způsoby
Výpis kontejnerů	Vypište kontejnery v účtu a různé možnosti, které můžete přizpůsobit výpis.
Správa vlastností a metadat (objektů blob)	Získejte a nastavte vlastnosti a metadata pro objekty blob.
Správa vlastností a metadat (kontejnerů)	Získejte a nastavte vlastnosti a metadata pro kontejnery.
Ladění výkonu pro přenosy dat	Optimalizujte výkon operací přenosu dat.
Nastavení nebo změna úrovně přístupu objektu blob	Nastavte nebo změňte úroveň přístupu pro objekt blob bloku.
Nahrání objektů blob	Naučte se nahrávat objekty blob pomocí řetězců, datových proudů, cest k souborům a dalších metod.

Sdílet prostřednictvím