Pustaka klien Antrean Azure Storage untuk JavaScript - versi 12.28.1

Azure Storage Queue menyediakan olahpesan cloud antar komponen aplikasi. Dalam merancang aplikasi untuk skala, komponen aplikasi sering dipisahkan, sehingga mereka dapat menskalakan secara independen. Penyimpanan antrean memberikan pesan asinkron untuk komunikasi antar komponen aplikasi, baik yang berjalan di cloud, di desktop, di server lokal, atau di perangkat seluler. Penyimpanan antrean juga mendukung pengelolaan tugas asinkron dan membangun alur kerja proses.

Proyek ini menyediakan pustaka klien di JavaScript yang memudahkan penggunaan layanan Azure Storage Queue.

Gunakan pustaka klien dalam paket ini untuk:

Mendapatkan/Mengatur Properti Layanan Antrean
Membuat/Mendaftarkan/Menghapus Antrean
Kirim/Terima/Intip/Hapus/Perbarui/Hapus Pesan Antrean

Tautan kunci:

Kode sumber
Paket (npm)
Dokumentasi Referensi API
dokumentasi produk
Samples
REST API Antrean Azure Storage

Memulai Langkah Pertama

Lingkungan yang saat ini didukung

versi LTS Node.js
Versi terbaru Safari, Chrome, Edge, dan Firefox.

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prerequisites

Menginstal paket

Cara yang disukai untuk menginstal pustaka klien Azure Storage Queue untuk JavaScript adalah dengan menggunakan manajer paket npm. Ketik berikut ini ke dalam jendela terminal:

npm install @azure/storage-queue

Mengautentikasi klien

Azure Storage mendukung beberapa cara untuk mengautentikasi. Untuk berinteraksi dengan layanan Azure Queue Storage, Anda harus membuat instans klien Storage - QueueServiceClient atau QueueClient misalnya. Lihat sampel untuk membuat QueueServiceClient untuk mempelajari selengkapnya tentang autentikasi.

Azure Active Directory
Kunci Bersama
Tanda tangan akses bersama

Azure Active Directory

Layanan Azure Queue Storage mendukung penggunaan Azure Active Directory untuk mengautentikasi permintaan ke API-nya. Paket @azure/identity menyediakan berbagai jenis kredensial yang dapat digunakan aplikasi Anda untuk melakukan ini. Silakan lihat README untuk @azure/identity untuk detail dan sampel selengkapnya untuk memulai.

Compatibility

Pustaka ini kompatibel dengan Node.js dan browser, dan divalidasi terhadap versi Node.js LTS (>=8.16.0) dan versi terbaru Chrome, Firefox, dan Edge.

Pekerja Web

Pustaka ini mengharuskan objek DOM tertentu tersedia secara global ketika digunakan di browser, yang tidak tersedia oleh pekerja web secara default. Anda perlu melakukan polifill ini untuk membuat pustaka ini berfungsi di pekerja web.

Untuk informasi selengkapnya, lihat dokumentasi kami untuk menggunakan Azure SDK untuk JS di Pekerja Web

Pustaka ini bergantung pada API DOM berikut yang memerlukan polifill eksternal yang dimuat saat digunakan dalam pekerja web:

Perbedaan antara Node.js dan browser

Ada perbedaan antara runtime Node.js dan browser. Saat memulai pustaka ini, perhatikan API atau kelas yang ditandai dengan "HANYA TERSEDIA DI NODE.JS RUNTIME" atau "HANYA TERSEDIA DI BROWSER".

Fitur, antarmuka, kelas, atau fungsi berikut ini hanya tersedia di Node.js

Otorisasi Kunci Bersama berdasarkan nama akun dan kunci akun
- StorageSharedKeyCredential
Pembuatan Tanda Tangan Akses Bersama (SAS)
- generateAccountSASQueryParameters()
- generateQueueSASQueryParameters()

Bundel JavaScript

Untuk menggunakan pustaka klien ini di browser, pertama-tama Anda perlu menggunakan bunder. Untuk detail tentang cara melakukan ini, silakan lihat dokumentasi bundling kami.

CORS

Anda perlu menyiapkan aturan Berbagi Sumber Daya Lintas Asal (CORS) untuk akun penyimpanan Anda jika Anda perlu mengembangkan browser. Buka portal Microsoft Azure dan Azure Storage Explorer, temukan akun penyimpanan Anda, buat aturan CORS baru untuk layanan blob/antrean/file/tabel.

Misalnya, Anda dapat membuat pengaturan CORS berikut untuk penelusuran kesalahan. Tetapi silakan sesuaikan pengaturan dengan hati-hati sesuai dengan kebutuhan Anda di lingkungan produksi.

Asal yang diizinkan: *
Kata kerja yang diizinkan: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Header yang diizinkan: *
Header yang diekspos: *
Usia maksimum (detik): 86400

Konsep utama

Antrean adalah penyimpanan data dalam akun layanan Azure Storage Queue untuk mengirim/menerima pesan antara klien yang terhubung.

Jenis data utama di pustaka kami yang terkait dengan layanan ini adalah:

A QueueServiceClient mewakili koneksi (melalui URL) ke akun penyimpanan tertentu di layanan Antrean Azure Storage dan menyediakan API untuk memanipulasi antreannya. Ini diautentikasi ke layanan dan dapat digunakan untuk membuat objek QueueClient, serta membuat, menghapus, mencantumkan antrean dari layanan.
A QueueClient mewakili satu antrean di akun penyimpanan. Ini dapat digunakan untuk memanipulasi pesan antrean, misalnya untuk mengirim, menerima, dan mengintip pesan dalam antrean.

Examples

Impor paket

Untuk menggunakan klien, impor paket ke dalam file Anda:

import * as AzureStorageQueue from "@azure/storage-queue";

Atau, secara selektif hanya mengimpor jenis yang Anda butuhkan:

import { QueueServiceClient, StorageSharedKeyCredential } from "@azure/storage-queue";

Membuat klien layanan antrean

QueueServiceClient memerlukan URL ke layanan antrean dan kredensial akses. Ini juga secara opsional menerima beberapa pengaturan dalam parameter options.

dengan `DefaultAzureCredential` dari paket `@azure/identity`

Cara yang direkomendasikan untuk membuat instans QueueServiceClient

Penyiapan: Referensi - Mengotorisasi akses ke blob dan antrean dengan Azure Active Directory dari aplikasi klien - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

Daftarkan aplikasi AAD baru dan berikan izin untuk mengakses Azure Storage atas nama pengguna yang masuk
- Mendaftarkan aplikasi baru di Azure Active Directory (di azure-portal) - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- Di bagian API permissions, pilih Add a permission dan pilih Microsoft APIs.
- Pilih Azure Storage dan pilih kotak centang di samping user_impersonation lalu klik Add permissions. Ini akan memungkinkan aplikasi untuk mengakses Azure Storage atas nama pengguna yang masuk.
Memberikan akses ke data Antrean Azure Storage dengan RBAC di Portal Microsoft Azure
- Peran RBAC untuk blob dan antrean - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- Di portal microsoft Azure, buka akun penyimpanan Anda dan tetapkan peran Kontributor Data Antrean Penyimpanan ke aplikasi AAD terdaftar dari tab (di bilah navigasi sisi kiri akun penyimpanan Anda di azure-portal).
Penyiapan lingkungan untuk sampel
- Dari halaman gambaran umum Aplikasi AAD Anda, catat CLIENT ID dan TENANT ID. Di tab "Sertifikat & Rahasia", buat rahasia dan catat itu.
- Pastikan Anda memiliki AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET sebagai variabel lingkungan agar berhasil menjalankan sampel (dapat memanfaatkan process.env).

import { DefaultAzureCredential } from "@azure/identity";
import { QueueServiceClient } from "@azure/storage-queue";

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

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

[Catatan - Langkah-langkah di atas hanya untuk Node.js]

menggunakan string koneksi

Atau, Anda dapat membuat instans QueueServiceClient menggunakan metode statis fromConnectionString() dengan string koneksi lengkap sebagai argumen. (String koneksi dapat diperoleh dari portal microsoft Azure.) [HANYA TERSEDIA DALAM RUNTIME NODE.JS]

import { QueueServiceClient } from "@azure/storage-queue";

const connectionString = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

dengan `StorageSharedKeyCredential`

Atau, Anda membuat instance a QueueServiceClient dengan a StorageSharedKeyCredential dengan melewati accountName dan accountKey sebagai argumen. (Nilai nama akun dan kunci akun dapat diperoleh dari portal Microsoft Azure.) [HANYA TERSEDIA DALAM RUNTIME NODE.JS]

import { StorageSharedKeyCredential, QueueServiceClient } from "@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
    userAgentOptions: {
      userAgentPrefix: "BasicSample V10.0.0",
    }, // Customized telemetry string
  },
);

dengan Token SAS

Selain itu, Anda dapat membuat instans QueueServiceClient dengan tanda tangan akses bersama (SAS). Anda bisa mendapatkan token SAS dari Portal Microsoft Azure atau membuatnya menggunakan generateAccountSASQueryParameters().

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

Mencantumkan antrean di akun ini

Gunakan fungsi QueueServiceClient.listQueues() untuk mengurutkan antrean, dengan sintaks for-await-of baru:

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

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

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

Atau tanpa for-await-of:

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

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

let i = 1;
const iterator = queueServiceClient.listQueues();
let { done, value } = await iterator.next();
while (!done) {
  console.log(`Queue${i++}: ${value.name}`);
  ({ done, value } = await iterator.next());
}

Untuk sampel lengkap tentang antrian iterasi, silakan lihat samples/v12/typescript/listQueues.ts.

Membuat antrean baru

Gunakan fungsi QueueServiceClient.getQueueClient() untuk membuat antrean baru.

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

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

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const createQueueResponse = await queueClient.create();
console.log(
  `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`,
);

Mengirim pesan ke antrean

Gunakan sendMessage() untuk menambahkan pesan ke antrean:

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

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

const queueName = "<valid queue name>";
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}`,
);

Mengintip pesan

QueueClient.peekMessages() memungkinkan melihat satu atau beberapa pesan di depan antrean. Panggilan ini tidak mencegah kode lain mengakses pesan yang diintip.

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

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

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const peekMessagesResponse = await queueClient.peekMessages();
console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);

Memproses pesan

Pesan diproses dalam dua langkah.

Panggilan pertama queueClient.receiveMessages(). Ini membuat pesan tidak terlihat oleh pesan pembacaan kode lain dari antrean ini untuk periode default 30 detik.
Saat pemrosesan pesan selesai, panggil queueClient.deleteMessage() dengan popReceiptpesan .

Jika kode Anda gagal memproses pesan karena kegagalan perangkat keras atau perangkat lunak, proses dua langkah ini memastikan bahwa instans lain dari kode Anda bisa mendapatkan pesan yang sama dan mencoba lagi.

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

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

const queueName = "<valid queue name>";
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}`,
  );
}

Menghapus antrean

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

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

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const deleteQueueResponse = await queueClient.delete();
console.log(
  `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`,
);

Contoh lengkap skenario sederhana QueueServiceClient ada di samples/v12/typescript/src/queueClient.ts.

Troubleshooting

Mengaktifkan pengelogan dapat membantu mengungkap informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Langkah selanjutnya

Sampel kode lainnya

Sampel Penyimpanan Antrean
Kasus Pengujian Penyimpanan Antrean

Contributing

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Lihat juga panduan khusus Storage untuk informasi tambahan tentang menyiapkan lingkungan pengujian untuk pustaka penyimpanan.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-17