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

Articolo
11/10/2023

BLOB di Archiviazione di Azure è la soluzione di archiviazione degli 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 seguono una definizione o un modello di dati specifico, ad esempio dati di testo o binari.

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

Usare le librerie client in questo pacchetto per:

Ottenere/impostare 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

Introduzione

Ambienti attualmente supportati

Versioni LTS di Node.js
Ultime versioni di Safari, Chrome, Edge e Firefox.

Per altre informazioni, vedere i criteri di supporto.

Prerequisiti

Una sottoscrizione di Azure
Un account di archiviazione

Installare il pacchetto

Il modo preferito per installare la libreria client blob di Archiviazione di Azure per JavaScript consiste nell'usare 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 , BlobServiceClient, ContainerCliento BlobClient ad esempio. Per altre informazioni sull'autenticazioneBlobServiceClient, vedere esempi per la creazione 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 @azure/identity pacchetto offre un'ampia gamma di tipi di credenziali che l'applicazione può usare per eseguire questa operazione. Per altri dettagli ed esempi, vedere il file LEGGIMI @azure/identity per iniziare.

Compatibilità

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

Web Worker

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 relativa all'uso di Azure SDK per JS in Web Worker

Questa libreria dipende dalle API DOM seguenti che richiedono polifill 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 BROWSER" (DISPONIBILE SOLO NEI BROWSER).

Se un BLOB contiene dati compressi in o deflate in gzip formato 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 della chiave condivisa basata sul nome dell'account e sulla chiave dell'account
- StorageSharedKeyCredential
Generazione di firme di accesso condiviso
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Caricamento e download paralleli. Si noti che è disponibile sia in Node.js che BlockBlobClient.uploadData() 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()

JavaScript Bundle

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle.

CORS

È necessario configurare regole CORS (Cross-Origin Resource Sharing) per l'account di archiviazione se è necessario sviluppare per i browser. Passare a 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 alle esigenze 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:

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

L’archiviazione BLOB offre tre tipi di risorse:

L'account di archiviazione usato tramiteBlobServiceClient
Contenitore nell'account di archiviazione usato tramiteContainerClient
BLOB in un contenitore usato tramiteBlobClient

Esempio

Importare il pacchetto
Creare il client del servizio BLOB
Crea 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:

const AzureStorageBlob = require("@azure/storage-blob");

In alternativa, importare selettivamente solo i tipi necessari:

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

Creare il client del servizio BLOB

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

con `DefaultAzureCredential` da `@azure/identity` pacchetto

Modo consigliato per creare un'istanza di BlobServiceClient

Installazione: riferimento - Autorizzare l'accesso a BLOB e code con Azure Active Directory da un'applicazione client - /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(in azure-portal) - /azure/active-directory/develop/quickstart-register-app
- API permissions Nella sezione 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 controllo degli accessi in base al ruolo per BLOB e code - /azure/storage/common/storage-auth-aad-rbac-portal.
- Nel portale di Azure passare all'account di archiviazione e assegnare il ruolo Collaboratore ai dati del BLOB di archiviazione all'applicazione AAD registrata dalla Access control (IAM) scheda (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 di CLIENT ID e TENANT ID. Nella scheda "Certificates & Secrets" (Certificati & segreti) creare un segreto e annotare tale segreto.
- 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).

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

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

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

uso di stringa di connessione

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

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

Con `StorageSharedKeyCredential`

In alternativa, si crea un'istanza di con un BlobServiceClientStorageSharedKeyCredential oggetto passando account-name e account-key come argomenti. È possibile ottenere il nome dell'account e la chiave dell'account dal portale di Azure. [DISPONIBILE SOLO 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
);

con token di firma di accesso condiviso

È anche possibile creare un'istanza BlobServiceClient di con firme di accesso condiviso. È possibile ottenere il token di firma di accesso condiviso dal portale di Azure o generarne uno usando 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}`);

Crea un nuovo contenitore

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

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

Elencare i contenitori

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

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

In alternativa, senza usare 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();

Inoltre, la paginazione è supportata anche per l'inserzione tramite 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();

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

Creare un BLOB caricando i dati

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

Elencare i BLOB all'interno di un contenitore

Simile all'elenco dei contenitori.

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

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)

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

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

Per altre informazioni sull'uso di questa libreria nel browser, vedere la sezione Bundle JavaScript .

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

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

Risoluzione dei problemi

L'abilitazione della registrazione consente di 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 in @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Passaggi successivi

Altri esempi di codice:

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi 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 dell'archiviazione.

Impression

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

Introduzione

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto

Autenticare il client

Azure Active Directory

Compatibilità

Web Worker

Differenze tra Node.js e browser

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

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

JavaScript Bundle

CORS

Concetti chiave

Esempio

Importare il pacchetto

Creare il client del servizio BLOB

con `DefaultAzureCredential` da `@azure/identity` pacchetto

uso di stringa di connessione

Con `StorageSharedKeyCredential`

con token di firma di accesso condiviso

Crea 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).

Risoluzione dei problemi

Passaggi successivi

Contributo

Commenti e suggerimenti

Risorse aggiuntive

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

Introduzione

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto

Autenticare il client

Azure Active Directory

Compatibilità

Web Worker

Differenze tra Node.js e browser

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

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

JavaScript Bundle

CORS

Concetti chiave

Esempio

Importare il pacchetto

Creare il client del servizio BLOB

con DefaultAzureCredential da @azure/identity pacchetto

uso di stringa di connessione

Con StorageSharedKeyCredential

con token di firma di accesso condiviso

Crea 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).

Risoluzione dei problemi

Passaggi successivi

Contributo

Commenti e suggerimenti

Risorse aggiuntive

con `DefaultAzureCredential` da `@azure/identity` pacchetto

Con `StorageSharedKeyCredential`