V tomto článku se dozvíte, jak se připojit ke službě Azure Blob Storage pomocí klientské knihovny služby Azure Blob Storage pro JavaScript. Po připojení může váš kód pracovat s kontejnery, objekty blob a funkcemi služby Blob Storage.
Pro klientské aplikace (prohlížeč) potřebujete nástroje pro sdružování.
Nastavení projektu
Otevřete příkazový řádek a přejděte do složky projektu. Změňte YOUR-DIRECTORY název složky:
cd YOUR-DIRECTORY
Pokud soubor ještě nemáte package.json v adresáři, inicializujte projekt a vytvořte ho:
npm init -y
Nainstalujte TypeScript a klientskou knihovnu azure Blob Storage pro JavaScript s typy TypeScript:
npm install typescript @azure/storage-blob
Pokud chcete používat připojení bez hesla pomocí ID Microsoft Entra, nainstalujte klientskou knihovnu Azure Identity pro JavaScript:
npm install @azure/identity
Autorizace přístupu a připojení ke službě Blob Storage
Microsoft Entra ID poskytuje nejbezpečnější připojení tím, že spravuje identitu připojení (spravovaná identita). Tato funkce bez hesla umožňuje vyvíjet aplikaci, která nevyžaduje žádné tajné kódy (klíče nebo připojovací řetězec) uložené v kódu.
Nastavení přístupu k identitě ke cloudu Azure
Pokud se chcete připojit k Azure bez hesel, musíte nastavit identitu Azure nebo použít existující identitu. Po nastavení identity nezapomeňte k identitě přiřadit příslušné role.
Pokud chcete autorizovat přístup bez hesla pomocí ID Microsoft Entra, budete muset použít přihlašovací údaje Azure. Jaký typ přihlašovacích údajů potřebujete, závisí na tom, kde vaše aplikace běží. Tuto tabulku použijte jako vodítko.
Váš prostředek úložiště musí mít přiřazenou jednu nebo více následujících rolí Azure RBAC k prostředku identity, ke kterému se plánujete připojit. Nastavte role Azure Storage pro každou identitu, kterou jste vytvořili v předchozím kroku: cloud Azure, místní vývoj.
Po dokončení instalace potřebuje každá identita aspoň jednu z odpovídajících rolí:
Po nastavení rolí identit účtu úložiště Azure a místního prostředí vytvořte soubor TypeScript, který obsahuje @azure/identity balíček. Vytvořte přihlašovací údaje, například DefaultAzureCredential, pro implementaci připojení bez hesla ke službě Blob Storage. Pomocí tohoto pověření se ověřte pomocí objektu BlobServiceClient .
// connect-with-default-azure-credential.js
// You must set up RBAC for your identity with one of the following roles:
// - Storage Blob Data Reader
// - Storage Blob Data Contributor
import { DefaultAzureCredential } from '@azure/identity';
import { BlobServiceClient } from '@azure/storage-blob';
import * as dotenv from 'dotenv';
dotenv.config();
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');
const blobServiceClient = new BlobServiceClient(
`https://${accountName}.blob.core.windows.net`,
new DefaultAzureCredential()
);
async function main() {
const containerName = 'my-container';
const blobName = 'my-blob';
const timestamp = Date.now();
const fileName = `my-new-file-${timestamp}.txt`;
// create container client
const containerClient = await blobServiceClient.getContainerClient(
containerName
);
// create blob client
const blobClient = await containerClient.getBlockBlobClient(blobName);
// download file
const downloadResult = await blobClient.downloadToFile(fileName);
if (downloadResult.errorCode) throw Error(downloadResult.errorCode);
console.log(
`${fileName} downloaded ${downloadResult.contentType}, isCurrentVersion: ${downloadResult.isCurrentVersion}`
);
}
main()
.then(() => console.log(`success`))
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
Balíček dotenv se používá ke čtení názvu účtu úložiště ze .env souboru. Tento soubor by neměl být vrácen do správy zdrojového kódu. Pokud jako součást nastavení DefaultAzureCredential použijete místní instanční objekt, všechny informace o zabezpečení pro tyto přihlašovací údaje se také přesunou do .env souboru.
Pokud plánujete nasadit aplikaci na servery a klienty, kteří běží mimo Azure, vytvořte jednu z přihlašovacích údajů , která vyhovuje vašim potřebám.
// connect-with-account-name-and-key.js
import {
BlobServiceClient,
StorageSharedKeyCredential
} from '@azure/storage-blob';
import * as dotenv from 'dotenv';
import path from 'path';
dotenv.config();
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY as string;
if (!accountName) throw Error('Azure Storage accountName not found');
if (!accountKey) throw Error('Azure Storage accountKey not found');
const sharedKeyCredential = new StorageSharedKeyCredential(
accountName,
accountKey
);
const blobServiceClient = new BlobServiceClient(
`https://${accountName}.blob.core.windows.net`,
sharedKeyCredential
);
async function main(): Promise<void> {
const containerName = 'my-container';
const blobName = 'my-blob';
const timestamp = Date.now();
const fileName = path.join(
__dirname,
'../files',
`my-new-file-${timestamp}.txt`
);
// create container client
const containerClient = await blobServiceClient.getContainerClient(
containerName
);
// create blob client
const blobClient = await containerClient.getBlockBlobClient(blobName);
// download file
const downloadResult = await blobClient.downloadToFile(fileName);
if (downloadResult.errorCode) throw Error(downloadResult.errorCode);
console.log(
`${fileName} downloaded, created on ${downloadResult.createdOn}}`
);
}
main()
.then(() => console.log(`success`))
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
Balíček dotenv se používá ke čtení názvu a klíče účtu úložiště ze .env souboru. Tento soubor by neměl být vrácen do správy zdrojového kódu.
Informace o tom, jak získat klíče účtu a osvědčené postupy pro správnou správu a ochranu klíčů, najdete v tématu Správa přístupových klíčů k účtu úložiště.
Důležité
Přístupový klíč účtu by se měl používat s opatrností. Pokud dojde ke ztrátě nebo náhodnému umístění přístupového klíče k účtu do nezabezpečeného umístění, může být vaše služba zranitelná. Každý, kdo má přístupový klíč, může autorizovat požadavky na účet úložiště a efektivně má přístup ke všem datům. DefaultAzureCredential poskytuje vylepšené funkce a výhody zabezpečení a je doporučeným přístupem ke správě autorizace služeb Azure.
Pomocí koncového bodu služby blob a tokenu SAS vytvořte identifikátor URI pro váš prostředek. Pak vytvořte objekt BlobServiceClient s identifikátorem URI. Token SAS je řada párů název/hodnota v řetězci dotazu ve formátu, například:
Ve scénářích, ve kterých se používají sdílené přístupové podpisy (SAS), microsoft doporučuje používat SAS delegování uživatele. Sas delegování uživatele je zabezpečený pomocí přihlašovacích údajů Microsoft Entra místo klíče účtu. Další informace najdete v tématu Vytvoření SAS delegování uživatele pomocí JavaScriptu.
Vytvoření objektu ContainerClient
Objekt ContainerClient můžete vytvořit buď z objektu BlobServiceClient, nebo přímo.
Vytvoření objektu ContainerClient z BlobServiceClient
// Azure Storage dependency
import { ContainerClient } from '@azure/storage-blob';
// Azure authentication for credential dependency
import { DefaultAzureCredential } from '@azure/identity';
// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();
// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');
// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;
// Unique container name
const timeStamp = Date.now();
const containerName = `my-container`;
async function main(): Promise<void> {
try {
// create container client from DefaultAzureCredential
const containerClient = new ContainerClient(
`${baseUrl}/${containerName}`,
new DefaultAzureCredential()
);
// do something with containerClient...
let i = 1;
// List blobs in container
for await (const blob of containerClient.listBlobsFlat({
includeMetadata: true,
includeSnapshots: false,
includeTags: true,
includeVersions: false,
prefix: ''
})) {
console.log(`Blob ${i++}: ${blob.name}`);
}
} catch (err) {
console.log(err);
throw err;
}
}
main()
.then(() => console.log(`success`))
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
// Azure Storage dependency
import {
ContainerClient,
StorageSharedKeyCredential
} from '@azure/storage-blob';
// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();
// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');
// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY as string;
if (!accountKey) throw Error('Azure Storage accountKey not found');
const sharedKeyCredential = new StorageSharedKeyCredential(
accountName,
accountKey
);
const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
async function main(): Promise<void> {
try {
// create container from ContainerClient
const containerClient = new ContainerClient(
`${baseUrl}/${containerName}`,
sharedKeyCredential
);
// do something with containerClient...
let i = 1;
// List blobs in container
for await (const blob of containerClient.listBlobsFlat({
includeMetadata: true,
includeSnapshots: false,
includeTags: true,
includeVersions: false,
prefix: ''
})) {
console.log(`Blob ${i++}: ${blob.name}`);
}
} catch (err) {
console.log(err);
throw err;
}
}
main()
.then(() => console.log(`success`))
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
Důležité
Přístupový klíč účtu by se měl používat s opatrností. Pokud dojde ke ztrátě nebo náhodnému umístění přístupového klíče k účtu do nezabezpečeného umístění, může být vaše služba zranitelná. Každý, kdo má přístupový klíč, může autorizovat požadavky na účet úložiště a efektivně má přístup ke všem datům. DefaultAzureCredential poskytuje vylepšené funkce a výhody zabezpečení a je doporučeným přístupem ke správě autorizace služeb Azure.
// Azure Storage dependency
import { ContainerClient } from '@azure/storage-blob';
// For development environment - include environment variables
import * as dotenv from 'dotenv';
dotenv.config();
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');
// Container must exist prior to running this script
const containerName = `my-container`;
// SAS token must have LIST permissions on container that haven't expired
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN as string;
// Create SAS URL
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}?${sasToken}`;
async function main(): Promise<void> {
try {
// create container client from SAS token
const containerClient = new ContainerClient(sasUrl);
// do something with containerClient...
let i = 1;
// List blobs in container
for await (const blob of containerClient.listBlobsFlat({
includeMetadata: true,
includeSnapshots: false,
includeTags: true,
includeVersions: false,
prefix: ''
})) {
console.log(`Blob ${i++}: ${blob.name}`);
}
} catch (err) {
console.log(err);
throw err;
}
}
main()
.then(() => console.log(`success`))
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
Poznámka:
Ve scénářích, ve kterých se používají sdílené přístupové podpisy (SAS), microsoft doporučuje používat SAS delegování uživatele. Sas delegování uživatele je zabezpečený pomocí přihlašovacích údajů Microsoft Entra místo klíče účtu. Další informace najdete v tématu Vytvoření SAS delegování uživatele pomocí JavaScriptu.
Balíček dotenv se používá ke čtení názvu účtu úložiště ze .env souboru. Tento soubor by neměl být vrácen do správy zdrojového kódu.
Vytvoření objektu BlobClient
Můžete vytvořit kterýkoli z objektů BlobClient, které jsou uvedené níže, buď z ContainerClient, nebo přímo.
// Azure Storage dependency
import {
BlockBlobClient,
BlockBlobUploadHeaders,
BlockBlobUploadResponse
} from '@azure/storage-blob';
import { getBlockBlobClientFromDefaultAzureCredential } from './auth-get-client';
// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();
// Container must exist prior to running this script
const containerName = `my-container`;
// Random blob name and contents
const timeStamp = Date.now();
const blobName = `${timeStamp}-my-blob.txt`;
const fileContentsAsString = 'Hello there.';
const blockBlobClient: BlockBlobClient =
getBlockBlobClientFromDefaultAzureCredential(containerName, blobName);
async function main(
blockBlobClient: BlockBlobClient
): Promise<BlockBlobUploadHeaders> {
// Get file url - available before contents are uploaded
console.log(`blob.url: ${blockBlobClient.url}`);
// Upload file contents
const result: BlockBlobUploadHeaders = await blockBlobClient.upload(
fileContentsAsString,
fileContentsAsString.length
);
if (result.errorCode) throw Error(result.errorCode);
// Get results
return result;
}
main(blockBlobClient)
.then((result) => {
console.log(result);
console.log(`success`);
})
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
/*
Response looks like this:
{
etag: '"0x8DAD247F1F4896E"',
lastModified: 2022-11-29T20:26:07.000Z,
contentMD5: <Buffer 9d 6a 29 63 87 20 77 db 67 4a 27 a3 9c 49 2e 61>,
clientRequestId: 'a07fdd1f-5937-44c7-984f-0699a48a05c0',
requestId: '3580e726-201e-0045-1a30-0474f6000000',
version: '2021-04-10',
date: 2022-11-29T20:26:06.000Z,
isServerEncrypted: true,
'content-length': '0',
server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
'x-ms-content-crc64': 'BLv7vb1ONT8=',
body: undefined
}
*/
// Azure Storage dependency
import {
BlockBlobClient,
BlockBlobUploadHeaders,
BlockBlobUploadResponse,
StorageSharedKeyCredential
} from '@azure/storage-blob';
// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();
// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');
// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY as string;
if (!accountKey) throw Error('Azure Storage accountKey not found');
// Create credential
const sharedKeyCredential: StorageSharedKeyCredential =
new StorageSharedKeyCredential(accountName, accountKey);
const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;
const fileContentsAsString = 'Hello there.';
async function main(): Promise<void> {
try {
// create blob from BlockBlobClient
const blockBlobClient = new BlockBlobClient(
`${baseUrl}/${containerName}/${blobName}`,
sharedKeyCredential
);
// Upload data to the blob
const blockBlobUploadResponse: BlockBlobUploadHeaders =
await blockBlobClient.upload(
fileContentsAsString,
fileContentsAsString.length
);
if (blockBlobUploadResponse.errorCode)
throw Error(blockBlobUploadResponse.errorCode);
console.log(`blob ${blockBlobClient.url} created`);
} catch (err) {
console.log(err);
throw err;
}
}
main()
.then(() => console.log(`success`))
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
Důležité
Přístupový klíč účtu by se měl používat s opatrností. Pokud dojde ke ztrátě nebo náhodnému umístění přístupového klíče k účtu do nezabezpečeného umístění, může být vaše služba zranitelná. Každý, kdo má přístupový klíč, může autorizovat požadavky na účet úložiště a efektivně má přístup ke všem datům. DefaultAzureCredential poskytuje vylepšené funkce a výhody zabezpečení a je doporučeným přístupem ke správě autorizace služeb Azure.
/**
* Best practice - use managed identity to avoid keys & connection strings
* managed identity is implemented with @azure/identity's DefaultAzureCredential
*
* The identity that the managed identity chain selects must have the
* correct roles applied in order to work correctly.
*
* For local development: add your personal identity on your resource group
* az role assignment create --assignee "<your-username>" \
* --role "Blob Data Contributor" \
* --resource-group "<your-resource-group-name>"
**/
//const logger = require('@azure/logger');
//logger.setLogLevel('info');
//<Snippet_Dependencies>
import {
BlobSASPermissions,
BlobSASSignatureValues,
BlobServiceClient,
BlockBlobClient,
BlockBlobUploadHeaders,
BlockBlobUploadResponse,
generateBlobSASQueryParameters,
SASProtocol,
SASQueryParameters,
ServiceGetUserDelegationKeyResponse
} from '@azure/storage-blob';
// used for local environment variables
import * as dotenv from 'dotenv';
dotenv.config();
// Get BlobServiceClient
import { getBlobServiceClientFromDefaultAzureCredential } from './auth-get-client';
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
const blobServiceClient: BlobServiceClient =
getBlobServiceClientFromDefaultAzureCredential();
//</Snippet_Dependencies>
//<Snippet_CreateBlobSas>
// Server creates User Delegation SAS Token for blob
async function createBlobSas(
blobServiceClient: BlobServiceClient,
blobName: string
): Promise<string> {
const containerName = 'my-container';
// Best practice: create time limits
const TEN_MINUTES = 10 * 60 * 1000;
const NOW = new Date();
// Best practice: set start time a little before current time to
// make sure any clock issues are avoided
const TEN_MINUTES_BEFORE_NOW = new Date(NOW.valueOf() - TEN_MINUTES);
const TEN_MINUTES_AFTER_NOW = new Date(NOW.valueOf() + TEN_MINUTES);
// Best practice: delegation key is time-limited
// When using a user delegation key, container must already exist
const userDelegationKey: ServiceGetUserDelegationKeyResponse =
await blobServiceClient.getUserDelegationKey(
TEN_MINUTES_BEFORE_NOW,
TEN_MINUTES_AFTER_NOW
);
if (userDelegationKey.errorCode) throw Error(userDelegationKey.errorCode);
// Need only create/write permission to upload file
const blobPermissionsForAnonymousUser = 'cw';
// Best practice: SAS options are time-limited
const sasOptions: BlobSASSignatureValues = {
blobName,
containerName,
permissions: BlobSASPermissions.parse(blobPermissionsForAnonymousUser),
protocol: SASProtocol.HttpsAndHttp,
startsOn: TEN_MINUTES_BEFORE_NOW,
expiresOn: TEN_MINUTES_AFTER_NOW
};
const sasQueryParameters: SASQueryParameters = generateBlobSASQueryParameters(
sasOptions,
userDelegationKey,
accountName
);
const sasToken: string = sasQueryParameters.toString();
return sasToken;
}
//</Snippet_CreateBlobSas>
//<Snippet_UploadToBlob>
// Client or another process uses SAS token to upload content to blob
async function uploadStringToBlob(
blobName: string,
sasToken,
textAsString: string
): Promise<BlockBlobUploadHeaders> {
// Get environment variables
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
const containerName = 'my-container';
// Create Url SAS token as query string with typical `?` delimiter
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}?${sasToken}`;
console.log(`\nBlobUrl = ${sasUrl}\n`);
// Create blob client from SAS token url
const blockBlobClient = new BlockBlobClient(sasUrl);
// Upload string
const blockBlobUploadResponse: BlockBlobUploadHeaders =
await blockBlobClient.upload(textAsString, textAsString.length, undefined);
if (blockBlobUploadResponse.errorCode)
throw Error(blockBlobUploadResponse.errorCode);
return blockBlobUploadResponse;
}
//</Snippet_UploadToBlob>
//<Snippet_Main>
async function main(blobServiceClient: BlobServiceClient) {
// Create random blob name for text file
const blobName = `${(0 | (Math.random() * 9e6)).toString(36)}.txt`;
// Server creates SAS Token
const userDelegationSasForBlob: string = await createBlobSas(
blobServiceClient,
blobName
);
// Server hands off SAS Token & blobName to client to
// Upload content
const result: BlockBlobUploadHeaders = await uploadStringToBlob(
blobName,
userDelegationSasForBlob,
'Hello Blob World'
);
if (result.errorCode) throw Error(result.errorCode);
console.log(`\n${blobName} uploaded successfully ${result.lastModified}\n`);
}
main(blobServiceClient)
.then(() => {
console.log(`success`);
})
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
//</Snippet_Main>
Poznámka:
Ve scénářích, ve kterých se používají sdílené přístupové podpisy (SAS), microsoft doporučuje používat SAS delegování uživatele. Sas delegování uživatele je zabezpečený pomocí přihlašovacích údajů Microsoft Entra místo klíče účtu. Další informace najdete v tématu Vytvoření SAS delegování uživatele pomocí JavaScriptu.
Balíček dotenv se používá ke čtení názvu účtu úložiště ze .env souboru. Tento soubor by neměl být vrácen do správy zdrojového kódu.