Azure Storage-Bibliotheken für Java
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
- Pufferüberschreibungsproblem mit
BlobOutputStream - Ungültige Daten, die während Wiederholungsversuchen hochgeladen wurden
- Upload fälschlicherweise als erfolgreich zurückgegeben, wenn
IOExceptioneintritt - Falsche Daten, die mit heruntergeladen werden
downloadToFile - Parameter überschreiben beim Hochladen großer Dateien nicht berücksichtigt, was zu einem falschen Überschreiben führt
- Overwrite-Vorgang für den Überschreibungsparameter umgekehrt, was zu einem falschen Überschreiben führt
- Der Nachrichteninhalt wurde fälschlicherweise gelöscht, wenn nur ein Timeout für die Sichtbarkeit festgelegt ist
- Clientseitige Verschlüsselung aktualisiert, um AES-GCM aufgrund von Sicherheitsrisiken im CBC-Modus zu verwenden
- Falsche Daten, die mit downloadToFile() heruntergeladen werden, wenn zugrunde liegende REST-Anforderungen wiederholt werden
- 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 |
Empfohlene Schritte
- Aktualisieren Sie die Clientbibliotheksversionen gemäß der obigen Tabelle.
- Ü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:
- Überprüfen Sie, ob Ihre Anwendung verwendet,
BlobOutputStreamum Blobs hochzuladen (abgerufen überBlockBlobClient.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. - Rufen Sie den
MaxSingleUploadSizeWert für Ihre Anwendung ab (standardmäßig 256 MiB). Überprüfen Sie Ihren Code aufsetMaxSingleUploadSizeLong()die Methode derParallelTransferOptions-Klasse, und rufen Sie den Wert ab, den Sie für diese Eigenschaft angegeben haben. - Identifizieren sie das Zeitfenster, in dem Ihre Anwendung die Clientbibliotheksversion mit diesem Problem verwendet hat (12.0 bis 12.10.0).
- Identifizieren Sie alle blobs, die in diesem Zeitfenster hochgeladen wurden. Sie können eine Liste der Blobs abrufen, indem Sie den
List BlobsVorgang 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 |
Empfohlene Schritte
- 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 |
Empfohlene Schritte
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 |
Empfohlene Schritte
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 |
Empfohlene Schritte
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 |
Empfohlene Schritte
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 |
Empfohlene Schritte
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 |
Empfohlene Schritte
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 |
Empfohlene Schritte
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.
Azure SDK for Java
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für