Azure Storage Blob-clientbibliotheek voor JavaScript - versie 12.24.0
Azure Storage Blob is de oplossing voor objectopslag van Microsoft voor de cloud. Blob Storage is geoptimaliseerd voor het opslaan van enorme hoeveelheden ongestructureerde gegevens. Ongestructureerde gegevens zijn gegevens die niet voldoen aan een bepaald gegevensmodel of bepaalde definitie, zoals tekst of binaire gegevens.
Dit project biedt een clientbibliotheek in JavaScript waarmee u eenvoudig Microsoft Azure Storage Blob-service kunt gebruiken.
Gebruik de clientbibliotheken in dit pakket om:
- Eigenschappen van blobservice ophalen/instellen
- Containers maken/weergeven/verwijderen
- Blok-blobs maken/lezen/weergeven/bijwerken/verwijderen
- Pagina-blobs maken/lezen/weergeven/bijwerken/verwijderen
- Toevoeg-blobs maken/lezen/weergeven/bijwerken/verwijderen
Sleutelkoppelingen
- broncode
- package (npm)
- API-referentiedocumentatie
- productdocumentatie
- voorbeelden
- Azure Storage Blob REST API's
Slag
Momenteel ondersteunde omgevingen
- LTS-versies van Node.js
- Nieuwste versies van Safari, Chrome, Edge en Firefox.
Zie ons ondersteuningsbeleid voor meer informatie.
Voorwaarden
- Een Azure-abonnement
- Een -opslagaccount
Het pakket installeren
De voorkeursmethode voor het installeren van de Azure Storage Blob-clientbibliotheek voor JavaScript is het gebruik van npm-pakketbeheer. Typ het volgende in een terminalvenster:
npm install @azure/storage-blob
De client verifiëren
Azure Storage ondersteunt verschillende manieren om te verifiëren. Als u wilt communiceren met de Azure Blob Storage-service, moet u bijvoorbeeld een exemplaar van een Storage-client maken: BlobServiceClient
, ContainerClient
of BlobClient
. Zie voorbeelden voor het maken van de BlobServiceClient
voor meer informatie over verificatie.
- Azure Active Directory-
- gedeelde sleutel
- handtekeningen voor gedeelde toegang
Azure Active Directory
De Azure Blob Storage-service ondersteunt het gebruik van Azure Active Directory voor het verifiëren van aanvragen bij de API's. Het @azure/identity
-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. Raadpleeg de LEESMIJ voor @azure/identity
voor meer informatie en voorbeelden om u op weg te helpen.
Compatibiliteit
Deze bibliotheek is compatibel met Node.js en browsers en gevalideerd op basis van LTS-Node.js versies (>=8.16.0) en de nieuwste versies van Chrome, Firefox en Edge.
Webmedewerkers
Voor deze bibliotheek moeten bepaalde DOM-objecten wereldwijd beschikbaar zijn wanneer ze worden gebruikt in de browser, die webmedewerkers niet standaard beschikbaar maken. U moet deze invullen om deze bibliotheek in webwerkrollen te laten werken.
Raadpleeg onze documentatie voor het gebruik van Azure SDK voor JS in Web Workers voor meer informatie
Deze bibliotheek is afhankelijk van de volgende DOM-API's waarvoor externe polyfills moeten worden geladen wanneer ze worden gebruikt in webwerkrollen:
Verschillen tussen Node.js en browsers
Er zijn verschillen tussen Node.js en runtime van browsers. Wanneer u aan de slag gaat met deze bibliotheek, moet u letten op API's of klassen die zijn gemarkeerd met 'ONLY AVAILABLE IN NODE.JS RUNTIME' of 'ONLY AVAILABLE IN BROWSERS'.
- Als een blob gecomprimeerde gegevens in
gzip
ofdeflate
-indeling bevat en de inhoudscodering dienovereenkomstig is ingesteld, is het downloaden van gedrag anders tussen Node.js en browsers. In Node.js-opslagclients wordt de blob gedownload in de gecomprimeerde indeling, terwijl in browsers de gegevens worden gedownload in de niet-gecomprimeerde indeling.
Functies, interfaces, klassen of functies die alleen beschikbaar zijn in Node.js
- Autorisatie van gedeelde sleutels op basis van accountnaam en accountsleutel
StorageSharedKeyCredential
- Sas-generatie (Shared Access Signature)
generateAccountSASQueryParameters()
generateBlobSASQueryParameters()
- Parallel uploaden en downloaden. Houd er rekening mee dat
BlockBlobClient.uploadData()
beschikbaar is in zowel Node.js als browsers.BlockBlobClient.uploadFile()
BlockBlobClient.uploadStream()
BlobClient.downloadToBuffer()
BlobClient.downloadToFile()
Functies, interfaces, klassen of functies die alleen beschikbaar zijn in browsers
- Parallel uploaden en downloaden
BlockBlobClient.uploadBrowserData()
JavaScript-bundel
Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.
CORS
U moet CORS-regels (Cross-Origin Resource Sharing) instellen regels voor uw opslagaccount als u voor browsers moet ontwikkelen. Ga naar Azure Portal en Azure Storage Explorer, zoek uw opslagaccount, maak nieuwe CORS-regels voor blob/queue/file/table-service(s).
U kunt bijvoorbeeld de volgende CORS-instellingen maken voor foutopsporing. Maar pas de instellingen zorgvuldig aan op basis van uw vereisten in de productieomgeving.
- Toegestane oorsprongen: *
- Toegestane werkwoorden: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
- Toegestane headers: *
- Weergegeven headers: *
- Maximale leeftijd (seconden): 86400
Sleutelbegrippen
Blob Storage is ontworpen voor:
- Afbeeldingen of documenten rechtstreeks aan een browser leveren.
- Bestanden opslaan voor gedistribueerde toegang.
- Video en audio streamen.
- Schrijven naar logboekbestanden.
- Gegevens opslaan voor back-up en herstel, herstel na noodgevallen en archivering.
- Gegevens opslaan voor analyse door een on-premises of door Azure gehoste service.
Blob Storage biedt drie typen resources:
- Het -opslagaccount dat via
BlobServiceClient
wordt gebruikt - Een container in het opslagaccount dat via
ContainerClient
wordt gebruikt - Een blob- in een container die wordt gebruikt via
BlobClient
Voorbeelden
- het pakket importeren
- de blobserviceclient maken
- Een nieuwe container maken
- de containers weergeven
- Een blob maken door gegevens te uploaden
- blobs in een container weergeven
- Een blob downloaden en deze converteren naar een tekenreeks (Node.js)
- een blob downloaden en deze converteren naar een tekenreeks (browsers)
Het pakket importeren
Als u de clients wilt gebruiken, importeert u het pakket in uw bestand:
const AzureStorageBlob = require("@azure/storage-blob");
U kunt ook selectief alleen de typen importeren die u nodig hebt:
const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");
De blobserviceclient maken
De BlobServiceClient
vereist een URL naar de blobservice en een toegangsreferentie. Het accepteert desgewenst ook bepaalde instellingen in de parameter options
.
met DefaultAzureCredential
uit @azure/identity
pakket
Aanbevolen manier om een BlobServiceClient
te instantiëren
Installatie : Naslaginformatie - Toegang tot blobs en wachtrijen autoriseren met Azure Active Directory vanuit een clienttoepassing - /azure/storage/common/storage-auth-aad-app
Een nieuwe AAD-toepassing registreren en machtigingen verlenen voor toegang tot Azure Storage namens de aangemelde gebruiker
- Een nieuwe toepassing registreren in Azure Active Directory (in azure-portal) - /azure/active-directory/develop/quickstart-register-app
- Selecteer
Add a permission
in de sectieAPI permissions
en kiesMicrosoft APIs
. - Kies
Azure Storage
en schakel het selectievakje naastuser_impersonation
in en klik vervolgens opAdd permissions
. Hierdoor heeft de toepassing namens de aangemelde gebruiker toegang tot Azure Storage.
Toegang verlenen tot Azure Blob-gegevens met RBAC in azure Portal
- RBAC-rollen voor blobs en wachtrijen : /azure/storage/common/storage-auth-aad-rbac-portal.
- Ga in azure Portal naar uw opslagaccount en wijs rol Inzender voor opslagblobgegevens toe aan de geregistreerde AAD-toepassing vanaf
Access control (IAM)
tabblad (in de navigatiebalk aan de linkerkant van uw opslagaccount in azure-portal).
Omgeving instellen voor het voorbeeld
- Noteer op de overzichtspagina van uw AAD-toepassing de
CLIENT ID
enTENANT ID
. Maak op het tabblad Certificaten & Geheimen een geheim en noteer dat. - Zorg ervoor dat u AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET als omgevingsvariabelen om het voorbeeld uit te voeren (kan gebruikmaken van process.env).
- Noteer op de overzichtspagina van uw AAD-toepassing de
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
Zie het Azure AD-verificatievoorbeeld voor een volledig voorbeeld met behulp van deze methode.
[Opmerking: bovenstaande stappen zijn alleen bedoeld voor Node.js]
verbindingsreeks gebruiken
U kunt ook een BlobServiceClient
maken met behulp van de statische methode fromConnectionString()
met de volledige verbindingsreeks als argument. (De verbindingsreeks kan worden verkregen via azure Portal.) [ALLEEN BESCHIKBAAR IN NODE.JS RUNTIME]
const { BlobServiceClient } = require("@azure/storage-blob");
const connStr = "<connection string>";
const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);
met StorageSharedKeyCredential
U kunt ook een BlobServiceClient
maken met een StorageSharedKeyCredential
door accountnaam en accountsleutel door te geven als argumenten. (De accountnaam en accountsleutel kunnen worden verkregen via de Azure-portal.) [ALLEEN BESCHIKBAAR IN NODE.JS RUNTIME]
const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");
// 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 sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
sharedKeyCredential
);
met SAS-token
U kunt ook een BlobServiceClient
maken met shared access signatures (SAS). U kunt het SAS-token ophalen uit azure Portal of er een genereren met behulp van generateAccountSASQueryParameters()
.
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);
Een nieuwe container maken
Gebruik BlobServiceClient.getContainerClient()
om een containerclientinstantie op te halen en vervolgens een nieuwe containerresource te maken.
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
// Create a container
const containerName = `newcontainer${new Date().getTime()}`;
const containerClient = blobServiceClient.getContainerClient(containerName);
const createContainerResponse = await containerClient.create();
console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);
}
main();
De containers weergeven
Gebruik BlobServiceClient.listContainers()
functie om de containers te herhalen, met de nieuwe for-await-of
syntaxis:
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
let containers = blobServiceClient.listContainers();
for await (const container of containers) {
console.log(`Container ${i++}: ${container.name}`);
}
}
main();
U kunt ook for-await-of
:
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
let iter = blobServiceClient.listContainers();
let containerItem = await iter.next();
while (!containerItem.done) {
console.log(`Container ${i++}: ${containerItem.value.name}`);
containerItem = await iter.next();
}
}
main();
Daarnaast wordt paginering ook ondersteund voor vermelding via byPage()
:
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
if (response.containerItems) {
for (const container of response.containerItems) {
console.log(`Container ${i++}: ${container.name}`);
}
}
}
}
main();
Zie samples/v12/typescript/src/listContainers.tsvoor een volledig voorbeeld van het herhalen van containers.
Een blob maken door gegevens te uploaden
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const content = "Hello world!";
const blobName = "newblob" + new Date().getTime();
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(`Upload block blob ${blobName} successfully`, uploadBlobResponse.requestId);
}
main();
Blobs in een container weergeven
Vergelijkbaar met het weergeven van containers.
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
let i = 1;
let blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
console.log(`Blob ${i++}: ${blob.name}`);
}
}
main();
Zie samples/v12/typescript/src/listBlobsFlat.tsvoor een volledig voorbeeld van het herhalen van blobs.
Een blob downloaden en converteren naar een tekenreeks (Node.js)
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
const blobName = "<blob name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);
// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
const downloadBlockBlobResponse = await blobClient.download();
const downloaded = (
await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
).toString();
console.log("Downloaded blob content:", downloaded);
// [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);
});
}
}
main();
Download een blob en converteer deze naar een tekenreeks (browsers).
Raadpleeg de sectie JavaScript Bundle voor meer informatie over het gebruik van deze bibliotheek in de browser.
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";
const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);
// Get blob content from position 0 to the end
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blobClient.download();
const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
console.log("Downloaded blob content", downloaded);
// [Browsers 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();
Een volledig voorbeeld van eenvoudige scenario's is op samples/v12/typescript/src/sharedKeyAuth.ts.
Probleemoplossing
Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL
in op info
. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel
aan te roepen in de @azure/logger
:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Volgende stappen
Meer codevoorbeelden:
Bijdragen
Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.
Raadpleeg ook storage-specifieke handleiding voor aanvullende informatie over het instellen van de testomgeving voor opslagbibliotheken.
Azure SDK for JavaScript