Aracılığıyla paylaş

JavaScript için Azure Depolama Kuyruğu istemci kitaplığı - sürüm 12.28.1

Azure Depolama Kuyruğu, uygulama bileşenleri arasında bulut mesajlaşması sağlar. Ölçek için uygulama tasarımında, uygulama bileşenleri genellikle birbirinden ayrılır, böylece bağımsız olarak ölçeklendirilebilirler. Kuyruk depolama, bulutta, masaüstünde, şirket içi sunucuda veya mobil cihazda çalışan uygulama bileşenleri arasındaki iletişim için zaman uyumsuz mesajlaşma sunar. Kuyruk depolama, zaman uyumsuz görevleri yönetmeyi ve süreç iş akışları oluşturmayı da destekler.

Bu proje, JavaScript'te Azure Depolama Kuyruğu hizmetini tüketmeyi kolaylaştıran bir istemci kitaplığı sağlar.

Aşağıdakiler için bu paketteki istemci kitaplıklarını kullanın:

  • Kuyruk Hizmeti Özelliklerini Alma/Ayarlama
  • Kuyruk Oluştur/Listele/Sil
  • Kuyruk İletilerini Gönderme/Alma/Göz Atma/Temizleme/Güncelleştirme/Silme

Önemli bağlantılar:

Başlangıç Yapmak

Şu anda desteklenen ortamlar

Daha fazla ayrıntı için destek politikamıza bakın.

Prerequisites

Paketi yükleme

JavaScript için Azure Depolama Kuyruğu istemci kitaplığını yüklemenin tercih edilen yolu npm paket yöneticisini kullanmaktır. Terminal penceresine aşağıdakileri yazın:

npm install @azure/storage-queue

İstemcinin kimliğini doğrulama

Azure Depolama, kimlik doğrulaması için çeşitli yolları destekler. Azure Kuyruk Depolama hizmetiyle etkileşim kurmak için bir Depolama istemcisi örneği oluşturmanız gerekir; örneğin QueueServiceClient veya QueueClient. Kimlik doğrulaması hakkında daha fazla bilgi edinmek için bkz. oluşturmak için örnekleri.

Azure Active Directory

Azure Kuyruk Depolama hizmeti, API'lerine yönelik isteklerin kimliğini doğrulamak için Azure Active Directory kullanımını destekler. @azure/identity paketi, uygulamanızın bunu yapmak için kullanabileceği çeşitli kimlik bilgisi türleri sağlar. Başlamanıza yönelik diğer ayrıntılar ve örnekler için lütfen BENIOKU bölümüne bakın.

Compatibility

Bu kitaplık Node.js ve tarayıcılarla uyumludur ve LTS Node.js sürümlerine (>=8.16.0) ve Chrome, Firefox ve Edge'in en son sürümlerine göre doğrulanır.

Web Çalışanları

Bu kitaplık, belirli DOM nesnelerinin tarayıcıda kullanıldığında genel olarak kullanılabilir olmasını gerektirir ve bu, web çalışanlarının varsayılan olarak kullanılabilir hale getirmez. Bu kitaplığın web çalışanlarında çalışması için bunları çok doldurmanız gerekir.

Daha fazla bilgi için lütfen Web Çalışanları JS için Azure SDK'sını kullanmaya yönelik belgelerimize bakın

Bu kitaplık, web çalışanlarında kullanıldığında dış çok dolguların yüklenmesi gereken aşağıdaki DOM API'lerine bağlıdır:

Node.js ve tarayıcılar arasındaki farklar

Node.js ve tarayıcı çalışma zamanı arasında farklar vardır. Bu kitaplığı kullanmaya başlarken, veya "YALNIZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR" ile işaretlenmiş API'lere veya sınıflara dikkat edin.

Aşağıdaki özellikler, arabirimler, sınıflar veya işlevler yalnızca Node.js
  • Hesap adına ve hesap anahtarına göre Paylaşılan Anahtar Yetkilendirmesi
    • StorageSharedKeyCredential
  • Paylaşılan Erişim İmzası (SAS) oluşturma
    • generateAccountSASQueryParameters()
    • generateQueueSASQueryParameters()

JavaScript Paketi

Bu istemci kitaplığını tarayıcıda kullanmak için önce bir paketleyici kullanmanız gerekir. Bunun nasıl yapılacağıyla ilgili ayrıntılar için lütfen paketleme belgelerimize bakın.

CORS

Tarayıcılar için geliştirmeniz gerekiyorsa depolama hesabınız için Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) kuralları ayarlamanız gerekir. Azure portalına ve Azure Depolama Gezgini'ne gidin, depolama hesabınızı bulun, blob/kuyruk/dosya/tablo hizmetleri için yeni CORS kuralları oluşturun.

Örneğin, hata ayıklama için aşağıdaki CORS ayarlarını oluşturabilirsiniz. Ancak lütfen üretim ortamındaki gereksinimlerinize göre ayarları dikkatli bir şekilde özelleştirin.

  • İzin verilen çıkış noktaları: *
  • İzin verilen fiiller: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • İzin verilen üst bilgiler: *
  • Kullanıma sunulan üst bilgiler: *
  • Maksimum yaş (saniye): 86400

Temel kavramlar

Kuyruk, bağlı istemciler arasında ileti göndermeye/almaya yönelik bir Azure Depolama Kuyruğu hizmet hesabı içindeki bir veri deposudur.

Kitaplığımızda bu hizmetlerle ilgili temel veri türleri şunlardır:

  • A, QueueServiceClient Azure Depolama Kuyruğu hizmetindeki belirli bir depolama hesabına bağlantıyı (URL aracılığıyla) temsil eder ve kuyruklarını işlemek için API'ler sağlar. Hizmette kimliği doğrulanır ve QueueClient nesneleri oluşturmak ve hizmetten kuyrukları oluşturmak, silmek, listelemek için kullanılabilir.
  • A, QueueClient depolama hesabındaki tek bir kuyruğu temsil eder. Kuyruktaki iletileri göndermek, almak ve kuyruğa göz atmak gibi kuyruk iletilerini işlemek için kullanılabilir.

Examples

Paketi içeri aktarma

İstemcileri kullanmak için paketi dosyanıza aktarın:

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

Alternatif olarak, yalnızca ihtiyacınız olan türleri seçmeli olarak içeri aktarın:

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

Kuyruk hizmeti istemcisini oluşturma

QueueServiceClient, kuyruk hizmetinin URL'sini ve erişim kimlik bilgilerini gerektirir. ayrıca isteğe bağlı olarak options parametresindeki bazı ayarları kabul eder.

DefaultAzureCredential paketinden @azure/identity

bir QueueServiceClient örneği oluşturmanın önerilen yolu

Kurulum : Referans - Bir istemci uygulamasından Azure Active Directory ile bloblara ve kuyruklara erişimi yetkilendirme - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

  • Yeni bir AAD uygulaması kaydedin ve oturum açan kullanıcı adına Azure Depolama'ya erişim izinleri verin

    • Azure Active Directory'ye (azure-portal'da) yeni bir uygulama kaydedin - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
    • API permissions bölümünde Add a permission ve Microsoft APIsseçin.
    • Azure Storage seçin, user_impersonation yanındaki onay kutusunu seçin ve ardından Add permissionsöğesine tıklayın. Bu, uygulamanın oturum açmış kullanıcı adına Azure Depolama'ya erişmesine olanak tanır.

  • Azure Portal'da RBAC ile Azure Depolama Kuyruğu verilerine erişim izni verme

  • Örnek için ortam kurulumu

    • AAD Uygulamanızın genel bakış sayfasında CLIENT ID ve TENANT IDnot edin. "Sertifikalar & Gizli Diziler" sekmesinde bir gizli dizi oluşturun ve bunu not edin.
    • Örneği başarıyla yürütmek için ortam değişkenleri olarak AZURE_TENANT_ID, AZURE_CLIENT_IDAZURE_CLIENT_SECRET sahip olduğunuzdan emin olun (process.env'yi kullanabilir).
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,
);

[Not - Yukarıdaki adımlar yalnızca Node.jsiçindir]

bağlantı dizesini kullanma

Alternatif olarak, bağımsız değişken olarak tam bağlantı dizesiyle QueueServiceClient statik yöntemini kullanarak bir fromConnectionString() örneği oluşturabilirsiniz. (Bağlantı dizesi azure portalından alınabilir.) [YALNıZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR]

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

const connectionString = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

StorageSharedKeyCredential ile

Alternatif olarak, a ile a QueueServiceClientStorageSharedKeyCredential 'yi geçerek accountName ve accountKey bağımsız değişkenler olarak örnekleyebilirsiniz. (Hesap adı ve hesap anahtarı değerleri Azure portal alınabilir.) [YALNIZCA NODE.JS ÇALIŞMA ZAMANINDA KULLANILABILIR]

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

SAS Belirteci ile

Ayrıca, paylaşılan erişim imzalarıyla (SAS) bir QueueServiceClient örneği oluşturabilirsiniz. SAS belirtecini Azure Portal'dan alabilir veya generateAccountSASQueryParameters()kullanarak oluşturabilirsiniz.

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

Bu hesaptaki kuyrukları listele

Yeni QueueServiceClient.listQueues() söz dizimi ile kuyrukları yinelemek için for-await-of işlevini kullanın:

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

Alternatif olarak for-await-ofolmadan:

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

Kuyrukları yineleme hakkında eksiksiz bir örnek için lütfen samples/v12/typescript/listQueues.ts adresine bakın.

Yeni kuyruk oluşturma

Yeni bir kuyruk oluşturmak için QueueServiceClient.getQueueClient() işlevini kullanın.

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

Kuyruğa ileti gönderme

Kuyruğa ileti eklemek için sendMessage() kullanın:

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

İletiye göz atma

QueueClient.peekMessages(), kuyruğun önündeki bir veya daha fazla iletiye bakmanızı sağlar. Bu çağrı, diğer kodların göz atılan iletilere erişmesini engellemez.

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

İletiyi işleme

İletiler iki adımda işlenir.

  • İlk çağrı queueClient.receiveMessages(). Bu, iletilerin 30 saniyelik varsayılan bir süre boyunca bu kuyruktan gelen iletileri okuyan diğer kodlar için görünmez olmasını sağlar.
  • bir iletinin işlenmesi tamamlandığında, iletinin queueClient.deleteMessage()ile popReceipt çağırın.

Kodunuz donanım veya yazılım hatası nedeniyle bir iletiyi işleyemezse, bu iki adımlı işlem kodunuzun başka bir örneğinin aynı iletiyi alıp yeniden denemesini sağlar.

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

Kuyruk silme

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

Basit QueueServiceClient senaryoların tam bir örneği samples/v12/typescript/src/queueClient.ts adresindedir.

Troubleshooting

Günlüğe kaydetmeyi etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, setLogLevel@azure/logger çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

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

setLogLevel("info");

Sonraki Adımlar

Diğer kod örnekleri

Contributing

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

Ayrıca, depolama kitaplıkları için test ortamını ayarlama hakkında ek bilgi için Depolama'ya özgü kılavuz bakın.

  • Last updated on