Azure Storage fájlmegosztási ügyféloldali kódtár JavaScripthez – 12.29.1-es verzió

Az Azure Files teljes mértékben felügyelt fájlmegosztásokat kínál a felhőben, amelyek az iparági szabvány kiszolgálói üzenetblokk (SMB) protokollon keresztül érhetők el. Az Azure-fájlmegosztások egyidejűleg csatlakoztathatók a Windows, Linux és macOS felhőbeli vagy helyszíni üzembe helyezésével. Emellett az Azure-fájlmegosztások gyorsítótárazhatók a Windows-kiszolgálókon az Azure File Sync használatával, hogy gyorsan elérhessék az adatok felhasználási helyét.

Ez a projekt egy JavaScript-ügyfélkódtárat biztosít, amely megkönnyíti a Microsoft Azure File Storage szolgáltatás használatát.

A csomagban található ügyfélkódtárak használatával:

• Fájlszolgáltatás tulajdonságainak lekérése/beállítása
• Fájlmegosztások létrehozása/listázása/törlése
• Fájlkönyvtárak létrehozása/listázása/törlése
• Fájlok létrehozása/olvasása/listázása/frissítése/törlése

Megjegyzés: Ez a csomag korábban @azure/storage-filenéven lett közzétéve. Át lett nevezve @azure/storage-file-share, hogy jobban igazodjon az Azure Storage Files DataLake közelgő új csomagjához, és konzisztens API-kat biztosít az Azure-beli fájlok kezeléséhez.

Főbb hivatkozások:

• forráskód
• Csomag (npm)
• API referenciadokumentációja
• termékdokumentáció
• Samples
• Azure Storage-fájl REST API-jait

Kezdő lépések

Jelenleg támogatott környezetek

• A Node.js LTS-verziói
• A Safari, a Chrome, az Edge és a Firefox legújabb verziói.

További részletekért tekintse meg támogatási szabályzatunkat .

Prerequisites

• Azure-előfizetés
• Tárfiók

A csomag telepítése

A JavaScripthez készült Azure File Storage-ügyfélkódtár telepítésének elsődleges módja az npm-csomagkezelő használata. Írja be a következőt egy terminálablakba:

npm install @azure/storage-file-share

Az ügyfél hitelesítése

Az Azure Storage számos módon támogatja a hitelesítést. Az Azure Storage-fájlmegosztási szolgáltatás használatához létre kell hoznia egy Storage-ügyfélpéldányt – például ShareServiceClient, ShareClientvagy ShareDirectoryClient. A létrehozásához tekintse meg mintákat a hitelesítésről.

• Megosztott kulcs
• közös hozzáférésű jogosultságkódok

Compatibility

Ez a kódtár kompatibilis a Node.js és a böngészőkkel, és az LTS Node.js (>=8.16.0) és a Chrome, a Firefox és az Edge legújabb verzióival van érvényesítve.

Webes dolgozók

Ehhez a kódtárhoz bizonyos DOM-objektumoknak globálisan elérhetővé kell lenniük a böngészőben való használatkor, amelyeket a webmunkások alapértelmezés szerint nem tesznek elérhetővé. Ezeket a függvénytárat a webmunkásokban való működéshez többszörösen kell feltöltenie.

További információkért tekintse meg dokumentációnkat az Azure SDK for JS webmunkásokban való használatához

Ez a kódtár a következő DOM API-któl függ, amelyek a webmunkásokban való használathoz külső polifilleket igényelnek:

• document
• DOMParser
• Node
• XMLSerializer

Különbségek a Node.js és a böngészők között

A Node.js és a böngésző futtatókörnyezete között különbségek vannak. A kódtár használatbavételekor figyelje meg a "CSAK ELÉRHETŐ NODE.JS FUTTATÓKÖRNYEZETBEN" megjelölt API-kat vagy osztályokat, vagy "CSAK BÖNGÉSZŐBEN ELÉRHETŐ".

• Ha egy fájl gzip vagy deflate formátumban tárolja a tömörített adatokat, és a tartalomkódolás ennek megfelelően van beállítva, a letöltési viselkedés eltér a Node.js és a böngészők között. A Node.js storage-ügyfelek tömörített formátumban töltik le a fájlt, míg böngészőkben az adatok tömörített formátumban lesznek letöltve.

Az alábbi funkciók, felületek, osztályok vagy függvények csak Node.js

• Megosztott kulcs engedélyezése a fióknév és a fiókkulcs alapján
  • StorageSharedKeyCredential
• Közös hozzáférésű jogosultságkód (SAS) létrehozása
  • generateAccountSASQueryParameters()
  • generateFileSASQueryParameters()
• Párhuzamos feltöltés és letöltés. Vegye figyelembe, hogy ShareFileClient.uploadData() Node.js és böngészőkben is elérhető.
  • ShareFileClient.uploadFile()
  • ShareFileClient.uploadStream()
  • ShareFileClient.downloadToBuffer()
  • ShareFileClient.downloadToFile()

Az alábbi funkciók, felületek, osztályok vagy függvények csak böngészőkben érhetők el

N/A

JavaScript-csomag

Ahhoz, hogy ezt az ügyfélkódtárat a böngészőben használhassa, először egy kötegelőt kell használnia. Ennek módjáról a kötegelési dokumentációban olvashat.

CORS

Ha böngészőkre van szüksége, be kell állítania forrásközi erőforrás-megosztási (CORS) szabályokat a tárfiókhoz. Nyissa meg az Azure Portalt és az Azure Storage Explorert, keresse meg a tárfiókot, hozzon létre új CORS-szabályokat a blob-/üzenetsor-/fájl-/táblaszolgáltatás(ok)hoz.

A hibakereséshez például az alábbi CORS-beállításokat hozhatja létre. Azonban az éles környezetben a követelményeknek megfelelően szabja testre a beállításokat.

• Engedélyezett források: *
• Engedélyezett parancsok: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Engedélyezett fejlécek: *
• Közzétett fejlécek: *
• Maximális életkor (másodperc): 86400

Főbb fogalmak

Az Azure Storage-fájlmegosztási szolgáltatást a következő összetevők és a hozzájuk tartozó ügyfélkódtárak alkotják:

• Maga a tárfiók , amelyet egy ShareServiceClient
• A tárfiókon belüli fájlmegosztás , amelyet egy ShareClient
• A fájlmegosztáson belül címtárak nem kötelező hierarchiája, amelyet példányok jelölnek
• A fájlmegosztáson belüli fájl, amely legfeljebb 1 TiB méretű lehet, és amelyet egy ShareFileClient

Examples

• Csomag importálása
• Share Service-ügyfélalkalmazás létrehozása
• Fiókmegosztások listázása
• Új megosztás és címtár létrehozása
• Azure-fájl létrehozása, majd feltöltés
• Fájlok és könyvtárak listázása címtár
• Fájl letöltése és sztringgé alakítása (Node.js)
• Fájl letöltése és konvertálása sztringgé (Böngészők)

A csomag importálása

Az ügyfelek használatához importálja a csomagot a fájlba:

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

Másik lehetőségként csak a szükséges típusokat importálja szelektíven:

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

A share service-ügyfél létrehozása

A ShareServiceClient megköveteli a fájlmegosztási szolgáltatás URL-címét és a hozzáférési hitelesítő adatokat. Emellett a options paraméter bizonyos beállításait is elfogadja.

kapcsolati sztring használata

Másik lehetőségként létrehozhat egy ShareServiceClient a fromConnectionString() statikus metódussal, argumentumként pedig a teljes kapcsolati sztringgel. (A kapcsolati sztring az Azure Portalról kérhető le.)

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

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

StorageSharedKeyCredential

Adjon meg egy StorageSharedKeyCredential a fiók nevével és a fiókkulcsával. (A fióknév és a fiókkulcs az Azure Portalon szerezhető be.)

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,
);

SAS-jogkivonattal

Emellett egy ShareServiceClient is létrehozhat közös hozzáférésű jogosultságkódokkal (SAS). Az SAS-jogkivonatot lekérheti az Azure Portalról, vagy létrehozhat egyet generateAccountSASQueryParameters()használatával.

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}`,
);

Megosztások listázása a fiókban

Használja a ShareServiceClient.listShares() a fiókban lévő megosztások iterátorához az új for-await-of szintaxissal:

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}`);
}

Másik lehetőségként for-await-ofnélkül:

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());
}

Új megosztás és könyvtár létrehozása

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`);

Azure-fájl létrehozása, majd feltöltése

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`);

Fájlok és könyvtárak listázása könyvtár alatt

Az új DirectoryClient.listFilesAndDirectories() szintaxissal a for-await-of használatával DirectoryClient.listFilesAndDirectories() fájlokat és könyvtárakat is iterátorként használhatja. A kind tulajdonság segítségével megállapíthatja, hogy az iterm könyvtár vagy fájl-e.

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++;
}

Másik lehetőségként for-await-ofhasználata nélkül:

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++;
}

Az iterációval kapcsolatos teljes mintát lásd: samples/v12/typescript/src/listFilesAndDirectories.ts.

Fájl letöltése és sztringgé alakítása (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);
  });
}

Fájl letöltése és sztringgé alakítása (Böngészők)

Kérjük, olvassa el a JavaScript Bundle részt a könyvtár böngészőben való használatával kapcsolatos további információkért.

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()}`);
}

Az egyszerű ShareServiceClient forgatókönyvek teljes példája a samples/v12/typescript/src/shareSerivceClient.ts oldalon található.

Troubleshooting

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a AZURE_LOG_LEVEL környezeti változót info. Másik lehetőségként a naplózás futásidőben is engedélyezhető a setLogLevel meghívásával a @azure/logger:

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

setLogLevel("info");

Következő lépések

További kódminták

• Fájlmegosztási tárminták (JavaScript)
• Fájlmegosztási tárminták (TypeScript)
• fájlmegosztás tárolási teszteseteinek

Contributing

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót , amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

A tárolótárak tesztkörnyezetének beállításával kapcsolatos további információkért tekintse meg társpecifikus útmutatót.