Megosztás a következőn keresztül:

Rövid útmutató: Azure Blob Storage-ügyfélkódtár Node.js TypeScript használatával

Első lépések az Azure Blob Storage ügyfélkódtárával Node.js a TypeScripttel a blobok és tárolók kezeléséhez.

Ebben a cikkben lépéseket követve telepítheti a csomagot, és kipróbálhatja az alapműveletek példakódját.

API-referencia kódtár forráskódcsomagja |

Előfeltételek

Beállítás

Ez a szakasz végigvezeti egy projekt előkészítésén az Azure Blob Storage-ügyfélkódtár Node.js való használatához.

A Node.js projekt létrehozása

Hozzon létre egy Blob-Quickstart nevű TypeScript-alkalmazást.

  1. Egy konzolablakban (például parancsmag, PowerShell vagy Bash) hozzon létre egy új könyvtárat a projekthez:

    mkdir blob-quickstart

  2. Váltson az újonnan létrehozott blob-rövid útmutató könyvtárra:

    cd blob-quickstart

  3. Hozzon létre egy package.json fájlt:

    npm init -y

  4. Nyissa meg a projektet a Visual Studio Code-ban:

    code .

  5. Szerkessze a package.json fájlt, és adja hozzá a következő tulajdonságokat az ESM TypeScripttel való támogatásához:

    "type": "module",

A csomagok telepítése

A projektkönyvtárból telepítse a következő csomagokat a npm install paranccsal.

  1. Telepítse az Azure Storage npm-csomagot:

    npm install @azure/storage-blob

  2. Telepítse az ebben a rövid útmutatóban használt egyéb függőségeket:

    npm install uuid dotenv @types/node @types/uuid

  3. Hozzon létre egy tsconfig.json fájlt a projektkönyvtárban az alábbi tartalommal.

    {
    "compilerOptions": {
      "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
      "module": "ESNext",                                /* Specify what module code is generated. */
      "moduleResolution": "node",                     /* Specify how TypeScript looks up a file from a given module specifier. */
      "outDir": "dist",                                   /* Specify an output folder for all emitted files. */
      "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
      "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
      "strict": true,                                      /* Enable all strict type-checking options. */
      "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
    }
  }

Objektummodell

Az Azure Blob Storage nagy mennyiségű strukturálatlan adat tárolására van optimalizálva. A strukturálatlan adatok olyan adatok, amelyek nem követnek egy adott adatmodellt vagy -definíciót, például szöveges vagy bináris adatok. A Blob Storage háromféle erőforrást kínál:

  • A tárfiók
  • Tároló a tárfiókban
  • Blob a tárolóban

Az alábbi ábra az ezen erőforrások közötti kapcsolatot mutatja be.

A Blob Storage architektúrájának diagramja.

Az alábbi JavaScript-osztályokkal kezelheti ezeket az erőforrásokat:

  • BlobServiceClient: Az BlobServiceClient osztály lehetővé teszi az Azure Storage-erőforrások és blobtárolók manipulálására.
  • ContainerClient: Az ContainerClient osztály lehetővé teszi az Azure Storage-tárolók és a blobok manipulálására.
  • BlobClient: Az BlobClient osztály lehetővé teszi az Azure Storage-blobok manipulálására.

Kódpéldák

Ezek a példakódrészletek bemutatják, hogyan végezheti el a következő feladatokat a JavaScripthez készült Azure Blob Storage ügyfélkódtárral:

A mintakód a GitHubon is elérhető.

Hitelesítés az Azure-ban és a blobadatokhoz való hozzáférés engedélyezése

Az Azure Blob Storage-ba irányuló alkalmazáskéréseket engedélyezni kell. DefaultAzureCredential Az Azure Identity-ügyfélkódtár által biztosított osztály használata ajánlott módszer az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatok implementálásához a kódban, beleértve a Blob Storage-t is.

Az Azure Blob Storage-ra irányuló kéréseket a fiók hozzáférési kulcsával is engedélyezheti. Ezt a megközelítést azonban körültekintően kell alkalmazni. A fejlesztőknek szorgalmasnak kell lenniük, hogy soha ne tegyék elérhetővé a hozzáférési kulcsot nem biztonságos helyen. Bárki, aki rendelkezik a hozzáférési kulccsal, engedélyezheti a tárfiókra irányuló kérelmeket, és hatékonyan hozzáférhet az összes adathoz. DefaultAzureCredential továbbfejlesztett felügyeleti és biztonsági előnyöket kínál a fiókkulcson keresztül a jelszó nélküli hitelesítés engedélyezéséhez. Az alábbi példában mindkét lehetőség látható.

DefaultAzureCredential több hitelesítési módszert támogat, és meghatározza, hogy melyik metódust kell használni futásidőben. Ez a megközelítés lehetővé teszi, hogy az alkalmazás különböző hitelesítési módszereket használjon különböző környezetekben (helyi és éles környezetben) környezetspecifikus kód implementálása nélkül.

A hitelesítő adatokat kereső sorrend és helyek DefaultAzureCredential az Azure Identity-kódtár áttekintésében találhatók.

Az alkalmazás például hitelesítheti az Azure CLI bejelentkezési hitelesítő adataival a helyi fejlesztés során. Az alkalmazás ezután használhat felügyelt identitást az Azure-ban való üzembe helyezés után. Ehhez az áttűnéshez nincs szükség kódmódosításra.

Szerepkörök hozzárendelése a Microsoft Entra felhasználói fiókjához

Helyi fejlesztéskor győződjön meg arról, hogy a blobadatokhoz hozzáférő felhasználói fiók rendelkezik a megfelelő engedélyekkel. A blobadatok olvasásához és írásához tárolóblobadatok közreműködője szükséges. A szerepkör hozzárendeléséhez hozzá kell rendelnie a Felhasználói hozzáférés rendszergazdája szerepkört, vagy egy másik szerepkört, amely tartalmazza a Microsoft.Authorization/roleAssignments/write műveletet. Azure RBAC-szerepköröket rendelhet egy felhasználóhoz az Azure Portal, az Azure CLI vagy az Azure PowerShell használatával. A Storage Blob Data Közreműködő szerepkörével kapcsolatos további információkért lásd: Storage Blob Data Közreműködő. A szerepkör-hozzárendelésekhez elérhető hatókörökről további információt az Azure RBAC hatókörének ismertetése című témakörben talál.

Ebben a forgatókönyvben engedélyeket rendel hozzá a felhasználói fiókjához, amely a tárfiókra terjed ki, hogy kövesse a minimális jogosultság elvét. Ez a gyakorlat csak a minimálisan szükséges engedélyeket biztosítja a felhasználóknak, és biztonságosabb éles környezeteket hoz létre.

Az alábbi példa a Storage Blob Data Contributor szerepkört rendeli hozzá a felhasználói fiókjához, amely olvasási és írási hozzáférést biztosít a tárfiók blobadataihoz.

Fontos

A szerepkör-hozzárendelés propagálása a legtöbb esetben egy-két percet vesz igénybe az Azure-ban, de ritkán akár nyolc percet is igénybe vehet. Ha hitelesítési hibákat kap a kód első futtatásakor, várjon néhány percet, és próbálkozzon újra.

  1. Az Azure Portalon keresse meg a tárfiókot a fő keresősávon vagy a bal oldali navigációs sávon.

  2. A tárfiók áttekintési lapján válassza a Hozzáférés-vezérlés (IAM) lehetőséget a bal oldali menüben.

  3. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelések lapot.

  4. Válassza a +Hozzáadás lehetőséget a felső menüből, majd a szerepkör-hozzárendelés hozzáadása lehetőséget az eredményül kapott legördülő menüből.

    Képernyőkép egy szerepkör hozzárendeléséről.

  5. A keresőmezővel szűrheti az eredményeket a kívánt szerepkörre. Ebben a példában keresse meg a Storage Blob-adatszolgáltatót, és válassza ki a megfelelő eredményt, majd válassza a Tovább gombot.

  6. A Hozzáférés hozzárendelése területen válassza a Felhasználó, csoport vagy szolgáltatásnév lehetőséget, majd válassza a + Tagok kijelölése lehetőséget.

  7. A párbeszédpanelen keresse meg a Microsoft Entra-felhasználónevet (általában a user@domain e-mail-címét), majd válassza a Párbeszédpanel alján található Kiválasztás lehetőséget.

  8. Válassza a Véleményezés + hozzárendelés lehetőséget a végső lapra való ugráshoz, majd a folyamat befejezéséhez a Véleményezés + hozzárendelés lehetőséget.

Jelentkezzen be, és csatlakoztassa az alkalmazáskódot az Azure-hoz a DefaultAzureCredential használatával

A tárfiókban lévő adatokhoz való hozzáférést az alábbi lépések végrehajtásával engedélyezheti:

  1. Győződjön meg arról, hogy ugyanazzal a Microsoft Entra-fiókkal van hitelesítve, amelyhez a szerepkört hozzárendelte a tárfiókban. Hitelesítést az Azure CLI, a Visual Studio Code vagy az Azure PowerShell használatával végezhet.

    Jelentkezzen be az Azure-ba az Azure CLI-vel a következő paranccsal:

    az login

  2. A használathoz DefaultAzureCredentialgyőződjön meg arról, hogy a @azure\identity csomag telepítve van, és az osztály importálva van:

    import { DefaultAzureCredential } from '@azure/identity';

  3. Adja hozzá ezt a kódot a blokkba try . Amikor a kód a helyi munkaállomáson fut, DefaultAzureCredential a kiemelt eszköz fejlesztői hitelesítő adatait használja az Azure-beli hitelesítéshez. Ilyen eszközök például az Azure CLI vagy a Visual Studio Code.

    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');

// Add `Storage Blob Data Contributor` role assignment to the identity
const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

  4. Frissítse a tárfiók nevét AZURE_STORAGE_ACCOUNT_NAMEa .env fájlban vagy a környezet változóiban. A tárfiók neve az Azure Portal áttekintési oldalán található.

    Képernyőkép a tárfiók nevének megkereséséről.

    Feljegyzés

    Az Azure-ban való üzembe helyezéskor ugyanezzel a kóddal engedélyezheti az Azure Storage-ra irányuló kéréseket egy Azure-ban futó alkalmazásból. Azonban engedélyeznie kell a felügyelt identitást az alkalmazásban az Azure-ban. Ezután konfigurálja a tárfiókot úgy, hogy lehetővé tegye a felügyelt identitás csatlakozását. Az Azure-szolgáltatások közötti kapcsolat konfigurálásával kapcsolatos részletes utasításokért tekintse meg az Azure által üzemeltetett alkalmazások hitelesítési útmutatójában.

Tároló létrehozása

Hozzon létre egy új tárolót a tárfiókban. Az alábbi példakód egy BlobServiceClient objektumot használ, és meghívja a getContainerClient metódust egy tárolóra mutató hivatkozás lekéréséhez. Ezután a kód meghívja a létrehozási metódust, hogy ténylegesen létrehozza a tárolót a tárfiókban.

Adja hozzá ezt a kódot a blokk végéhez try :

  const containerName = 'quickstart' + uuidv4();

  console.log('\nCreating container...');
  console.log('\t', containerName);

  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse: ContainerCreateResponse = await containerClient.create();
  console.log(
    `Container was created successfully.\n\trequestId:${createContainerResponse.requestId}\n\tURL: ${containerClient.url}`
  );

A tárolók létrehozásával és további kódmintákkal kapcsolatos további információkért lásd : Blobtároló létrehozása JavaScripttel.

Fontos

A tárolók nevei csak kisbetűket tartalmazhatnak. A tárolók és blobok elnevezésével kapcsolatos további információkért lásd a tárolók, blobok és metaadatok elnevezését és hivatkozását.

Blobok feltöltése tárolóba

Töltsön fel egy blobot a tárolóba. Az alábbi kód egy BlockBlobClient-objektumra mutató hivatkozást kap a getBlockBlobClient metódus meghívásával a ContainerClienten a Tároló létrehozása szakaszból.

A kód a feltöltési módszer meghívásával feltölti a szöveges sztringadatokat a blobba.

Adja hozzá ezt a kódot a blokk végéhez try :

  const blobName = 'quickstart' + uuidv4(); + '.txt';
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  console.log(
    `\nUploading to Azure storage as blob\n\tname: ${blobName}:\n\tURL: ${blockBlobClient.url}`
  );

  const data = 'Hello, World!';
  const uploadBlobResponse: BlockBlobUploadResponse = await blockBlobClient.upload(data, data.length);
  console.log(
    `Blob was uploaded successfully. requestId: ${uploadBlobResponse.requestId}`
  );

Ha többet szeretne megtudni a blobok feltöltéséről, és további kódmintákat szeretne megismerni, olvassa el a Blob feltöltése JavaScripttel című témakört.

Tárolóban lévő blobok kilistázása

Listázza a tárolóban található blobokat. Az alábbi kód meghívja a listBlobsFlat metódust . Ebben az esetben csak egy blob található a tárolóban, ezért a listázási művelet csak azt az egy blobot adja vissza.

Adja hozzá ezt a kódot a blokk végéhez try :

  console.log('\nListing blobs...');

  for await (const blob of containerClient.listBlobsFlat()) {
    const tempBlockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blob.name);

    console.log(
      `\n\tname: ${blob.name}\n\tURL: ${tempBlockBlobClient.url}\n`
    );
  }

A blobok listázásáról és további kódminták megismeréséről további információt a Blobok listázása JavaScript használatával című témakörben talál.

Blobok letöltése

Töltse le a blobot, és jelenítse meg a tartalmat. Az alábbi kód meghívja a letöltési módszert a blob letöltésére.

Adja hozzá ezt a kódot a blokk végéhez try :

  const offset = 0;         // start at beginning
  const length = undefined; // read all

  const downloadBlockBlobResponse: BlobDownloadResponseParsed = await blockBlobClient.download(offset, length);
  console.log('\nDownloaded blob content...');
  console.log(
    '\t',
    await streamToText(downloadBlockBlobResponse.readableStreamBody as NodeJS.ReadableStream)
  );

Az alábbi kód visszaalakít egy streamet sztringgé a tartalom megjelenítéséhez.

Adja hozzá ezt a kódot :

// Convert stream to text
async function streamToText(readable: NodeJS.ReadableStream): Promise<string> {
  readable.setEncoding('utf8');
  let data = '';
  for await (const chunk of readable) {
    data += chunk;
  }
  return data;
}

Ha többet szeretne megtudni a blobok letöltéséről, és további kódmintákat szeretne megismerni, olvassa el a Blob letöltése JavaScripttel című témakört.

Tároló törlése

Törölje a tárolót és a tárolón belüli összes blobot. Az alábbi kód megtisztítja az alkalmazás által létrehozott erőforrásokat a teljes tároló törlési módszerrel történő eltávolításával.

Adja hozzá ezt a kódot a blokk végéhez try :

  console.log('\nDeleting container...');

  const deleteContainerResponse: ContainerDeleteResponse = await containerClient.delete();
  console.log(
    'Container was deleted successfully. requestId: ',
    deleteContainerResponse.requestId
  );

Ha többet szeretne megtudni a tároló törléséről, és további kódmintákat szeretne megismerni, olvassa el a Blob-tároló törlése és visszaállítása JavaScripttel című témakört.

A kód futtatása

  1. Egy Visual Studio Code-terminálból hozza létre az alkalmazást.

    tsc

  2. Futtassa az alkalmazást.

    node dist/index.js

  3. Az alkalmazás kimenete a következő példához hasonló:

    Azure Blob storage - JavaScript quickstart sample

Creating container...
    quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da

Uploading to Azure Storage as blob:
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Listing blobs...
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Downloaded blob content...
    Hello, World!

Deleting container...
Done

Haladjon végig a hibakeresőben található kódon, és ellenőrizze az Azure Portalt a folyamat során. Ellenőrizze, hogy a tároló létre lett-e hozva. Megnyithatja a blobot a tárolóban, és megtekintheti a tartalmat.

Az erőforrások eltávolítása

  1. Ha végzett ezzel a rövid útmutatóval, törölje a címtárat blob-quickstart .
  2. Ha végzett az Azure Storage-erőforrással, az Azure CLI használatával távolítsa el a Storage-erőforrást.

Következő lépés

Azure Storage-minták és fejlesztői útmutatók JavaScripthez és TypeScripthez

  • Last updated on