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

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/wyświetlanie/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 zasady pomocy technicznej .

Prerequisites

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.

Klucz współdzielony
sygnatury dostępu współdzielonego

Compatibility

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 .

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

Najważniejsze 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 przezShareServiceClient
Udział plików na koncie magazynu, reprezentowany przezShareClient
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 przezShareFileClient

Examples

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:

import * as AzureStorageFileShare from "@azure/storage-file-share";

Alternatywnie selektywnie zaimportuj tylko potrzebne typy:

import { ShareServiceClient, StorageSharedKeyCredential } from "@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).

import { ShareServiceClient } from "@azure/storage-file-share";

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

z `StorageSharedKeyCredential`

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

import { StorageSharedKeyCredential, ShareServiceClient } from "@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().

import { ShareServiceClient } from "@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:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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,
);

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

Alternatywnie bez for-await-of:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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 shareIter = serviceClient.listShares();
let i = 1;
let { value, done } = await shareIter.next();
while (!done) {
  console.log(`Share ${i++}: ${value.name}`);
  ({ value, done } = await shareIter.next());
}

import { StorageSharedKeyCredential, ShareServiceClient } from "@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 = `newshare${+new Date()}`;
const shareClient = serviceClient.getShareClient(shareName);
await shareClient.create();
console.log(`Create share ${shareName} successfully`);

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

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

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

const content = "Hello World!";
const fileName = `newdirectory${+new Date()}`;
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`);

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.

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

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

Alternatywnie bez użycia for-await-of:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

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

Aby uzyskać pełną próbkę iteracji, zobacz samples/v12/typescript/src/listFilesAndDirectories.ts.

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

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
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();
if (downloadFileResponse.readableStreamBody) {
  const buffer = await streamToBuffer(downloadFileResponse.readableStreamBody);
  console.log(`Downloaded file content: ${buffer.toString()}`);
}

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

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

Zapoznaj się z sekcją JavaScript Bundle , aby uzyskać więcej informacji na temat korzystania z tej biblioteki w przeglądarce.

import { ShareServiceClient } from "@azure/storage-file-share";

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

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

const shareName = "<share name>";
const fileName = "<file name>";
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);
if (downloadFileResponse.blobBody) {
  console.log(`Downloaded file content: ${(await downloadFileResponse.blobBody).text()}`);
}

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

Troubleshooting

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:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Dalsze kroki

Więcej przykładów kodu

Contributing

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.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-17