Aan de slag met Azure Blob Storage en TypeScript
In dit artikel leest u hoe u verbinding maakt met Azure Blob Storage met behulp van de Azure Blob Storage-clientbibliotheek voor JavaScript. Zodra de code is verbonden, kan uw code worden uitgevoerd op containers, blobs en functies van de Blob Storage-service.
Broncode van | pakket (npm) | API-referentiebibliotheek | feedback geven
Vereisten
- Azure-abonnement: u kunt een gratis abonnement nemen
- Azure Storage-account: maak een opslagaccount
- Node.js LTS
- Voor clienttoepassingen (browsertoepassingen) hebt u bundelprogramma's nodig.
Uw project instellen
Open een opdrachtprompt en ga naar de projectmap. Ga naar
YOUR-DIRECTORY
de mapnaam:cd YOUR-DIRECTORY
Als u nog geen bestand in uw map hebt
package.json
, initialiseert u het project om het bestand te maken:npm init -y
Installeer TypeScript en de Azure Blob Storage-clientbibliotheek voor JavaScript met typeScript-typen:
npm install typescript @azure/storage-blob
Als u wachtwoordloze verbindingen wilt gebruiken met behulp van Microsoft Entra ID, installeert u de Azure Identity-clientbibliotheek voor JavaScript:
npm install @azure/identity
Toegang autoriseren en verbinding maken met Blob Storage
Microsoft Entra ID biedt de veiligste verbinding door de verbindingsidentiteit (beheerde identiteit) te beheren. Met deze functionaliteit zonder wachtwoord kunt u een toepassing ontwikkelen waarvoor geen geheimen (sleutels of verbindingsreeks s) zijn vereist die zijn opgeslagen in de code.
Identiteitstoegang tot de Azure-cloud instellen
Als u zonder wachtwoorden verbinding wilt maken met Azure, moet u een Azure-identiteit instellen of een bestaande identiteit gebruiken. Zodra de identiteit is ingesteld, moet u de juiste rollen toewijzen aan de identiteit.
Als u toegang zonder wachtwoord wilt autoriseren met Microsoft Entra ID, moet u een Azure-referentie gebruiken. Welk type referentie u nodig hebt, is afhankelijk van waar uw toepassing wordt uitgevoerd. Gebruik deze tabel als richtlijn.
Omgeving | Methode |
---|---|
Ontwikkelomgeving | Visual Studio Code |
Ontwikkelomgeving | Service/principal |
Apps die in Azure worden gehost | Installatie van door Azure gehoste apps |
On-premises | Installatie van on-premises apps |
Opslagaccountrollen instellen
Voor uw opslagresource moeten een of meer van de volgende Azure RBAC-rollen zijn toegewezen aan de identiteitsresource waarmee u verbinding wilt maken. Stel de Azure Storage-rollen in voor elke identiteit die u in de vorige stap hebt gemaakt: Azure-cloud, lokale ontwikkeling, on-premises.
Nadat u de installatie hebt voltooid, heeft elke identiteit ten minste één van de juiste rollen nodig:
Een rol voor gegevenstoegang , zoals:
- Lezer voor opslagblobgegevens
- Inzender voor Storage Blob-gegevens
Een resourcerol , zoals:
- Lezer
- Inzender
Uw toepassing bouwen
Tijdens het bouwen van uw toepassing werkt uw code voornamelijk met drie typen resources:
- Het opslagaccount, de unieke naamruimte op het hoogste niveau voor uw Azure Storage-gegevens.
- Containers, die de blobgegevens in uw opslagaccount organiseren.
- Blobs, die ongestructureerde gegevens opslaan, zoals tekst en binaire gegevens.
Het volgende diagram geeft de relatie tussen deze resources weer.
Elk type resource wordt vertegenwoordigd door een of meer gekoppelde JavaScript-clients:
Klasse | Omschrijving |
---|---|
BlobServiceClient | Vertegenwoordigt het Blob Storage-eindpunt voor uw opslagaccount. |
ContainerClient | Hiermee kunt u Azure Storage-containers en hun blobs bewerken. |
BlobClient | Hiermee kunt u Azure Storage-blobs bewerken. |
Een BlobServiceClient-object maken
Het BlobServiceClient-object is het bovenste object in de SDK. Met deze client kunt u de service, containers en blobs bewerken.
Zodra uw Azure Storage-account-id-rollen en uw lokale omgeving zijn ingesteld, maakt u een TypeScript-bestand dat het @azure/identity
pakket bevat. Maak een referentie, zoals defaultAzureCredential, om wachtwoordloze verbindingen met Blob Storage te implementeren. Gebruik deze referentie om te verifiëren met een BlobServiceClient-object .
// 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);
}
});
Het dotenv
pakket wordt gebruikt om de naam van uw opslagaccount uit een .env
bestand te lezen. Dit bestand mag niet worden ingecheckt bij broncodebeheer. Als u een lokale service-principal gebruikt als onderdeel van uw DefaultAzureCredential-configuratie, gaan alle beveiligingsgegevens voor die referentie ook naar het .env
bestand.
Als u van plan bent om de toepassing te implementeren op servers en clients die buiten Azure worden uitgevoerd, maakt u een van de referenties die aan uw behoeften voldoen.
Een ContainerClient-object maken
U kunt het ContainerClient-object maken vanuit de BlobServiceClient of rechtstreeks.
ContainerClient-object maken vanuit BlobServiceClient
Maak het ContainerClient-object op basis van de BlobServiceClient.
// Azure Storage dependency
import {
BlobServiceClient,
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 = new StorageSharedKeyCredential(
accountName,
accountKey
);
const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
// Create BlobServiceClient
const blobServiceClient = new BlobServiceClient(
`${baseUrl}`,
sharedKeyCredential
);
async function main(): Promise<void> {
try {
// Create container client
const containerClient = await blobServiceClient.getContainerClient(
containerName
);
// 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);
}
});
ContainerClient rechtstreeks maken
// 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);
}
});
Het dotenv
pakket wordt gebruikt om de naam van uw opslagaccount uit een .env
bestand te lezen. Dit bestand mag niet worden ingecheckt bij broncodebeheer.
Een BlobClient-object maken
U kunt een van de Onderstaande BlobClient-objecten maken, hetzij vanuit een ContainerClient, hetzij rechtstreeks.
Lijst met Blob-clients:
BlobClient-object maken vanuit ContainerClient
// Azure Storage dependency
import {
BlobClient,
BlobDownloadHeaders,
BlobGetPropertiesHeaders,
BlobGetPropertiesResponse,
BlockBlobClient,
ContainerClient
} from '@azure/storage-blob';
// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
import { getContainerClientFromDefaultAzureCredential } from './auth-get-client';
dotenv.config();
const containerName = `my-container`;
const containerClient: ContainerClient =
getContainerClientFromDefaultAzureCredential(containerName);
const blobName = `my-blob`;
async function main(containerClient: ContainerClient): Promise<void> {
// Create BlobClient object
const blobClient: BlobClient = containerClient.getBlobClient(blobName);
// do something with blobClient...
const properties: BlobGetPropertiesHeaders = await blobClient.getProperties();
if (properties.errorCode) throw Error(properties.errorCode);
console.log(`Blob ${blobName} properties:`);
// get BlockBlobClient from blobClient
const blockBlobClient: BlockBlobClient = blobClient.getBlockBlobClient();
// do something with blockBlobClient...
const downloadResponse: BlobDownloadHeaders = await blockBlobClient.download(
0
);
if (downloadResponse.errorCode) throw Error(downloadResponse.errorCode);
}
main(containerClient)
.then(() => console.log(`success`))
.catch((err: unknown) => {
if (err instanceof Error) {
console.log(err.message);
}
});
BlobClient rechtstreeks maken
// 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
}
*/
Het dotenv
pakket wordt gebruikt om de naam van uw opslagaccount uit een .env
bestand te lezen. Dit bestand mag niet worden ingecheckt bij broncodebeheer.