Biblioteka klienta udziału plików usługi Azure Storage dla języka JavaScript

Artykuł
11/20/2024

Usługa Azure Files oferuje w pełni zarządzane udziały plików w chmurze, które są dostępne za pośrednictwem standardowego protokołu SMB (Industry Standard Server Message Block). Udziały plików platformy Azure można instalować współbieżnie za pomocą wdrożeń w chmurze lub lokalnych systemów Windows, Linux i macOS. Ponadto udziały plików platformy Azure można buforować na serwerach z systemem Windows za pomocą usługi Azure File Sync w celu uzyskania szybkiego dostępu w pobliżu miejsca, w którym są używane dane.

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

Użyj bibliotek klienckich w tym pakiecie, aby:

Pobieranie/ustawianie właściwości usługi plików
Tworzenie/wyświetlanie/usuwanie udziałów plików
Tworzenie/wyświetlanie/usuwanie katalogów plików
Tworzenie/odczytywanie/lista/aktualizowanie/usuwanie plików

Uwaga: ten pakiet został wcześniej opublikowany pod nazwą @azure/storage-file. Zmieniono jej nazwę na @azure/storage-file-share w celu lepszego dopasowania do nadchodzącego nowego pakietu usługi Azure Storage Files DataLake i zapewnienia spójnego zestawu interfejsów API do pracy z plikami na platformie Azure.

Kluczowe linki:

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

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 File Storage 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-share

Uwierzytelnianie klienta

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

klucza współużytkowanego
sygnatury dostępu współdzielonego

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:

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.

Następujące funkcje, interfejsy, klasy lub funkcje są 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()
- generateFileSASQueryParameters()
Równoległe przekazywanie i pobieranie. Należy pamiętać, że ShareFileClient.uploadData() jest dostępna zarówno w Node.js, jak i w przeglądarkach.
- ShareFileClient.uploadFile()
- ShareFileClient.uploadStream()
- ShareFileClient.downloadToBuffer()
- ShareFileClient.downloadToFile()

Następujące funkcje, interfejsy, klasy lub funkcje są 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

Kluczowe pojęcia

Następujące składniki i odpowiadające im biblioteki klienckie składają się na usługę udziału plików usługi Azure Storage:

Samo konto magazynu reprezentowane przez ShareServiceClient
Udział plików na koncie magazynu reprezentowany przez ShareClient
Opcjonalna hierarchia katalogów w udziale plików reprezentowana przez wystąpienia ShareDirectoryClient
Plik w udziale plików, który może mieć rozmiar do 1 TiB reprezentowany przez ShareFileClient

Przykłady

Importowanie pakietu
Tworzenie klienta usługi udostępniania
listy udziałów na koncie
Tworzenie nowego udziału i katalogu
Utwórz plik platformy Azure, a następnie przekaż go
Wyświetlanie listy plików i katalogów w katalogu
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 AzureStorageFileShare = require("@azure/storage-file-share");

Alternatywnie selektywnie zaimportuj tylko potrzebne typy:

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

ShareServiceClient wymaga adresu URL usługi udziału plików i poświadczenia dostępu. Opcjonalnie akceptuje również niektóre ustawienia w parametrze options.

używanie parametrów połączenia

Alternatywnie można utworzyć wystąpienie ShareServiceClient przy użyciu metody statycznej fromConnectionString() z pełnymi parametrami połączenia jako argumentem. (Parametry połączenia można uzyskać w witrynie Azure Portal).

const { ShareServiceClient } = require("@azure/storage-file-share");

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

z `StorageSharedKeyCredential`

Przekaż StorageSharedKeyCredential przy użyciu nazwy konta i klucza konta. (Nazwę konta i klucz konta można uzyskać w witrynie Azure Portal).

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

// 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 credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  // When using AnonymousCredential, following url should include a valid SAS
  `https://${account}.file.core.windows.net`,
  credential
);

z tokenem SAS

Ponadto można utworzyć wystąpienie ShareServiceClient 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 { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new ShareServiceClient(
  `https://${account}.file.core.windows.net${sas}`
);

Wyświetlanie listy udziałów na koncie

Użyj ShareServiceClient.listShares() do iteratora udziałów na tym koncie z nową składnią for-await-of:

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareIter = serviceClient.listShares();
  let i = 1;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

Alternatywnie bez for-await-of:

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareIter = serviceClient.listShares();
  let i = 1;
  let shareItem = await shareIter.next();
  while (!shareItem.done) {
    console.log(`Share ${i++}: ${shareItem.value.name}`);
    shareItem = await shareIter.next();
  }
}

main();

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareName = `newshare${new Date().getTime()}`;
  const shareClient = serviceClient.getShareClient(shareName);
  await shareClient.create();
  console.log(`Create share ${shareName} successfully`);

  const directoryName = `newdirectory${new Date().getTime()}`;
  const directoryClient = shareClient.getDirectoryClient(directoryName);
  await directoryClient.create();
  console.log(`Create directory ${directoryName} successfully`);
}

main();

Utwórz plik platformy Azure, a następnie przekaż do niego

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const content = "Hello World!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = directoryClient.getFileClient(fileName);
  await fileClient.create(content.length);
  console.log(`Create file ${fileName} successfully`);

  // Upload file range
  await fileClient.uploadRange(content, 0, content.length);
  console.log(`Upload file range "${content}" to ${fileName} successfully`);
}

main();

Wyświetlanie listy plików i katalogów w katalogu

Użyj DirectoryClient.listFilesAndDirectories(), aby iterować pliki i katalogi z nową składnią for-await-of. Właściwość kind może służyć do określenia, czy element iterm jest katalogiem, czy plikiem.

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  for await (const item of dirIter) {
    if (item.kind === "directory") {
      console.log(`${i} - directory\t: ${item.name}`);
    } else {
      console.log(`${i} - file\t: ${item.name}`);
    }
    i++;
  }
}

main();

Alternatywnie bez użycia for-await-of:

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  let item = await dirIter.next();
  while (!item.done) {
    if (item.value.kind === "directory") {
      console.log(`${i} - directory\t: ${item.value.name}`);
    } else {
      console.log(`${i} - file\t: ${item.value.name}`);
    }
    i++;
    item = await dirIter.next();
  }
}

main();

Aby uzyskać kompletny przykład dotyczący iteracji, zobacz samples/v12/typescript/src/listFilesAndDirectories.ts.

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

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const fileName = "<file name>";

// [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);
  });
}

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadFileResponse.readableStreamBody
  const downloadFileResponse = await fileClient.download();
  console.log(
    `Downloaded file content: ${(
      await streamToBuffer(downloadFileResponse.readableStreamBody)
    ).toString()}`
  );
}

main();

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

Aby uzyskać więcej informacji na temat korzystania z tej biblioteki w przeglądarce, zapoznaj się z sekcją pakietu JavaScript.

const { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const shareName = "<share name>";
const fileName = "<file name>";

const serviceClient = new ShareServiceClient(`https://${account}.file.core.windows.net${sas}`);

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadFileResponse.blobBody
  const downloadFileResponse = await fileClient.download(0);
  console.log(
    `Downloaded file content: ${await blobToString(await downloadFileResponse.blobBody)}`
  );
}

// [Browser 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();

Kompletny przykład prostych scenariuszy ShareServiceClient znajduje się w samples/v12/typescript/src/shareSerivceClient.ts.

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

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.

Zapoznaj się również z przewodnikiem Storage, aby uzyskać dodatkowe informacje na temat konfigurowania środowiska testowego dla bibliotek magazynu.

Udostępnij za pośrednictwem

Wprowadzenie

Obecnie obsługiwane środowiska

Warunki wstępne

Instalowanie pakietu

Uwierzytelnianie klienta

Zgodność

Procesy robocze sieci Web

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

Następujące funkcje, interfejsy, klasy lub funkcje są dostępne tylko w Node.js

Następujące funkcje, interfejsy, klasy lub funkcje są dostępne tylko w przeglądarkach

Pakiet JavaScript

MECHANIZM CORS

Kluczowe pojęcia

Przykłady

Importowanie pakietu

używanie parametrów połączenia

z `StorageSharedKeyCredential`

z tokenem SAS

Wyświetlanie listy udziałów na koncie

Utwórz plik platformy Azure, a następnie przekaż do niego

Wyświetlanie listy plików i katalogów w katalogu

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

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

Rozwiązywanie problemów

Następne kroki

Przyczyniając się

Dodatkowe zasoby

Udostępnij za pośrednictwem

Biblioteka klienta udziału plików usługi Azure Storage dla języka JavaScript — wersja 12.26.0

Wprowadzenie

Obecnie obsługiwane środowiska

Warunki wstępne

Instalowanie pakietu

Uwierzytelnianie klienta

Zgodność

Procesy robocze sieci Web

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

Następujące funkcje, interfejsy, klasy lub funkcje są dostępne tylko w Node.js

Następujące funkcje, interfejsy, klasy lub funkcje są dostępne tylko w przeglądarkach

Pakiet JavaScript

MECHANIZM CORS

Kluczowe pojęcia

Przykłady

Importowanie pakietu

Tworzenie klienta usługi udostępniania

używanie parametrów połączenia

z StorageSharedKeyCredential

z tokenem SAS

Wyświetlanie listy udziałów na koncie

Tworzenie nowego udziału i katalogu

Utwórz plik platformy Azure, a następnie przekaż do niego

Wyświetlanie listy plików i katalogów w katalogu

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

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

Rozwiązywanie problemów

Następne kroki

Przyczyniając się

Dodatkowe zasoby

z `StorageSharedKeyCredential`