Libreria client della coda di archiviazione di Azure per JavaScript - versione 12.25.0

La coda di Archiviazione di Azure fornisce la messaggistica cloud tra i componenti dell'applicazione. Nella progettazione di applicazioni per la scalabilità, i componenti dell'applicazione vengono spesso disaccoppiati, in modo che possano essere ridimensionati in modo indipendente. L'archiviazione code offre messaggi asincroni per la comunicazione tra i componenti dell'applicazione, sia che siano in esecuzione nel cloud, sul desktop, in un server locale o in un dispositivo mobile. L'archiviazione code supporta anche la gestione delle attività asincrone e la creazione di flussi di lavoro dei processi.

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

Usare le librerie client in questo pacchetto per:

• Get/Set Queue Service Properties
• Creare/elencare/eliminare code
• Inviare/ricevere/visualizzare/cancellare/aggiornare/eliminare messaggi di coda

Collegamenti chiave:

• Codice sorgente
• pacchetto (npm)
• documentazione di riferimento dell'API
• documentazione del prodotto
• Esempi
• API REST della coda di archiviazione di Azure

Introduttiva

Ambienti attualmente supportati

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

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 della coda 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-queue

Autenticare il client

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

• Azure Active Directory
• chiave condivisa
• firme di accesso condiviso

Azure Active Directory

Il servizio Archiviazione code 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:

• document
• DOMParser
• Node
• XMLSerializer

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

Le funzionalità, le interfacce, le classi o le funzioni seguenti sono 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()
  • generateQueueSASQueryParameters()

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

Una coda è un archivio dati all'interno di un account del servizio di accodamento di Archiviazione di Azure per l'invio o la ricezione di messaggi tra i client connessi.

I tipi di dati chiave nella libreria correlata a questi servizi sono:

• Un QueueServiceClient rappresenta una connessione (tramite un URL) a un determinato account di archiviazione nel servizio coda di archiviazione di Azure e fornisce api per la modifica delle code. Viene autenticato nel servizio e può essere usato per creare QueueClient oggetti, nonché creare, eliminare, elencare le code dal servizio.
• Un QueueClient rappresenta una singola coda di nell'account di archiviazione. Può essere usato per modificare i messaggi della coda, ad esempio per inviare, ricevere e visualizzare i messaggi nella coda.

Esempi

Importare il pacchetto

Per usare i client, importare il pacchetto nel file:

const AzureStorageQueue = require("@azure/storage-queue");

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

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

Creare il client del servizio code

Il QueueServiceClient richiede un URL per il servizio di accodamento 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 QueueServiceClient

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 della coda di Archiviazione 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 della coda 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 { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

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

uso della stringa di connessione

In alternativa, è possibile creare un'istanza di un QueueServiceClient 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 { QueueServiceClient } = require("@azure/storage-queue");

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

con StorageSharedKeyCredential

In alternativa, si crea un'istanza di un QueueServiceClient 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 { QueueServiceClient, StorageSharedKeyCredential } = require("@azure/storage-queue");

// 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 queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  sharedKeyCredential,
  {
    retryOptions: { maxTries: 4 }, // Retry options
    telemetry: { value: "BasicSample/V11.0.0" } // Customized telemetry string
  }
);

con token di firma di accesso condiviso

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

const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net${sas}`
);

Elencare le code in questo account

Usare QueueServiceClient.listQueues() funzione per scorrere le code, con la nuova sintassi for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

async function main() {
  const iter1 = queueServiceClient.listQueues();
  let i = 1;
  for await (const item of iter1) {
    console.log(`Queue${i}: ${item.name}`);
    i++;
  }
}

main();

In alternativa, senza for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

async function main() {
  const iter2 = queueServiceClient.listQueues();
  let i = 1;
  let item = await iter2.next();
  while (!item.done) {
    console.log(`Queue ${i++}: ${item.value.name}`);
    item = await iter2.next();
  }
}

main();

Per un esempio completo sulla iterazione delle code, vedere samples/v12/typescript/listQueues.ts.

Creare una nuova coda

Usare QueueServiceClient.getQueueClient() funzione per creare una nuova coda.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const createQueueResponse = await queueClient.create();
  console.log(
    `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`
  );
}

main();

Inviare un messaggio alla coda

Usare sendMessage() per aggiungere un messaggio alla coda:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  // Send a message into the queue using the sendMessage method.
  const sendMessageResponse = await queueClient.sendMessage("Hello World!");
  console.log(
    `Sent message successfully, service assigned message Id: ${sendMessageResponse.messageId}, service assigned request Id: ${sendMessageResponse.requestId}`
  );
}

main();

Visualizzare un messaggio

QueueClient.peekMessages() consente di esaminare uno o più messaggi davanti alla coda. Questa chiamata non impedisce ad altri codici di accedere ai messaggi visualizzati.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const peekMessagesResponse = await queueClient.peekMessages();
  console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);
}

main();

Elaborazione di un messaggio

I messaggi vengono elaborati in due passaggi.

• Prima chiamata queueClient.receiveMessages(). Ciò rende i messaggi invisibili ad altri messaggi di lettura da questa coda per un periodo predefinito di 30 secondi.
• Al termine dell'elaborazione di un messaggio, chiamare queueClient.deleteMessage() con il popReceiptdel messaggio .

Se il codice non riesce a elaborare un messaggio a causa di un errore hardware o software, questo processo in due passaggi garantisce che un'altra istanza del codice possa ottenere lo stesso messaggio e riprovare.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const response = await queueClient.receiveMessages();
  if (response.receivedMessageItems.length === 1) {
    const receivedMessageItem = response.receivedMessageItems[0];
    console.log(`Processing & deleting message with content: ${receivedMessageItem.messageText}`);
    const deleteMessageResponse = await queueClient.deleteMessage(
      receivedMessageItem.messageId,
      receivedMessageItem.popReceipt
    );
    console.log(
      `Delete message successfully, service assigned request Id: ${deleteMessageResponse.requestId}`
    );
  }
}

main();

Eliminare una coda

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const deleteQueueResponse = await queueClient.delete();
  console.log(
    `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`
  );
}

main();

Un esempio completo di scenari di QueueServiceClient semplici è disponibile in samples/v12/typescript/src/queueClient.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

• esempi di archiviazione code
• test case di archiviazione code

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.