Biblioteka klienta usługi Azure Storage File Lake dla języka JavaScript — wersja 12.25.0

Usługa Azure Data Lake Storage (ADLS) obejmuje wszystkie funkcje wymagane do ułatwienia deweloperom, analitykom danych i analitykom przechowywania danych o dowolnym rozmiarze, kształcie i szybkości oraz we wszystkich typach przetwarzania i analizy na różnych platformach i językach. Eliminuje on złożoność pozyskiwania i przechowywania wszystkich danych, jednocześnie przyspieszając pracę z usługą batch, przesyłaniem strumieniowym i interakcyjnymi analizami.

Ten projekt udostępnia bibliotekę klienta w języku JavaScript, która ułatwia korzystanie z usługi Microsoft Azure Storage Data Lake.

Użyj bibliotek klienckich w tym pakiecie, aby:

• Tworzenie/wyświetlanie/usuwanie systemów plików
• Tworzenie/odczytywanie/wyświetlanie/aktualizowanie/usuwanie ścieżek, katalogów i plików

linki kluczowe:

• Kod źródłowy
• pakiet (npm)
• Dokumentacja referencyjna interfejsu API
• dokumentacja produktu
• Samples
• interfejsów API REST usługi Azure Storage Data Lake

Wprowadzenie

Obecnie obsługiwane środowiska

• wersje Node.js LTS
• Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

Aby uzyskać więcej informacji, zobacz nasze zasad pomocy technicznej.

Warunki wstępne

• subskrypcji platformy Azure
• Konto magazynu

Instalowanie pakietu

Preferowanym sposobem zainstalowania biblioteki klienta usługi Azure Storage Data Lake dla języka JavaScript jest użycie menedżera pakietów npm. Wpisz następujące polecenie w oknie terminalu:

npm install @azure/storage-file-datalake

Uwierzytelnianie klienta

Usługa Azure Storage obsługuje kilka sposobów uwierzytelniania. Aby móc korzystać z usługi Azure Data Lake Storage, należy utworzyć na przykład wystąpienie klienta usługi Storage — DataLakeServiceClient, DataLakeFileSystemClientlub DataLakePathClient. Zobacz przykłady tworzenia DataLakeServiceClient, aby dowiedzieć się więcej na temat uwierzytelniania.

• usługi Azure Active Directory
• klucza współużytkowanego
• sygnatury dostępu współdzielonego

Azure Active Directory

Usługa Azure Data Lake Storage obsługuje używanie usługi Azure Active Directory do uwierzytelniania żądań w swoich interfejsach API. Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. Aby uzyskać więcej szczegółów i przykładów, zobacz README dla @azure/identity.

Zgodność

Ta biblioteka jest zgodna z Node.js i przeglądarkami oraz jest weryfikowana w wersjach Node.js LTS (>=8.16.0) i najnowszych wersjach przeglądarki Chrome, Firefox i Edge.

Procesy robocze sieci Web

Ta biblioteka wymaga, aby niektóre obiekty DOM były globalnie dostępne w przypadku użycia w przeglądarce, które procesy robocze sieci Web nie są domyślnie dostępne. Aby ta biblioteka działała w procesach roboczych sieci Web, należy je polifill.

Aby uzyskać więcej informacji, zapoznaj się z naszą dokumentacją dotyczącą korzystania z zestawu Azure SDK for JS w Web Workers

Ta biblioteka zależy od następujących interfejsów API DOM, które wymagają zewnętrznych polifilli załadowanych podczas korzystania z procesów roboczych sieci Web:

• document
• DOMParser
• Node
• XMLSerializer

Różnice między Node.js a przeglądarkami

Istnieją różnice między środowiskiem uruchomieniowym Node.js a przeglądarkami. Podczas rozpoczynania pracy z tą biblioteką należy zwrócić uwagę na interfejsy API lub klasy oznaczone "TYLKO DOSTĘPNE W środowisku uruchomieniowym NODE.JS" lub "TYLKO DOSTĘPNE W PRZEGLĄDARKACH".

• Jeśli plik przechowuje skompresowane dane w formacie gzip lub deflate, a jego kodowanie zawartości jest odpowiednio ustawione, zachowanie pobierania różni się między Node.js a przeglądarkami. W Node.js klienci magazynu będą pobierać plik w formacie skompresowanym, podczas gdy w przeglądarkach dane zostaną pobrane w formacie de skompresowanym.

Funkcje, interfejsy, klasy lub funkcje dostępne tylko w Node.js

• Autoryzacja klucza współużytkowanego na podstawie nazwy konta i klucza konta
  • StorageSharedKeyCredential
• Generowanie sygnatury dostępu współdzielonego (SAS)
  • generateAccountSASQueryParameters()
  • generateDataLakeSASQueryParameters()
• Równoległe przekazywanie i pobieranie. Należy pamiętać, że DataLakeFileClient.upload() jest dostępna zarówno w Node.js, jak i w przeglądarkach.
  • DataLakeFileClient.uploadFile()
  • DataLakeFileClient.uploadStream()
  • DataLakeFileClient.readToBuffer()
  • DataLakeFileClient.readToFile()

Funkcje, interfejsy, klasy lub funkcje dostępne tylko w przeglądarkach

• N/A

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć pakietu. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów .

MECHANIZM CORS

Musisz skonfigurować współużytkowanie zasobów między źródłami (CORS) regułami dla konta magazynu, jeśli chcesz utworzyć aplikacje dla przeglądarek. Przejdź do witryny Azure Portal i Eksploratora usługi Azure Storage, znajdź konto magazynu, utwórz nowe reguły CORS dla usług blob/queue/file/table.

Można na przykład utworzyć następujące ustawienia mechanizmu CORS na potrzeby debugowania. Należy jednak dokładnie dostosować ustawienia zgodnie z wymaganiami w środowisku produkcyjnym.

• Dozwolone źródła: *
• Dozwolone czasowniki: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Dozwolone nagłówki: *
• Uwidocznione nagłówki: *
• Maksymalny wiek (w sekundach): 86400

Uwaga: usługa Data Lake obecnie udostępnia ustawienia mechanizmu CORS dla usługi blob.

Kluczowe pojęcia

Usługa Azure Data Lake Storage Gen2 została zaprojektowana w celu:

• Obsługa wielu petabajtów informacji przy zachowaniu setek gigabitów przepływności
• Umożliwia łatwe zarządzanie ogromnymi ilościami danych

Najważniejsze funkcje usługi DataLake Storage Gen2 obejmują:

• Dostęp zgodny z usługą Hadoop
• Super zestaw uprawnień POSIX
• Opłacalne pod względem pojemności i transakcji magazynu o niskich kosztach
• Zoptymalizowany sterownik do analizy danych big data

Podstawową częścią usługi Data Lake Storage Gen2 jest dodanie hierarchicznej przestrzeni nazw do magazynu obiektów blob. Hierarchiczna przestrzeń nazw organizuje obiekty/pliki w hierarchię katalogów w celu zapewnienia efektywnego dostępu do danych.

W przeszłości analiza oparta na chmurze musiała naruszyć bezpieczeństwo w obszarach wydajności, zarządzania i zabezpieczeń. Usługa Data Lake Storage Gen2 rozwiązuje każde z tych aspektów w następujący sposób:

• Wydajność jest zoptymalizowana, ponieważ nie trzeba kopiować ani przekształcać danych jako wymagań wstępnych do analizy. Hierarchiczna przestrzeń nazw znacznie poprawia wydajność operacji zarządzania katalogami, co zwiększa ogólną wydajność zadań.
• Zarządzanie jest łatwiejsze, ponieważ można organizować i manipulować plikami za pomocą katalogów i podkatalogów.
• Zabezpieczenia można wymusić, ponieważ można zdefiniować uprawnienia POSIX w katalogach lub pojedynczych plikach.
• Efektywność kosztów jest możliwa, ponieważ usługa Data Lake Storage Gen2 jest oparta na taniej usłudze Azure Blob Storage. Dodatkowe funkcje jeszcze bardziej obniżają całkowity koszt posiadania na potrzeby uruchamiania analizy danych big data na platformie Azure.

Usługa Data Lake Storage oferuje trzy typy zasobów:

• Konto magazynu używane za pośrednictwem DataLakeServiceClient
• System plików na koncie magazynu używanym za pośrednictwem DataLakeFileSystemClient
• Ścieżka w systemie plików używanym za pośrednictwem DataLakeDirectoryClient lub DataLakeFileClient

Azure DataLake Gen2	Blob
System plików	Kontener
Ścieżka (plik lub katalog)	Blob

Uwaga: ta biblioteka klienta obsługuje tylko konta magazynu z włączoną hierarchiczną przestrzenią nazw (HNS).

Przykłady

• Importowanie pakietu
• Tworzenie klienta usługi Data Lake
• Tworzenie nowego systemu plików
• Lista systemów plików
• Tworzenie i usuwanie katalogu
• Tworzenie pliku
• ścieżki listy wewnątrz systemu plików
• Pobierz plik i przekonwertuj go na ciąg (Node.js)
• Pobierz plik i przekonwertuj go na ciąg (przeglądarki)

Importowanie pakietu

Aby użyć klientów, zaimportuj pakiet do pliku:

const AzureStorageDataLake = require("@azure/storage-file-datalake");

Alternatywnie selektywnie zaimportuj tylko potrzebne typy:

const {
  DataLakeServiceClient,
  StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");

Tworzenie klienta usługi Data Lake

DataLakeServiceClient wymaga adresu URL usługi Data Lake i poświadczenia dostępu. Opcjonalnie akceptuje również niektóre ustawienia w parametrze options.

z DefaultAzureCredential z pakietu @azure/identity

Zalecany sposób tworzenia wystąpienia DataLakeServiceClient

Zauważyć. Usługa Azure Data Lake obecnie ponownie używa ról powiązanych z obiektami blob, takich jak "Właściciel danych obiektu blob usługi Storage" podczas uwierzytelniania za pomocą protokołu OAuth usługi AAD.

Konfiguracja: Dokumentacja — autoryzowanie dostępu do obiektów blob (data lake) i kolejek za pomocą usługi Azure Active Directory z poziomu aplikacji klienckiej — /azure/storage/common/storage-auth-aad-app

• Zarejestruj nową aplikację usługi AAD i przyznaj uprawnienia dostępu do usługi Azure Storage w imieniu zalogowanego użytkownika.

  • Rejestrowanie nowej aplikacji w usłudze Azure Active Directory (w witrynie Azure-Portal) — /azure/active-directory/develop/quickstart-register-app
  • W sekcji API permissions wybierz pozycję Add a permission i wybierz pozycję Microsoft APIs.
  • Wybierz Azure Storage i zaznacz pole wyboru obok user_impersonation, a następnie kliknij przycisk Add permissions. Umożliwiłoby to aplikacji dostęp do usługi Azure Storage w imieniu zalogowanego użytkownika.

• Udzielanie dostępu do danych usługi Azure Data Lake za pomocą kontroli dostępu opartej na rolach w witrynie Azure Portal

  • Role RBAC dla obiektów blob (data lake) i kolejek — /azure/storage/common/storage-auth-aad-rbac-portal.
  • W witrynie Azure Portal przejdź do konta magazynu i przypisz rolę współautora danych obiektu blob usługi Storage do zarejestrowanej aplikacji usługi AAD z karty Access control (IAM) (na pasku nawigacyjnym po lewej stronie konta magazynu w witrynie Azure-Portal).

• Konfiguracja środowiska dla przykładu

  • Na stronie przeglądu aplikacji usługi AAD zanotuj CLIENT ID i TENANT ID. Na karcie "Certyfikaty & Wpisy tajne" utwórz wpis tajny i zanotuj je.
  • Upewnij się, że masz AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET jako zmienne środowiskowe, aby pomyślnie wykonać przykład (może korzystać z pliku process.env).

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

Zobacz przykład Auth usługi Azure AD, aby zapoznać się z kompletnym przykładem użycia tej metody.

[Uwaga — powyższe kroki dotyczą tylko Node.js]

używanie parametrów połączenia

Alternatywnie można utworzyć wystąpienie DataLakeServiceClient przy użyciu metody statycznej fromConnectionString() z pełnymi parametrami połączenia jako argumentem. (Parametry połączenia można uzyskać w witrynie Azure Portal). [DOSTĘPNE TYLKO W ŚRODOWISKU URUCHOMIENIOWYM NODE.JS]

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

z StorageSharedKeyCredential

Alternatywnie utworzysz wystąpienie DataLakeServiceClient przy użyciu StorageSharedKeyCredential, przekazując argumenty account-name i account-key. (Nazwę konta i klucz konta można uzyskać w witrynie Azure Portal). [DOSTĘPNE TYLKO W ŚRODOWISKU URUCHOMIENIOWYM NODE.JS]

const {
  DataLakeServiceClient,
  StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  sharedKeyCredential
);

z tokenem SAS

Ponadto można utworzyć wystąpienie DataLakeServiceClient przy użyciu sygnatur dostępu współdzielonego (SAS). Token SAS można uzyskać z witryny Azure Portal lub wygenerować go przy użyciu generateAccountSASQueryParameters().

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const serviceClientWithSAS = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`
);

Tworzenie nowego systemu plików

Użyj DataLakeServiceClient.getFileSystemClient(), aby uzyskać wystąpienie klienta systemu plików, a następnie utworzyć nowy zasób systemu plików.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  // Create a file system
  const fileSystemName = `newfilesystem${new Date().getTime()}`;
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const createResponse = await fileSystemClient.create();
  console.log(`Create file system ${fileSystemName} successfully`, createResponse.requestId);
}

main();

Wyświetlanie listy systemów plików

Użyj funkcji DataLakeServiceClient.listFileSystems(), aby iterować systemy plików przy użyciu nowej składni for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  const fileSystems = datalakeServiceClient.listFileSystems();
  for await (const fileSystem of fileSystems) {
    console.log(`File system ${i++}: ${fileSystem.name}`);
  }
}

main();

Alternatywnie bez użycia for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  const iter = datalakeServiceClient.listFileSystems();
  let fileSystemItem = await iter.next();
  while (!fileSystemItem.done) {
    console.log(`File System ${i++}: ${fileSystemItem.value.name}`);
    fileSystemItem = await iter.next();
  }
}

main();

Ponadto stronicowanie jest obsługiwane również w przypadku wyświetlania listy za pośrednictwem byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  for await (const response of datalakeServiceClient
    .listFileSystems()
    .byPage({ maxPageSize: 20 })) {
    if (response.fileSystemItems) {
      for (const fileSystem of response.fileSystemItems) {
        console.log(`File System ${i++}: ${fileSystem.name}`);
      }
    }
  }
}

main();

Tworzenie i usuwanie katalogu

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const directoryClient = fileSystemClient.getDirectoryClient("directory");
  await directoryClient.create();
  await directoryClient.delete();
}

main();

Tworzenie pliku

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  const content = "Hello world!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = fileSystemClient.getFileClient(fileName);
  await fileClient.create();
  await fileClient.append(content, 0, content.length);
  await fileClient.flush(content.length);
  console.log(`Create and upload file ${fileName} successfully`);
}

main();

Wyświetlanie listy ścieżek w systemie plików

Podobnie jak w przypadku wyświetlania listy systemów plików.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  let i = 1;
  const paths = fileSystemClient.listPaths();
  for await (const path of paths) {
    console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
  }
}

main();

Pobierz plik i przekonwertuj go na ciąg (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const fileClient = fileSystemClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadResponse.readableStreamBody
  const downloadResponse = await fileClient.read();
  const downloaded = await streamToBuffer(downloadResponse.readableStreamBody);
  console.log("Downloaded file content:", downloaded.toString());

  // [Node.js only] A helper method used to read a Node.js readable stream into a Buffer.
  async function streamToBuffer(readableStream) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on("end", () => {
        resolve(Buffer.concat(chunks));
      });
      readableStream.on("error", reject);
    });
  }
}

main();

Pobieranie pliku i konwertowanie go na ciąg (przeglądarki)

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const sas = "<sas token>";

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`
);

const fileSystemName = "<file system name>";
const fileName = "<file name>"

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const fileClient = fileSystemClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadResponse.contentAsBlob
  const downloadResponse = await fileClient.read();
  const downloaded = await blobToString(await downloadResponse.contentAsBlob);
  console.log(
    "Downloaded file content",
    downloaded
  );

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Rozwiązywanie problemów

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Następne kroki

Więcej przykładów kodu:

• DataLake Storage Samples (JavaScript)
• DataLake Storage Samples (TypeScript)
• przypadki testowe magazynu DataLake

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.