Freigeben über

Azure Storage-Bibliotheken für Java

  • Artikel

Die Azure Storage-Bibliotheken für Java stellen Klassen für die Arbeit mit Daten in Ihrem Azure-Speicherkonto und mit dem Speicherkonto selbst bereit. Weitere Informationen zu Azure Storage finden Sie unter Einführung in Azure Storage.

Clientbibliothek für den Datenzugriff

Die Azure Storage-Clientbibliothek für Java unterstützt Blob Storage, Warteschlangenspeicher, Azure Files und Azure Data Lake Storage Gen2 (Vorschaubibliothek).

Hinzufügen des Pakets zu Ihrem Projekt

Fügen Sie der Maven-Datei pom.xml nach Bedarf die folgenden Abhängigkeiten hinzu:

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

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-queue</artifactId>
  <version>12.3.0</version>
</dependency>

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-file-share</artifactId>
  <version>12.2.0</version>
</dependency>

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-file-datalake</artifactId>
  <version>12.0.0-preview.6</version>
</dependency>

Weitere Informationen zum Hinzufügen einer Abhängigkeit in Java finden Sie unter Hinzufügen einer Abhängigkeit.

Beispielverwendung

Im folgenden Beispiel wird ein Speichercontainer erstellt und eine lokale Datei in den Speichercontainer hochgeladen.

String yourSasToken = "<insert-your-sas-token>";
/* Create a new BlobServiceClient with a SAS Token */
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("https://your-storage-account-url.storage.windows.net")
    .sasToken(yourSasToken)
    .buildClient();

/* Create a new container client */
try {
    containerClient = blobServiceClient.createBlobContainer("my-container-name");
} catch (BlobStorageException ex) {
    // The container may already exist, so don't throw an error
    if (!ex.getErrorCode().equals(BlobErrorCode.CONTAINER_ALREADY_EXISTS)) {
        throw ex;
    }
}

/* Upload the file to the container */
BlobClient blobClient = containerClient.getBlobClient("my-remote-file.jpg");
blobClient.uploadFromFile("my-local-file.jpg");

Weitere Beispiele finden Sie in der Infodatei zur Clientbibliothek.

Verfügbare Pakete

In der folgenden Tabelle werden die empfohlenen Versionen der Speicherclientbibliothek für Java beschrieben.

Bibliotheksversion Unterstützte Dienste Maven Referenz/Javadoc Quelle, Readme, Beispiele
Version 12 Blob, Warteschlange, Datei und Data Lake Blob
Warteschlange
Datei
Data Lake		 Blob
Warteschlange
Datei
Data Lake		 Blob (Schnellstart)
Warteschlange
Datei
Data Lake
Version 8 Blob, Warteschlange, Datei und Tabelle Alle Dienste Referenz zu Version 8 Alle Dienste (Schnellstart)

Weitere Informationen zum Installieren und Verwenden der Vorschaupakete finden Sie auf der Seite "Azure SDK Releases ".

Clientbibliothek für die Ressourcenverwaltung

Verwenden Sie den Azure Storage-Ressourcenanbieter, um Speicherkonten, Kontoschlüssel, Zugriffsebenen und vieles mehr zu verwalten. Um die Ressourcenanbieterbibliothek zu verwenden, fügen Sie ihrer Maven-Datei pom.xml eine Abhängigkeit hinzu. Die neueste Version der Ressourcenanbieterbibliothek ist auf Maven verfügbar.

Weitere Informationen zur Ressourcenanbieterbibliothek finden Sie in der Verwaltungsreferenz . Der Quellcode für die Ressourcenanbieterbibliothek ist im Repository des Azure Java SDK verfügbar.

Im folgenden Beispiel wird ein neues Speicherkonto in Ihrem Abonnement erstellt und dessen Zugriffsschlüssel abgerufen.

StorageAccount storageAccount = azureResourceManager.storageAccounts().define(storageAccountName)
    .withRegion(Region.US_EAST)
    .withNewResourceGroup(rgName)
    .create();

// get a list of storage account keys related to the account
List<StorageAccountKey> storageAccountKeys = storageAccount.getKeys();
for (StorageAccountKey key : storageAccountKeys) {
    System.out.println("Key name: " + key.keyName() + " with value "+ key.value());
}

Bekannte Probleme

Ältere Versionen des Azure Storage SDK für Java (v12) weisen ein oder mehrere bekannte kritische Probleme auf, die unten beschrieben werden. Diese Probleme können sich auf das Schreiben oder Lesen von Daten aus Ihrem Azure Storage-Konto auswirken. Wenn Sie eine ältere Version einer Clientbibliothek verwenden, wird empfohlen, auf die neueste Version zu aktualisieren.

Clientbibliothek Betroffener Versionen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Storage-Blob 12.0 bis 12.10.0, 12.19.0 bis 12.22.0 12.22.1 Update auf die aktuelle Version
Azure File Data Lake 12.0 bis 12.7.0 12.8.0 Update auf die aktuelle Version
Azure-Dateifreigabe 12.0 bis 12.4.1 12.5.0 Update auf die aktuelle Version
Azure Storage-Warteschlange 12.0 bis 12.6.0 12.7.0 Update auf die aktuelle Version
Azure Blob Storage Kryptografie 12.0 bis 12.16.1 12.17.0 Update auf die aktuelle Version

Wenn Sie Fragen haben oder zusätzliche Hilfe benötigen, erstellen Sie mithilfe der folgenden Optionen ein Supportticket :

  • Problemtyp: Technisch
  • Diensttyp: Blob Storage
  • Zusammenfassung: #JavaSDKv12
  • Problemtyp: Entwicklung
  • Problemuntertyp: Clientbibliothek oder SDK

Liste bekannter Probleme

  1. Pufferüberschreibungsproblem mit BlobOutputStream
  2. Ungültige Daten, die während Wiederholungsversuchen hochgeladen wurden
  3. Upload fälschlicherweise als erfolgreich zurückgegeben, wenn IOException eintritt
  4. Falsche Daten, die mit heruntergeladen werden downloadToFile
  5. Parameter überschreiben beim Hochladen großer Dateien nicht berücksichtigt, was zu einem falschen Überschreiben führt
  6. Overwrite-Vorgang für den Überschreibungsparameter umgekehrt, was zu einem falschen Überschreiben führt
  7. Der Nachrichteninhalt wurde fälschlicherweise gelöscht, wenn nur ein Timeout für die Sichtbarkeit festgelegt ist
  8. Clientseitige Verschlüsselung aktualisiert, um AES-GCM aufgrund von Sicherheitsrisiken im CBC-Modus zu verwenden
  9. Falsche Daten, die mit downloadToFile() heruntergeladen werden, wenn zugrunde liegende REST-Anforderungen wiederholt werden
  10. InvalidHeaderValue-Fehlermeldung bei Verwendung der Betaversion des SDK

1. Pufferüberschreibungsproblem mit BlobOutputStream

Problembeschreibung

Wenn ein BlobOutputStream Objekt zum Hochladen von Blobs verwendet wird, kann diese Verwendung in einigen Szenarien dazu führen, dass ein ungültiges Objekt in Azure Blob Storage geschrieben wird. BlobOutputStream -Objekt kann über BlockBlobClient.getBlobOutputStream()abgerufen werden.

Das Hochladen einer Datei, die größer als der Wert der MaxSingleUploadSize -write()Methode der BlobOutputStream -Klasse ist, führt dazu, dass ein ungültiges Objekt in Azure Blob Storage geschrieben wird. Der Standardwert von MaxSingleUploadSize ist 256 MiB. Sie können diesen Wert ändern, indem Sie die setMaxSingleUploadSizeLong() -Methode der ParallelTransferOptions -Klasse aufrufen.

Nachdem die Eingabedatengröße den MaxSingleUploadSizedurchkreuzt hat, gibt die write() BlobOutputStream-Methode zurück, bevor Sie eine tiefe Kopie der Eingabedaten erstellen. Wenn die aufrufende Anwendung das Eingabedatenbytearray mit anderen Daten überschreibt, bevor die tiefe Kopie erfolgt, werden möglicherweise ungültige Daten in das Blob geschrieben.

Details zum Problem

Clientbibliothek Betroffener Versionen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Storage-Blob 12.0 bis 12.10.0 12.10.1 Update auf die neueste Version oder mindestens 12.22.1
  1. Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.
  2. Überprüfen Sie, ob Ihr Anwendungscode aufruft BlockBlobClient.getBlobOutputStream(). Wenn Sie sie finden, ist Ihre Anwendung betroffen.

Darüber hinaus können Sie alle potenziell betroffenen Blobs aufgrund dieses Problems in Ihrem Azure Storage-Konto identifizieren. Führen Sie die folgenden Schritte aus, um potenziell betroffene Blobs zu identifizieren:

  1. Überprüfen Sie, ob Ihre Anwendung verwendet, BlobOutputStream um Blobs hochzuladen (abgerufen über BlockBlobClient.getBlobOutputStream()). Wenn dies nicht der Fall ist, wirkt sich dieses Problem nicht auf Ihre Anwendung aus. Es wird jedoch weiterhin empfohlen, ein Upgrade Ihrer Anwendung auf die Verwendung von Version 12.22.1 oder höher durchzuführen.
  2. Rufen Sie den MaxSingleUploadSize Wert für Ihre Anwendung ab (standardmäßig 256 MiB). Überprüfen Sie Ihren Code auf setMaxSingleUploadSizeLong() die Methode der ParallelTransferOptions -Klasse, und rufen Sie den Wert ab, den Sie für diese Eigenschaft angegeben haben.
  3. Identifizieren sie das Zeitfenster, in dem Ihre Anwendung die Clientbibliotheksversion mit diesem Problem verwendet hat (12.0 bis 12.10.0).
  4. Identifizieren Sie alle blobs, die in diesem Zeitfenster hochgeladen wurden. Sie können eine Liste der Blobs abrufen, indem Sie den List Blobs Vorgang mit PowerShell PowerShell, der Azure CLI oder einem anderen Tool aufrufen. Sie können auch die Blobinventurfunktion nutzen.

Wenn Sie diese Schritte ausführen, werden Blobs angezeigt, die möglicherweise von dem kritischen Problem betroffen sind und möglicherweise ungültig sind. Überprüfen Sie diese Blobs, um zu ermitteln, welche möglicherweise ungültig sind.

Zurück zur Liste der bekannten Probleme

2. Ungültige Daten, die während Wiederholungen hochgeladen werden

Problembeschreibung

Die unten aufgeführten Clientbibliotheken weisen einen Fehler auf, der falsche Daten während Wiederholungsversuchen nach einer fehlgeschlagenen Dienstanforderung hochladen kann (z. B. ein Wiederholungsversuch, der durch eine HTTP 500-Antwort verursacht wurde).

Details zum Problem

Clientbibliothek Betroffener Versionen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Storage-Blob 12.0 bis 12.6.1 12.7.0 Update auf die neueste Version oder mindestens 12.22.1
Azure File Data Lake 12.0 bis 12.1.2 12.2.0 Update auf die neueste Version oder mindestens 12.8.0
Azure-Dateifreigabe 12.0 bis 12.4.1 12.5.0 Update auf die neueste Version oder mindestens 12.5.0
  1. Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.

Hinweis: Azure verfügt nicht über die Möglichkeit, falsch geschriebene Objekte wiederherzustellen. Da potenzielle Auswirkungen vor dem Upload auftreten, verfügt Azure nicht über eine gültige Kopie des betroffenen Objekts. Wenn Sie über die ursprüngliche Datei verfügen, kann sie erneut in Ihr Speicherkonto geladen werden.

Zurück zur Liste der bekannten Probleme

3. Upload fälschlicherweise als erfolgreich zurückgegeben, wenn IOException eintritt

Problembeschreibung

Alle Überladungen von void BlobClient.upload() und void BlobClient.uploadWithResponse() erfassen Fehlerantworten vom Speicherdienst im Hintergrund. Die Methode sollte entweder als Erfolgs-/Fehlerindikator zurückgeben oder auslösen. Die Ausnahme, die protokolliert und weitergegeben werden sollte, würde stattdessen direkt in den Standardfehler geschrieben und dann verschluckt, obwohl das Auslösen der einzige Fehlerindikator für die API ist. Die Methode gibt daher erfolgreich zurück, sodass der Aufrufer denkt, dass der Vorgang abgeschlossen ist. Dies führt dazu, dass das Blob nicht in den Speicher geschrieben wurde, obwohl die Bibliothek den Erfolg anzeigt.

Details zum Problem

Clientbibliothek Betroffener Versionen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Storage-Blob 12.0 bis 12.4.0 12.5.0 Update auf die neueste Version oder mindestens 12.22.1

Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.

Zurück zur Liste der bekannten Probleme

4. Falsche Daten, die mit heruntergeladen werden downloadToFile

Problembeschreibung

Asynchrones Schreiben von Puffern hat eine Racebedingung, bei der der Puffer zwischen dem Netzwerkdatenstrom und dem Dateidatenstrom für eingehende Daten wiederverwendet werden kann, bevor er in die Datei geleert wird. Dies führt dazu, dass die heruntergeladene Datei beschädigt wird, wobei einige Daten sofort wiederholt werden, wodurch die gültigen Daten an ihrer Stelle überschrieben werden. Das Objekt in Storage ist weiterhin korrekt.

Details zum Problem

Clientbibliothek Betroffener Versionen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Storage-Blob 12.0 bis 12.2.0 12.3.0 Update auf die neueste Version oder mindestens 12.22.1

Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.

Zurück zur Liste der bekannten Probleme

5. Parameter überschreiben beim Hochladen großer Dateien nicht berücksichtigt, was zu einem falschen Überschreiben führt

Problembeschreibung

Das Überschreibungsflag wird in Fällen, in denen ein weiterer paralleler Uploadauftrag ausgeführt wird, nicht berücksichtigt. Dies führt dazu, dass ein Objekt in Storage nicht überschrieben wird, wenn dies beabsichtigt ist.

Details zum Problem

Clientbibliothek Betroffener Versionen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Storage-Blob 12.0 12.1.0 Update auf die neueste Version oder mindestens 12.22.1

Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.

Zurück zur Liste der bekannten Probleme

6. Überschreibungsvorgang wird für den Überschreibungsparameter umgekehrt, was zu einem falschen Überschreiben führt

Problembeschreibung

Der Überschreibungsparameter und der Überschreibungsvorgang werden in DataLakeFileClient.flush(long) -Funktionen und DataLakeFileClient.flush(long, bool) umgekehrt. Keine anderen Verhaltensweisen der Bibliothek rufen diese Methoden auf. Dies führt dazu, dass ein Objekt in Storage überschrieben wird, wenn der Benutzer dies nicht beabsichtigte, und es kann nicht bei Bedarf überschrieben werden.

Details zum Problem

Clientbibliothek Versionen betroffen Mindestsicherheitsversion Empfohlene Maßnahme
Azure File Data Lake 12.0 bis 12.7.0 12.8.0 Aktualisieren auf die neueste Version oder mindestens 12.8.0

Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.

Zurück zur Liste der bekannten Probleme

7. Nachrichteninhalte werden fälschlicherweise gelöscht, wenn nur das Sichtbarkeitstimeout festgelegt ist

Problembeschreibung

Der Inhalt von Warteschlangennachrichten wird fehlerhaft gelöscht, wenn nur das Sichtbarkeitstimeout festgelegt oder aktualisiert wurde.

Details zum Problem

Clientbibliothek Versionen betroffen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Storage-Warteschlange 12.0 bis 12.6.0 12.7.0 Aktualisieren auf die neueste Version oder mindestens 12.7.0

Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.

Zurück zur Liste der bekannten Probleme

8. Clientseitige Verschlüsselung für die Verwendung von AES-GCM aufgrund von Sicherheitsrisiken im CBC-Modus aktualisiert

Problembeschreibung

Um ein Sicherheitsrisiko zu beheben, das im CBC-Modus gefunden wurde, hat das Java v12 SDK eine neue Version der clientseitigen Verschlüsselung namens v2 veröffentlicht, die AES-GCM für die clientseitige Verschlüsselung anstelle des CBC-Modus verwendet. Die aktualisierten SDKs sind abwärtskompatibel und bieten Ihnen die Möglichkeit, mit der v1-Version verschlüsselte Daten zu lesen und zu schreiben. Ausführliche Informationen finden Sie unter Aktualisieren der clientseitigen Verschlüsselung von Azure Storage im SDK, um sicherheitsrelevante Sicherheitsrisiken zu beheben. In Abschnitt 2 des Blogbeitrags werden Schritte beschrieben, die Sie ausführen müssen, um festzustellen, ob sich dieses Problem auf Sie auswirkt.

Details zum Problem

Clientbibliothek Versionen betroffen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Blob Storage Kryptografie 12.0 bis 12.16.1 12.17.0 Update auf die aktuelle Version

Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle. Lesen Sie die clientseitige Verschlüsselung von Azure Storage im SDK, um eine Sicherheitslücke zu beheben, um eine empfohlene Aktion zu finden.

Zurück zur Liste der bekannten Probleme

9. Falsche Daten, die mit downloadToFile() heruntergeladen werden, wenn zugrunde liegende REST-Anforderungen wiederholt werden

Problembeschreibung

Die Azure SDK für Java Storage-Bibliothek weist einen Fehler auf, bei dem falsche Daten mit der downloadToFile() -Methode in eine Datei geschrieben werden konnten, wenn bei einigen der zugrunde liegenden Storage-REST-Anforderungen während der Zeit ein Netzwerkfehler aufgetreten ist. Dieser Fehler wurde ursprünglich im Sommer 2022 eingeführt und wurde im Mai 2023 gepatcht , indem zum vorherigen Verhalten zurückzukehren. Die betroffenen Versionen sind 12.19.0 bis 12.22.0. Der Patch befindet sich in Version 12.22.1.

Details zum Problem

Clientbibliothek Versionen betroffen Mindestsicherheitsversion Empfohlene Maßnahme
Azure Storage-Blob 12.19.0 bis 12.22.0 12.22.1 Update auf die neueste Version oder mindestens 12.22.1

Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.

Zurück zur Liste der bekannten Probleme

10. InvalidHeaderValue-Fehlermeldung bei Verwendung der Betaversion des SDK

In seltenen Szenarien können Anwendungen, die ein Upgrade auf die neueste Betaversion oder allgemein verfügbare Version des SDK durchgeführt haben, eine InvalidHeaderValue Fehlermeldung erhalten. Dieses Problem kann auftreten, wenn eine der Speicherbibliotheken verwendet wird. Die Fehlermeldung ähnelt dem folgenden Beispiel:

HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
 
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>

Wenn Sie ein Upgrade auf die neueste Betaversion oder die allgemein verfügbare Version des SDK durchgeführt haben und dieser Fehler auftritt, wird empfohlen, ein Downgrade auf die vorherige allgemein verfügbare Version des SDK durchzuführen, um festzustellen, ob das Problem behoben ist. Wenn das Problem weiterhin besteht oder die Empfehlung nicht möglich ist, öffnen Sie ein Supportticket , um weitere Optionen zu erkunden.

Zurück zur Liste der bekannten Probleme