Azure Storage Blob Clientbibliothek für Java – Version 12.24.1

  • Artikel

Azure Blob Storage ist die Objektspeicherlösung von Microsoft für die Cloud. Blob Storage ist für die Speicherung großer Mengen unstrukturierter Daten optimiert. Unstrukturierte Daten sind Daten, die keinem bestimmten Datenmodell und keiner bestimmten Definition entsprechen (also beispielsweise Text- oder Binärdaten).

Quellcode | API-Referenzdokumentation | DOKUMENTATION | ZUR REST-APIProduktdokumentation | Proben

Erste Schritte

Voraussetzungen

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der GA-Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste 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>

und fügen Sie dann die direkte Abhängigkeit ohne Versions-Tag in den Abschnitt „Abhängigkeit“ ein.

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

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Erstellen eines Speicherkontos

Zum Erstellen eines Speicherkontos können Sie das Azure-Portal oder die Azure CLI verwenden.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Ihre Speicherkonto-URL, die anschließend als <your-storage-account-url>identifiziert wird, wird wie folgt formatiert: http(s)://<storage-account-name>.blob.core.windows.net

Authentifizieren des Clients

Um mit dem Speicherdienst (Blob, Queue, Message, MessageId, File) zu interagieren, müssen Sie eine instance der Service Client-Klasse erstellen. Um dies zu ermöglichen, benötigen Sie die Konto-SAS-Zeichenfolge (Shared Access Signature) des Speicherkontos. Weitere Informationen finden Sie unter SAS Token.

Abrufen von Anmeldeinformationen

SAS-Token

a. Verwenden Sie den folgenden Azure CLI-Codeausschnitt, um das SAS-Token aus dem Speicherkonto abzurufen.

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

Beispiel:

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. Alternativ können Sie das KONTO-SAS-Token aus dem Azure-Portal abrufen.

  1. Wechseln Sie zu Ihrem Speicherkonto.
  2. Wählen Sie Shared access signature aus dem Menü auf der linken Seite aus.
  3. Klicken Sie auf Generate SAS and connection string (nach dem Setup)
Anmeldeinformationen für freigegebene Schlüssel

a. Verwenden Sie Kontoname und Kontoschlüssel. Kontoname ist Der Name Ihres Speicherkontos.

  1. Wechseln Sie zu Ihrem Speicherkonto.
  2. Wählen Sie Access keys aus dem Menü auf der linken Seite aus.
  3. Unter key1/key2 Kopieren des Feldinhalts Key

oder

b. Verwenden Sie die Verbindungszeichenfolge.

  1. Wechseln Sie zu Ihrem Speicherkonto.
  2. Wählen Sie Access keys aus dem Menü auf der linken Seite aus.
  3. Unter key1/key2 Kopieren des Feldinhalts Connection string

Wichtige Begriffe

Blob Storage ist für Folgendes konzipiert:

  • Speichern von Bildern oder Dokumenten direkt auf einem Browser
  • Speichern von Dateien für verteilten Zugriff
  • Video- und Audiostreaming
  • Schreiben in Protokolldateien
  • Speichern von Daten für Sicherung und Wiederherstellung, Notfallwiederherstellung und Archivierung
  • Speichern von Daten für Analysen durch einen lokalen oder von Azure gehosteten Dienst

URL-Format

Blobs können mit dem folgenden URL-Format adressiert werden: Die folgende URL adressiert ein Blob:

https://myaccount.blob.core.windows.net/mycontainer/myblob

Syntax von Ressourcen-URIs

Für das Speicherkonto enthält der Basis-URI für Blobvorgänge nur den Namen des Kontos:

https://myaccount.blob.core.windows.net

Bei einem Container enthält der Basis-URI den Namen des Kontos und den Namen des Containers:

https://myaccount.blob.core.windows.net/mycontainer

Für ein Blob enthält der Basis-URI den Namen des Kontos, den Namen des Containers und den Namen des Blobs:

https://myaccount.blob.core.windows.net/mycontainer/myblob

Beachten Sie, dass die oben genannten URIs für komplexere Szenarien wie benutzerdefinierte Domänennamen möglicherweise nicht enthalten sind.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Azure Storage-Blobaufgaben behandeln, einschließlich:

Erstellen der Datei BlobServiceClient

Erstellen Sie eine BlobServiceClient mithilfe der sasToken oben generierten.

BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

oder

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

Erstellen der Datei BlobContainerClient

Erstellen Sie mithilfe von BlobContainerClient .BlobServiceClient

BlobContainerClient blobContainerClient = blobServiceClient.getBlobContainerClient("mycontainer");

Erstellen Sie einen BlobContainerClient aus dem oben generierten Generator sasToken .

BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .containerName("mycontainer")
    .buildClient();

oder

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "mycontainer" + "?" + "<your-sasToken>")
    .buildClient();

Erstellen der Datei BlobClient

Erstellen Sie mithilfe von BlobClient .BlobContainerClient

BlobClient blobClient = blobContainerClient.getBlobClient("myblob");

oder

Erstellen Sie einen BlobClient aus dem oben generierten Generator sasToken .

BlobClient blobClient = new BlobClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .containerName("mycontainer")
    .blobName("myblob")
    .buildClient();

oder

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobClient blobClient = new BlobClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "mycontainer" + "/" + "myblob" + "?" + "<your-sasToken>")
    .buildClient();

Erstellen eines Containers

Erstellen Sie einen Container mit einem BlobServiceClient.

blobServiceClient.createBlobContainer("mycontainer");

oder

Erstellen Sie einen Container mit einem BlobContainerClient.

blobContainerClient.create();

Hochladen von Daten in ein Blob

Laden Sie BinaryData in ein Blob hoch, indem Sie ein BlobClient aus einem BlobContainerClientgenerierten verwenden.

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
String dataSample = "samples";
blobClient.upload(BinaryData.fromString(dataSample));

Hochladen eines Blobs aus einem Stream

Laden Sie aus einem InputStream in ein Blob hoch, indem Sie ein BlockBlobClient aus einem generierten BlobContainerClientverwenden.

BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("myblockblob").getBlockBlobClient();
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blockBlobClient.upload(dataStream, dataSample.length());
} catch (IOException e) {
    e.printStackTrace();
}

Hochladen eines Blobs aus dem lokalen Pfad

Laden Sie eine Datei mit BlobClient einem aus einem generierten in ein Blob hoch BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
blobClient.uploadFromFile("local-file.jpg");

Hochladen eines Blobs, falls noch kein Blob vorhanden ist

Laden Sie Daten in ein Blob hoch, und schlagen Sie fehl, wenn bereits eine vorhanden ist.

/*
 * Rather than use an if block conditioned on an exists call, there are three ways to upload-if-not-exists using
 * one network call instead of two. Equivalent options are present on all upload methods.
 */
// 1. The minimal upload method defaults to no overwriting
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length());
} catch (IOException e) {
    e.printStackTrace();
}

// 2. The overwrite flag can explicitly be set to false to make intention clear
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length(), false /* overwrite */);
} catch (IOException e) {
    e.printStackTrace();
}

// 3. If the max overload is needed, access conditions must be used to prevent overwriting
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    // Setting IfNoneMatch="*" ensures the upload will fail if there is already a blob at the destination.
    options.setRequestConditions(new BlobRequestConditions().setIfNoneMatch("*"));
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

Hochladen eines Blobs und Überschreiben, falls bereits vorhanden

Laden Sie Daten in ein Blob hoch, und überschreiben Sie alle vorhandenen Daten am Ziel.

/*
 * Rather than use an if block conditioned on an exists call, there are three ways to upload-if-exists in one
 * network call instead of two. Equivalent options are present on all upload methods.
 */
String dataSample = "samples";

// 1. The overwrite flag can explicitly be set to true. This will succeed as a create and overwrite.
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length(), true /* overwrite */);
} catch (IOException e) {
    e.printStackTrace();
}

/*
 * 2. If the max overload is needed and no access conditions are passed, the upload will succeed as both a
 * create and overwrite.
 */
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

/*
 * 3. If the max overload is needed, access conditions may be used to assert that the upload is an overwrite and
 * not simply a create.
 */
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    // Setting IfMatch="*" ensures the upload will succeed only if there is already a blob at the destination.
    options.setRequestConditions(new BlobRequestConditions().setIfMatch("*"));
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

Hochladen eines Blobs über ein OutputStream

Laden Sie ein Blob hoch, indem Sie ein BlobOutputStream öffnen und über Standardstream-APIs in das Blob schreiben.

/*
 * Opening a blob input stream allows you to write to a blob through a normal stream interface. It will not be
 * committed until the stream is closed.
 * This option is convenient when the length of the data is unknown.
 * This can only be done for block blobs. If the target blob already exists as another type of blob, it will
 * fail.
 */
try (BlobOutputStream blobOS = blobClient.getBlockBlobClient().getBlobOutputStream()) {
    blobOS.write(new byte[0]);
} catch (IOException e) {
    e.printStackTrace();
}

Herunterladen von Daten aus einem Blob

Laden Sie ein Blob mithilfe von in ein OutputStream herunter BlobClient.

BinaryData content = blobClient.downloadContent();

Herunterladen eines Blobs in einen Stream

Laden Sie ein Blob mithilfe von in ein OutputStream herunter BlobClient.

try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
    blobClient.downloadStream(outputStream);
} catch (IOException e) {
    e.printStackTrace();
}

Herunterladen eines Blobs in den lokalen Pfad

Laden Sie das Blob mithilfe von in eine lokale Datei herunter BlobClient.

blobClient.downloadToFile("downloaded-file.jpg");

Lesen eines Blobs über einen InputStream

Laden Sie ein Blob herunter, indem Sie ein BlobInputStream öffnen und über Standardstream-APIs lesen.

/*
 * Opening a blob input stream allows you to read from a blob through a normal stream interface. It is also
 * mark-able.
*/
try (BlobInputStream blobIS = blobClient.openInputStream()) {
    blobIS.read();
} catch (IOException e) {
    e.printStackTrace();
}

Auflisten von Blobs

Auflisten aller Blobs mithilfe von BlobContainerClient.

for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("This is the blob name: " + blobItem.getName());
}

oder

Listen Sie alle Blobs auf, und erstellen Sie neue Clients, die auf die Elemente zeigen.

for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    BlobClient blobClient;
    if (blobItem.getSnapshot() != null) {
        blobClient = blobContainerClient.getBlobClient(blobItem.getName(), blobItem.getSnapshot());
    } else {
        blobClient = blobContainerClient.getBlobClient(blobItem.getName());
    }
    System.out.println("This is the new blob uri: " + blobClient.getBlobUrl());
}

Kopieren eines Blobs

Kopieren eines Blobs. Weitere Informationen zu den Anforderungen an die Kopierquelle und deren Authentifizierung finden Sie in den Javadocs für jede dieser Methoden.

SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<url-to-blob>", Duration.ofSeconds(1));
poller.waitForCompletion();

oder

blobClient.copyFromUrl("url-to-blob");

Generieren eines SAS-Tokens

Verwenden Sie eine instance eines Clients, um ein neues SAS-Token zu generieren.

/*
 * Generate an account sas. Other samples in this file will demonstrate how to create a client with the sas
 * token.
 */
// Configure the sas parameters. This is the minimal set.
OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);
AccountSasPermission accountSasPermission = new AccountSasPermission().setReadPermission(true);
AccountSasService services = new AccountSasService().setBlobAccess(true);
AccountSasResourceType resourceTypes = new AccountSasResourceType().setObject(true);

// Generate the account sas.
AccountSasSignatureValues accountSasValues =
    new AccountSasSignatureValues(expiryTime, accountSasPermission, services, resourceTypes);
String sasToken = blobServiceClient.generateAccountSas(accountSasValues);

// Generate a sas using a container client
BlobContainerSasPermission containerSasPermission = new BlobContainerSasPermission().setCreatePermission(true);
BlobServiceSasSignatureValues serviceSasValues =
    new BlobServiceSasSignatureValues(expiryTime, containerSasPermission);
blobContainerClient.generateSas(serviceSasValues);

// Generate a sas using a blob client
BlobSasPermission blobSasPermission = new BlobSasPermission().setReadPermission(true);
serviceSasValues = new BlobServiceSasSignatureValues(expiryTime, blobSasPermission);
blobClient.generateSas(serviceSasValues);

Authentifizieren mit einer Azure-Identität

Die Azure Identity-Bibliothek bietet Azure Active Directory-Unterstützung für die Authentifizierung mit Azure Storage.

BlobServiceClient blobStorageClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Festlegen eines Proxys beim Erstellen eines Clients

ProxyOptions options = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 888));
BlobServiceClient client = new BlobServiceClientBuilder()
    .httpClient(new NettyAsyncHttpClientBuilder().proxy(options).build())
    .buildClient();

oder

Lassen Sie es dem Client-Generator zu, den HttpClient zu verwendenden Typ zu bestimmen, aber erstellen Sie ihn mit übergebenen Konfigurationen.

HttpClientOptions clientOptions = new HttpClientOptions()
    .setProxyOptions(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 888)));
BlobServiceClient client = new BlobServiceClientBuilder()
    .clientOptions(clientOptions)
    .buildClient();

Problembehandlung

Bei der Interaktion mit Blobs mithilfe dieser Java-Clientbibliothek entsprechen vom Dienst zurückgegebene Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden. Wenn Sie beispielsweise versuchen, einen Container oder Blob abzurufen, der in Ihrem Speicherkonto nicht vorhanden ist, wird ein 404 Fehler zurückgegeben, der angibt Not Found.

HTTP-Standardclient

Alle Clientbibliotheken verwenden standardmäßig den Netty-HTTP-Client. Durch Hinzufügen der obigen Abhängigkeit wird die Clientbibliothek automatisch für die Verwendung des Netty-HTTP-Clients konfiguriert. Das Konfigurieren oder Ändern des HTTP-Clients wird detailliert im Wiki zu HTTP-Clients beschrieben.

SSL-Standardbibliothek

Alle Clientbibliotheken verwenden standardmäßig die Tomcat-native Boring-SSL-Bibliothek, um die Leistung auf nativer Ebene für SSL-Vorgänge zu ermöglichen. Die Boring-SSL-Bibliothek ist eine Uber-JAR-Datei mit nativen Bibliotheken für Linux/macOS/Windows und bietet im Vergleich zur SSL-Standardimplementierung im JDK eine bessere Leistung. Weitere Informationen, einschließlich zur Reduzierung der Abhängigkeitsgröße, finden Sie im Abschnitt Leistungsoptimierung des Wikis.

Nächste Schritte

Im GitHub-Repository des SDK stehen Ihnen mehrere Beispiele für Das Java SDK für Storage-Blobs zur Verfügung. Diese Beispiele enthalten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Key Vault auftreten:

Beispiele für nächste Schritte

Die Beispiele werden hier ausführlich erläutert.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe