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

  • Articolo

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:

  • Get/Set Blob Service Properties
  • 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

Introduttiva

Ambienti attualmente supportati

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

  • 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.

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.

Compatibilità

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.

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

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 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 usato tramite BlobServiceClient
  • Un contenitore nell'account di archiviazione usato tramite
  • Un BLOB in un contenitore usato tramite BlobClient

Esempi

Importare il pacchetto

Per usare i client, importare il pacchetto nel file:

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

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

const { BlobServiceClient, StorageSharedKeyCredential } = require("@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

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
    • 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 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 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).
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 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]

const { BlobServiceClient } = require("@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]

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

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

Creare 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() funzione per scorrere i contenitori, con la nuova sintassi di 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 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, l'impaginazione è 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 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:

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

setLogLevel("info");

Passaggi successivi

Altri esempi di codice:

Contribuire

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.

impressioni