Azure File Data Lake-Clientbibliothek für Java– Version 12.17.1

  • Artikel

Azure Data Lake Storage ist die optimierte Speicherlösung von Microsoft für Big Data-Analyseworkloads. Ein wesentlicher Bestandteil von Data Lake Storage Gen2 ist das Hinzufügen eines hierarchischen Namespace zum Blobspeicher. Der hierarchische Namespace organisiert Objekte/Dateien in einer Hierarchie von Verzeichnissen für den effizienten Datenzugriff.

Quellcode | API-Referenzdokumentation | REST-API-Dokumentation | Produktdokumentation | Proben

Erste Schritte

Voraussetzungen

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie azure-sdk-bom in Ihr Projekt ein, um von der GA-Version der Bibliothek abhängig zu sein. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur BOM finden Sie in der INFODATEI FÜR AZURE SDK-STÜCKLISTEN.

<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-file-datalake</artifactId>
  </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Wenn Sie eine Abhängigkeit von einer bestimmten Version der Bibliothek annehmen möchten, die nicht in der BoM vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
    <version>12.17.1</version>
</dependency>

Erstellen eines Speicherkontos

Zum Erstellen eines Speicherkontos können Sie das Azure-Portal oder die Azure CLI verwenden. Hinweis: Um Data Lake verwenden zu können, muss für Ihr Konto der hierarchische Namespace aktiviert sein.

# Install the extension “Storage-Preview”
az extension add --name storage-preview
# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

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

Authentifizieren des Clients

Um mit dem Speicherdienst 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 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 gemeinsam genutzte Schlüssel

a. Verwenden Sie Kontoname und Kontoschlüssel. Kontoname ist Ihr Speicherkontoname.

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

oder

b. Verwenden Sie die Verbindungszeichenfolge.

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

Wichtige Begriffe

DataLake Storage Gen2 wurde für Folgendes konzipiert:

  • Verarbeiten von Informationen mit mehreren Petabytes bei gleichzeitiger Beibehaltung von Hunderten von Gigabit Durchsatz
  • Einfaches Verwalten großer Datenmengen

Zu den wichtigsten Features von DataLake Storage Gen2 gehören:

  • Hadoop-kompatibler Zugriff
  • Eine Obermenge von POSIX-Berechtigungen
  • Kosteneffizient in Bezug auf kostengünstige Speicherkapazität und Transaktionen
  • Optimierter Treiber für Big Data-Analysen

Ein wesentlicher Bestandteil von Data Lake Storage Gen2 ist das Hinzufügen eines hierarchischen Namespace zum Blobspeicher. Der hierarchische Namespace organisiert Objekte/Dateien in einer Hierarchie von Verzeichnissen für den effizienten Datenzugriff.

In der Vergangenheit mussten bei cloudbasierten Analysen Kompromisse in puncto Leistung, Verwaltung und Sicherheit eingegangen werden. Data Lake Storage Gen2 geht jeden dieser Aspekte auf folgende Weise an:

  • Die Leistung ist optimiert, da Sie keine Daten als Voraussetzung für die Analyse kopieren oder transformieren müssen. Der hierarchische Namespace verbessert die Leistung von Verzeichnisverwaltungsvorgängen erheblich, wodurch die gesamte Auftragsverarbeitungsleistung gesteigert wird.
  • Die Verwaltung ist einfacher, weil Sie Dateien mithilfe von Verzeichnissen und Unterverzeichnissen organisieren und bearbeiten können.
  • Die Sicherheit ist durchsetzbar, da Sie POSIX-Berechtigungen für Verzeichnisse oder einzelne Dateien definieren können.
  • Kosteneffizienz wird ermöglicht, da Data Lake Storage Gen2 auf kostengünstigem Azure Blob Storage aufsetzt. Durch diese zusätzlichen Features werden die Gesamtbetriebskosten für Big Data-Analysen in Azure weiter gesenkt.

Data Lake Storage Gen2 bietet zwei Arten von Ressourcen:

  • Das _filesystem über "DataLakeFileSystemClient" verwendete
  • Die _path über "DataLakeFileClient" oder "DataLakeDirectoryClient" verwendete
ADLS Gen2 Blob
Dateisystem Container
Pfad (Datei oder Verzeichnis) Blob

Hinweis: Diese Clientbibliothek unterstützt keine deaktivierten Speicherkonten für den hierarchischen Namespace (HNS).

URL-Format

Pfade können im folgenden URL-Format adressierbar sein: Die folgende URL adressieren eine Datei:

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${myfile}

Syntax von Ressourcen-URIs

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

https://${myaccount}.dfs.core.windows.net

Für ein Dateisystem enthält der Basis-URI den Namen des Kontos und den Namen des Dateisystems:

https://${myaccount}.dfs.core.windows.net/${myfilesystem}

Für eine Datei/ein Verzeichnis enthält der Basis-URI den Namen des Kontos, den Namen des Dateisystems und den Namen des Pfads:

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${mypath}

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 häufigsten Azure Storage-Blobtasks abdecken, einschließlich:

Erstellen der Datei DataLakeServiceClient

Erstellen Sie eine DataLakeServiceClient mithilfe der sasToken oben generierten.

DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

oder

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

Erstellen der Datei DataLakeFileSystemClient

Erstellen Sie mithilfe von DataLakeFileSystemClient .DataLakeServiceClient

DataLakeFileSystemClient dataLakeFileSystemClient = dataLakeServiceClient.getFileSystemClient("myfilesystem");

oder

Erstellen Sie einen DataLakeFileSystemClient aus dem oben generierten Generator sasToken .

DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .buildClient();

oder

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "?" + "<your-sasToken>")
    .buildClient();

Erstellen der Datei DataLakeFileClient

Erstellen Sie mithilfe von DataLakeFileClient .DataLakeFileSystemClient

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");

oder

Erstellen Sie einen FileClient aus dem oben generierten Generator sasToken .

DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("myfile")
    .buildFileClient();

oder

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "myfile" + "?" + "<your-sasToken>")
    .buildFileClient();

Erstellen der Datei DataLakeDirectoryClient

Abrufen eines DataLakeDirectoryClient mithilfe von DataLakeFileSystemClient.

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");

oder

Erstellen Sie einen DirectoryClient aus dem oben generierten Generator sasToken .

DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("mydir")
    .buildDirectoryClient();

oder

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "mydir" + "?" + "<your-sasToken>")
    .buildDirectoryClient();

Erstellen eines Dateisystems

Erstellen Sie ein Dateisystem mithilfe von DataLakeServiceClient.

dataLakeServiceClient.createFileSystem("myfilesystem");

oder

Erstellen Sie ein Dateisystem mithilfe von DataLakeFileSystemClient.

dataLakeFileSystemClient.create();

Auflisten von Pfaden

Auflisten aller Pfade mithilfe von DataLakeFileSystemClient.

for (PathItem pathItem : dataLakeFileSystemClient.listPaths()) {
    System.out.println("This is the path name: " + pathItem.getName());
}

Umbenennen einer Datei

Benennen Sie eine Datei mithilfe von um DataLakeFileClient.

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
fileClient.rename("new-file-system-name", "new-file-name");

Umbenennen eines Verzeichnisses

Benennen Sie ein Verzeichnis mithilfe von um DataLakeDirectoryClient.

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
directoryClient.rename("new-file-system-name", "new-directory-name");

Abrufen von Dateieigenschaften

Abrufen von Eigenschaften aus einer Datei mithilfe von DataLakeFileClient.

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
PathProperties properties = fileClient.getProperties();

Verzeichniseigenschaften abrufen

Abrufen von Eigenschaften aus einem Verzeichnis mithilfe von DataLakeDirectoryClient.

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
PathProperties properties = directoryClient.getProperties();

Authentifizieren mit einer Azure-Identität

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

DataLakeServiceClient storageClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Problembehandlung

Bei der Interaktion mit Data Lake mithilfe dieser Java-Clientbibliothek entsprechen vom Dienst zurückgegebene Fehler den gleichen HTTP-status-Codes, die für REST-API-Anforderungen zurückgegeben werden. Wenn Sie beispielsweise versuchen, ein Dateisystem oder einen Pfad abzurufen, der nicht in Ihrem Speicherkonto vorhanden ist, wird ein 404 Fehler zurückgegeben, der Not Foundangibt.

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 des SDK stehen Mehrere Beispiele für Storage Datalake Java SDK zur Verfügung.

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