Azure Storage-fájlmegosztási ügyfélkódtár JavaScripthez – 12.24.0-s 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ó
• minták
• Azure Storage-fájl REST API-jait

Kezdetekhez

Jelenleg támogatott környezetek

• 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 a támogatási szabályzat.

Előfeltételek

• Egy Azure-előfizetés
• Egy Storage-fió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

Kompatibilitás

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.

Webmunkások

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 további információt a csomagküldő dokumentációbantalál.

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:

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

Példák

• 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:

const AzureStorageFileShare = require("@azure/storage-file-share");

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

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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.)

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

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.)

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

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.

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

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:

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() {
  let shareIter = serviceClient.listShares();
  let i = 1;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

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

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() {
  let 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();

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

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

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

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

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

Az új for-await-of szintaxissal a DirectoryClient.listFilesAndDirectories() használatával for-await-of 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.

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

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

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

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

  let 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}`);
    }
    item = await dirIter.next();
  }
}

main();

Az iterálás teljes mintájáért tekintse meg mintákat/v12/typescript/src/listFilesAndDirectories.ts.

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

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

A kódtár böngészőben való használatáról további információt a JavaScript-csomag szakaszában talál.

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

Az egyszerű ShareServiceClient forgatókönyvek teljes példája minták/v12/typescript/src/shareSerivceClient.ts.

Hibaelhárítás

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:

const { setLogLevel } = require("@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

Hozzájárulás

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.