Erste Schritte mit Azure Blob Storage und Java

Artikel
10/28/2024

In diesem Artikel erfahren Sie, wie Sie mithilfe der Azure Blob Storage-Clientbibliothek für Java eine Verbindung mit Azure Blob Storage herstellen. Verwenden Sie nach der Verbindung die Entwicklerhandbücher, um zu erfahren, wie Ihr Code mit Containern, Blobs und Funktionen des Blob Storage-Diensts arbeiten kann.

Wenn Sie mit einem vollständigen Beispiel beginnen möchten, lesen Sie den Schnellstart: Azure Blob Storage-Clientbibliothek für Java.

API-Referenz | Paket (Maven) | Bibliotheksquellcode | Beispiele | Feedback geben

Voraussetzungen

Azure-Abonnement – Erstellen eines kostenlosen Kontos
Azure Storage-Konto – Erstellen eines Speicherkontos
Java Development Kit (JDK), Version 8 oder höher
Für die Projektverwaltung wird in diesem Beispiel Apache Maven verwendet.

Einrichten des Projekts

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.

Verwenden Sie Maven, um eine neue Konsolen-App zu erstellen oder ein vorhandenes Projekt zu öffnen. Führen Sie die folgenden Schritte zum Installieren von Paketen und Hinzufügen der erforderlichen import-Anweisungen aus.

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.

BOM-Datei einfügen

Fügen Sie azure-sdk-bom hinzu, um eine Abhängigkeit von der neuesten Version der Bibliothek herzustellen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Indem Sie azure-sdk-bom verwenden, müssen Sie nicht die Version jeder einzelnen Abhängigkeit angeben. Weitere Informationen zur BOM finden Sie in der Azure SDK-BOM-Infodatei.

<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>

Fügen Sie der Gruppe der Abhängigkeiten das folgende Abhängigkeitselement hinzu: Die azure-identity-Abhängigkeit wird für kennwortlose Verbindungen mit Azure-Diensten benötigt.

<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>

Einbeziehen einer direkten Abhängigkeit

Zur Übernahme der Abhängigkeit von einer bestimmten Version der Bibliothek fügen Sie Ihrem Projekt die direkte Abhängigkeit hinzu:

<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>

Einbeziehen von Importanweisungen

Öffnen Sie dann Ihre Codedatei, und fügen Sie die erforderlichen import-Anweisungen hinzu. In diesem Beispiel fügen Sie die folgenden Anweisungen in der Datei App.java hinzu:

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

Informationen zur Blob-Clientbibliothek:

com.azure.storage.blob enthält die primären Klassen (Clientobjekte), die Sie für den Betrieb mit dem Dienst, Containern und Blobs verwenden können.
com.azure.storage.blob.models enthält Hilfsklassen, Strukturen und Enumerationstypen.
com.azure.storage.blob.specialized enthält Klassen, die Sie zum Ausführen spezifischer Vorgänge für einen Blobtyp verwenden können (z. B. Blobs anfügen).

Autorisieren des Zugriffs und Herstellen einer Verbindung mit Blob Storage

Um eine Verbindung zwischen einer App und Blob Storage herzustellen, erstellen Sie eine Instanz der Klasse BlobServiceClient. Sie können auch die BlobServiceAsyncClient-Klasse für asynchrone Programmierung verwenden. Dieses Objekt ist Ihr Ausgangspunkt für die Interaktion mit Datenressourcen auf Speicherkontoebene. Sie können es verwenden, um das Speicherkonto und seine Container zu verwenden. Sie können den Dienstclient auch verwenden, um Containerclients oder Blobclients zu erstellen, je nachdem, mit welcher Ressource Sie arbeiten müssen.

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

Sie können ein BlobServiceClient-Objekt mithilfe eines Microsoft Entra-Autorisierungstokens, eines Kontozugriffsschlüssels oder einer freigegebenen Zugriffssignatur (SHARED Access Signature, SAS) autorisieren. Um optimale Sicherheit zu gewährleisten, empfiehlt Microsoft möglichst die Verwendung von Microsoft Entra ID mit verwalteten Identitäten, um Anforderungen für Blobdaten zu autorisieren. Weitere Informationen finden Sie unter Autorisieren des Zugriffs auf Blobs mit Microsoft Entra ID.

Um mit Microsoft Entra-ID zu autorisieren, müssen Sie einen Sicherheitsprinzipalverwenden. Der Typ des für Sie erforderlichen Sicherheitsprinzipals ist abhängig davon, wo Ihre App ausgeführt wird. Verwenden Sie die folgende Tabelle als Richtlinie:

Ausführungsort der App	Sicherheitsprinzipal	Leitfaden
Lokaler Computer (Entwickeln und Testen)	Dienstprinzipal	Informationen zum Registrieren der App, zum Einrichten einer Microsoft Entra-Gruppe, zum Zuweisen von Rollen und zum Konfigurieren von Umgebungsvariablen finden Sie unter Zugriff über Entwicklerdienstprinzipien autorisieren.
Lokaler Computer (Entwickeln und Testen)	Benutzeridentität	Informationen zum Einrichten einer Microsoft Entra-Gruppe, zum Zuweisen von Rollen und zum Anmelden bei Azure finden Sie unter Zugriff mit Entwickleranmeldeinformationen autorisieren.
In Azure gehostet	Verwaltete Identität	Informationen zum Aktivieren einer verwalteten Identität und zum Zuweisen von Rollen finden Sie unter Autorisieren des Zugriffs von in Azure gehosteten Apps mithilfe einer verwalteten Identität.
Außerhalb von Azure gehostet (z. B. lokale Apps)	Dienstprinzipal	Informationen zum Registrieren der App, zum Zuweisen von Rollen und zum Konfigurieren von Umgebungsvariablen finden Sie unter Authenticate to Azure resources from Python apps hosted on-premises (Authentifizieren bei Azure-Ressourcen mit lokal gehosteten Python-Apps).

Autorisieren des Zugriffs mithilfe von DefaultAzureCredential

Eine einfache und sichere Möglichkeit zum Autorisieren des Zugriffs und zum Herstellen einer Verbindung mit Blob Storage ist das Abrufen eines OAuth-Tokens durch Erstellung einer DefaultAzureCredential-Instanz. Anschließend können Sie mithilfe dieser Anmeldeinformationen ein BlobServiceClient-Objekt erstellen.

Stellen Sie sicher, dass Sie über die richtigen Abhängigkeiten in „pom.xml“ und über die notwendigen Anweisungen verfügen, die im Abschnitt Einrichten Ihres Projekts beschrieben sind.

Im folgenden Beispiel wird BlobServiceClientBuilder verwendet, um ein BlobServiceClient-Objekt mithilfe von DefaultAzureCredential zu erstellen, und gezeigt, 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>");

Verwenden Sie BlobServiceClientBuilder, um ein BlobServiceClient-Objekt mit einem SAS-Token zu erstellen:

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

Weitere Informationen zum Generieren und Verwalten von SAS-Token finden Sie in den folgenden Artikeln:

Hinweis

Für Szenarien, in denen SAS (Shared Access Signatures) verwendet werden, empfiehlt Microsoft die Verwendung einer Benutzerdelegierungs-SAS. Eine Benutzerdelegierungs-SAS wird mit Microsoft Entra-Anmeldeinformationen und nicht mithilfe des Kontoschlüssels geschützt.

Erstellen Sie mithilfe des Speicherkontonamens und des Kontoschlüssels ein storageSharedKeyCredential. Verwenden Sie dann dieses Objekt, um ein BlobServiceClient-Objekt zu initialisieren.

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

Sie können ein BlobServiceClient-Objekt auch mithilfe einer Verbindungszeichenfolge erstellen.

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

Informationen zum Abrufen von Kontoschlüsseln und Best Practices-Richtlinien für die ordnungsgemäße Verwaltung und Sicherung Ihrer Schlüssel finden Sie unter Verwalten von Speicherkonto-Zugriffsschlüsseln.

Wichtig

Der Kontozugriffsschlüssel sollte mit Vorsicht verwendet werden. Wenn Ihr Kontozugriffsschlüssel verloren geht oder versehentlich an einem unsicheren Ort gespeichert wird, kann Ihr Dienst anfällig werden. Jeder, der über den Zugriffsschlüssel verfügt, kann Anforderungen für das Speicherkonto autorisieren und hat somit Zugriff auf alle Daten. DefaultAzureCredential bietet erweiterte Sicherheitsfeatures und Vorteile und ist der empfohlene Ansatz zum Verwalten der Autorisierung für Azure-Dienste.

Konfigurieren der JVM TTL für DNS-Namensuchvorgänge

Java Virtual Machine (JVM) speichert Antworten aus erfolgreichen DNS-Namensuchvorgängen für einen bestimmten Zeitraum zwischen, der als Time-to-Live (TTL) bezeichnet wird. Der Standard-TTL-Wert für viele JVMs lautet -1, was bedeutet, dass der JVM die Antwort unbegrenzt zwischenspeichert oder bis der JVM neu gestartet wird.

Da Azure-Ressourcen DNS-Namenseinträge verwenden, die sich ändern können, empfehlen wir, den JVM-TTL-Wert auf 10 Sekunden festzulegen. Diese Konfiguration stellt sicher, dass eine aktualisierte IP-Adresse für eine Ressource mit der nächsten DNS-Abfrage zurückgegeben wird.

Wenn Sie den TTL-Wert global für alle Anwendungen ändern möchten, die JVM verwenden, legen Sie die networkaddress.cache.ttl-Eigenschaft in der java.security-Datei fest.

networkaddress.cache.ttl=10

Für Java 8 befindet sich die java.security-Datei im $JAVA_HOME/jre/lib/security-Verzeichnis. Für Java 11 und höher befindet sich die Datei im $JAVA_HOME/conf/security-Verzeichnis.

Erstellen der App

Wenn Sie Apps für die Arbeit mit Datenressourcen in Azure Blob Storage erstellen, interagiert Ihr Code primär mit drei Ressourcentypen: Speicherkonten, Container und Blobs. Weitere Informationen zu diesen Ressourcentypen, deren Beziehung zueinander und zur Interaktion von Apps mit Ressourcen finden Sie unter Grundlegendes zur Interaktion von Apps mit Blob Storage-Datenressourcen.

In den folgenden Anleitungen wird gezeigt, wie Sie mithilfe der Azure Storage-Clientbibliothek für Java auf Daten zugreifen und bestimmte Aktionen ausführen:

Handbuch	Beschreibung
Konfigurieren einer Wiederholungsrichtlinie	Implementieren Sie Wiederholungsrichtlinien für Clientvorgänge.
Kopieren von Blobs	Kopieren Sie ein Blob von einem Speicherort an einen anderen.
Container erstellen	Erstellen Sie Blobcontainer.
Erstellen einer SAS für die Benutzerdelegierung	Erstellen Sie eine SAS für die Benutzerdelegierung für einen Container oder ein Blob.
Erstellen und Verwalten von Blobleases	Richten Sie eine Sperre für ein Blob ein, und verwalten Sie sie.
Erstellen und Verwalten von Containerleases	Richten Sie eine Sperre für einen Container ein, und verwalten Sie sie.
Löschen und Wiederherstellen von Blobs	Löschen von Blobs und Wiederherstellen gelöschter Blobs, wenn das vorläufige Löschen aktiviert ist.
Löschen und Wiederherstellen von Containern	Löschen von Containern und Wiederherstellen gelöschter Container, für die vorläufiges Löschen aktiviert ist.
Herunterladen von Blobs	Herunterladen von Blobs mithilfe von Zeichenfolgen, Streams und Dateipfaden.
Suchen von Blobs mithilfe von Tags	Festlegen und Abrufen von Tags sowie Verwendung von Tags zum Suchen von Blobs.
Auflisten von Blobs	Auflisten von Blobs auf unterschiedliche Weise.
Auflisten von Containern	Auflisten von Containern in einem Konto und der verschiedenen verfügbaren Optionen zum Anpassen einer Auflistung.
Verwalten von Eigenschaften und Metadaten (Blobs)	Abrufen und Festlegen von Eigenschaften und Metadaten für Blobs.
Verwalten von Eigenschaften und Metadaten (Container)	Abrufen und Festlegen von Eigenschaften und Metadaten für Container.
Leistungsoptimierung für Datenübertragungen	Optimieren Sie die Leistung für Datenübertragungsvorgänge.
Festlegen oder Ändern der Zugriffsebene eines Blobs	Legen Sie die Zugriffsebene für ein Blockblob fest, oder ändern Sie sie.
Hochladen von Blobs	Erfahren Sie, wie Sie Blobs mithilfe von Zeichenfolgen, Streams, Dateipfaden und anderen Methoden hochladen.

Teilen über