Libreria client BLOB di Archiviazione di Azure per JavaScript - versione 12.29.1

BLOB di Archiviazione di Azure è la soluzione di archiviazione oggetti di Microsoft per il cloud. L'archiviazione BLOB è ottimizzata per l'archiviazione di grandi quantità di dati non strutturati. I dati non strutturati sono dati che non rispettano un particolare modello di dati o una definizione, ad esempio dati di testo o binari.

Questo progetto fornisce una libreria client in JavaScript che semplifica l'uso del servizio BLOB di Archiviazione di Microsoft Azure.

Usare le librerie client in questo pacchetto per:

Ottieni/Imposta le proprietà del servizio BLOB
Creare/Elencare/Eliminare contenitori
Creare/Leggere/Elencare/Aggiornare/Eliminare BLOB in blocchi
Creare/leggere/elencare/aggiornare/eliminare BLOB di pagine
Creare/leggere/elencare/aggiornare/eliminare BLOB di accodamento

Collegamenti chiave

Come iniziare

Ambienti attualmente supportati

versioni LTS di Node.js
Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per ulteriori dettagli, consulta la nostra politica di supporto .

Prerequisites

Una sottoscrizione di Azure
Un account di archiviazione

Installare il pacchetto

Il modo migliore per installare la libreria client blob di Archiviazione di Azure per JavaScript consiste nell'usare la gestione pacchetti npm. Digitare quanto segue in una finestra del terminale:

npm install @azure/storage-blob

Autenticare il client

Archiviazione di Azure supporta diversi modi per eseguire l'autenticazione. Per interagire con il servizio archiviazione BLOB di Azure, è necessario creare un'istanza di un client di archiviazione, ad esempio BlobServiceClient, ContainerCliento BlobClient. Per altre informazioni sull'autenticazione, vedere esempi per la creazione del BlobServiceClient.

di Azure Active Directory
Chiave condivisa
firme di accesso condiviso

Azure Active Directory

Il servizio Archiviazione BLOB di Azure supporta l'uso di Azure Active Directory per autenticare le richieste alle API. Il pacchetto @azure/identity offre diversi tipi di credenziali che l'applicazione può usare per eseguire questa operazione. Per altre informazioni e esempi, vedere README per @azure/identity.

Compatibility

Questa libreria è compatibile con Node.js e browser e convalidati rispetto alle versioni Node.js LTS (>=8.16.0) e versioni più recenti di Chrome, Firefox e Edge.

Lavoratori del Web

Questa libreria richiede che determinati oggetti DOM siano disponibili a livello globale quando vengono usati nel browser, che i web worker non rendono disponibili per impostazione predefinita. Sarà necessario eseguire il polyfill per rendere questa libreria funzionante nei web worker.

Per altre informazioni, vedere la documentazione di per l'uso di Azure SDK per JS in Web Worker

Questa libreria dipende dalle API DOM seguenti che richiedono polyfill esterni caricati quando vengono usati nei web worker:

Differenze tra Node.js e browser

Esistono differenze tra Node.js e il runtime dei browser. Quando si inizia a usare questa libreria, prestare attenzione alle API o alle classi contrassegnate con "ONLY AVAILABLE IN NODE.JS RUNTIME" o "ONLY AVAILABLE IN BROWSERS".

Se un BLOB contiene dati compressi in formato gzip o deflate e la relativa codifica del contenuto viene impostata di conseguenza, il comportamento di download è diverso tra Node.js e browser. In Node.js client di archiviazione scaricherà il BLOB nel formato compresso, mentre nei browser i dati verranno scaricati in formato decompresso.

Funzionalità, interfacce, classi o funzioni disponibili solo in Node.js

Autorizzazione chiave condivisa basata sul nome dell'account e sulla chiave dell'account
- StorageSharedKeyCredential
Generazione della firma di accesso condiviso
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Caricamento e download paralleli. Si noti che BlockBlobClient.uploadData() è disponibile sia in Node.js che nei browser.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Funzionalità, interfacce, classi o funzioni disponibili solo nei browser

Caricamento e download paralleli
- BlockBlobClient.uploadBrowserData()

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per i dettagli su come eseguire questa operazione, consulta la nostra documentazione sui raggruppamenti.

CORS

È necessario configurare regole cors (Cross-Origin Resource Sharing) per l'account di archiviazione se è necessario sviluppare per i browser. Passare al portale di Azure e Azure Storage Explorer, trovare l'account di archiviazione, creare nuove regole CORS per i servizi BLOB/queue/file/table.

Ad esempio, è possibile creare le impostazioni CORS seguenti per il debug. Ma personalizzare attentamente le impostazioni in base ai requisiti nell'ambiente di produzione.

Origini consentite: *
Verbi consentiti: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Intestazioni consentite: *
Intestazioni esposte: *
Età massima (secondi): 86400

Concetti chiave

L'archiviazione BLOB è progettata per:

Gestire immagini o documenti direttamente in un browser.
Archiviazione di file per l'accesso distribuito.
Streaming di video e audio.
Scrittura nei file di log.
Archiviazione dei dati per il backup e il ripristino, il ripristino di emergenza e l'archiviazione.
Archiviazione dei dati per l'analisi da parte di un servizio locale o ospitato in Azure.

L'archiviazione BLOB offre tre tipi di risorse:

L'account di archiviazione utilizzato tramiteBlobServiceClient
Un contenitore nell'account di archiviazione usato tramite ContainerClient
Un BLOB in un contenitore usato tramite BlobClient

Examples

Importare il pacchetto
Creare il client del servizio BLOB
Creare un nuovo contenitore
Elencare i contenitori
Creare un BLOB caricando i dati
elencare i BLOB all'interno di un contenitore
Scaricare un BLOB e convertirlo in una stringa (Node.js)
Scaricare un BLOB e convertirlo in una stringa (Browser)

Importare il pacchetto

Per usare i client, importare il pacchetto nel file:

import * as AzureStorageBlob from "@azure/storage-blob";

In alternativa, importare in modo selettivo solo i tipi necessari:

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

Creare il client del servizio BLOB

Il BlobServiceClient richiede un URL per il servizio BLOB e una credenziale di accesso. Facoltativamente accetta anche alcune impostazioni nel parametro options.

con `DefaultAzureCredential` dal pacchetto di `@azure/identity`

modo consigliato per creare un'istanza di un BlobServiceClient

Configurazione: Riferimento - Autorizzare l'accesso a BLOB e code con Azure Active Directory da un'applicazione client - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

Registrare una nuova applicazione AAD e concedere le autorizzazioni per accedere ad Archiviazione di Azure per conto dell'utente connesso
- Registrare una nuova applicazione in Azure Active Directory (nel portale azure) - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- Nella sezione API permissions selezionare Add a permission e scegliere Microsoft APIs.
- Selezionare Azure Storage e selezionare la casella di controllo accanto a user_impersonation e quindi fare clic su Add permissions. In questo modo l'applicazione può accedere ad Archiviazione di Azure per conto dell'utente connesso.
Concedere l'accesso ai dati BLOB di Azure con il controllo degli accessi in base al ruolo nel portale di Azure
- Ruoli RBAC per BLOB e code - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- Nel portale di Azure passare all'account di archiviazione e assegnare ruolo Collaboratore ai dati dei BLOB di archiviazione all'applicazione AAD registrata dalla scheda Access control (IAM) (nella barra di spostamento sul lato sinistro dell'account di archiviazione nel portale di Azure).
Configurazione dell'ambiente per l'esempio
- Nella pagina di panoramica dell'applicazione AAD prendere nota dei CLIENT ID e TENANT ID. Nella scheda "Certificati & segreti" creare un segreto e notare che è inattivo.
- Assicurarsi di avere AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET come variabili di ambiente per eseguire correttamente l'esempio(Può sfruttare process.env).

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@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,
);

Per un esempio completo con questo metodo, vedere esempio di autenticazione di Azure AD.

[Nota : i passaggi precedenti sono solo per Node.js]

uso della stringa di connessione

In alternativa, è possibile creare un'istanza di un BlobServiceClient usando il metodo statico fromConnectionString() con la stringa di connessione completa come argomento. La stringa di connessione può essere ottenuta dal portale di Azure. [DISPONIBILE SOLO IN NODE.JS RUNTIME]

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

con `StorageSharedKeyCredential`

In alternativa, si crea un'istanza di un BlobServiceClient con un StorageSharedKeyCredential passando il nome dell'account e la chiave dell'account come argomenti. È possibile ottenere il nome dell'account e la chiave dell'account dal portale di Azure. [DISPONIBILE SOLO IN NODE.JS RUNTIME]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

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

con token di firma di accesso condiviso

È anche possibile creare un'istanza di un BlobServiceClient con firme di accesso condiviso. È possibile ottenere il token di firma di accesso condiviso dal portale di Azure o generarne uno usando generateAccountSASQueryParameters().

import { BlobServiceClient } from "@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}`);

Creare un nuovo contenitore

Usare BlobServiceClient.getContainerClient() per ottenere un'istanza client del contenitore e quindi creare una nuova risorsa contenitore.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

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

Elencare i contenitori

Usare BlobServiceClient.listContainers() funzione per scorrere i contenitori, con la nuova sintassi di for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
  console.log(`Container ${i++}: ${container.name}`);
}

In alternativa, senza usare for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iter = blobServiceClient.listContainers();
let { value, done } = await iter.next();
while (!done) {
  console.log(`Container ${i++}: ${value.name}`);
  ({ value, done } = await iter.next());
}

Inoltre, l'impaginazione è supportata anche per l'inserzione tramite byPage():

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const page of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  for (const container of page.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

Per un esempio completo sui contenitori di iterazione, vedere samples/v12/typescript/src/listContainers.ts.

Creare un BLOB caricando i dati

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

const content = "Hello world!";
const blobName = `newblob ${+new Date()}`;
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(
  `Upload block blob ${blobName} successfully with request ID: ${uploadBlobResponse.requestId}`,
);

Elencare i BLOB all'interno di un contenitore

Simile all'elenco dei contenitori.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

Per un esempio completo sull'iterazione dei BLOB, vedere samples/v12/typescript/src/listBlobsFlat.ts.

Scaricare un BLOB e convertirlo in una stringa (Node.js)

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
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();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

Scaricare un BLOB e convertirlo in una stringa (Browser).

Per ulteriori informazioni sull'utilizzo di questa libreria nel browser, consulta la sezione Bundle JavaScript .

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
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 blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

Un esempio completo di scenari semplici è disponibile all'indirizzo samples/v12/typescript/src/sharedKeyAuth.ts.

Troubleshooting

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Passaggi successivi

Altri esempi di codice:

esempi di archiviazione BLOB (JavaScript)
esempi di archiviazione BLOB (TypeScript)
test case di archiviazione BLOB

Contributing

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

Per altre informazioni sulla configurazione dell'ambiente di test per le librerie di archiviazione, vedere anche guida specifica all'archiviazione.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-17