Aracılığıyla paylaş

Python için Azure Depolama Kuyrukları istemci kitaplığı - sürüm 12.9.0

  • Makale

Azure Kuyruk depolama, HTTP veya HTTPS kullanan kimlik doğrulaması yapılmış çağrılar aracılığıyla dünyanın her yerinden erişilebilen çok sayıda iletinin depolanması için bir hizmettir. Tek bir kuyruk iletisinin boyutu en fazla 64 KiB olabilir ve bir kuyruk, depolama hesabının toplam kapasite sınırına kadar milyonlarca ileti içerebilir.

Kuyruk depolamanın yaygın kullanımları şunlardır:

  • Zaman uyumsuz olarak işlemek için kapsamı oluşturma
  • Dağıtılmış uygulamanın farklı bölümleri arasında ileti geçirme

Kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Başlarken

Önkoşullar

Paketi yükleme

Python için Azure Depolama Kuyrukları istemci kitaplığını pip ile yükleyin:

pip install azure-storage-queue

Depolama hesabı oluşturma

Yeni bir depolama hesabı oluşturmak isterseniz Azure Portalı, Azure PowerShell veya Azure CLI'yı kullanabilirsiniz:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

İstemci oluşturma

Python için Azure Depolama Kuyrukları istemci kitaplığı üç tür kaynakla etkileşim kurmanızı sağlar: depolama hesabının kendisi, kuyruklar ve iletiler. Bu kaynaklarla etkileşim bir istemci örneğiyle başlar. İstemci nesnesi oluşturmak için depolama hesabının kuyruk hizmeti uç noktası URL'sine ve depolama hesabına erişmenizi sağlayan bir kimlik bilgilerine ihtiyacınız olacaktır:

from azure.storage.queue import QueueServiceClient

service = QueueServiceClient(account_url="https://<my-storage-account-name>.queue.core.windows.net/", credential=credential)

Hesap URL'sini arama

Azure Portal, Azure PowerShell veya Azure CLI kullanarak depolama hesabının kuyruk hizmeti URL'sini bulabilirsiniz:

# Get the queue service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.queue"

Kimlik bilgisi türleri

Parametre credential , kullanmak istediğiniz yetkilendirme türüne bağlı olarak bir dizi farklı biçimde sağlanabilir:

  1. Paylaşılan erişim imzası (SAS) belirteci kullanmak için belirteci dize olarak sağlayın. Hesap URL'niz SAS belirtecini içeriyorsa kimlik bilgisi parametresini atayın. Azure Portalı'ndan "Paylaşılan erişim imzası" altında bir SAS belirteci oluşturabilir veya işlevlerden generate_sas() birini kullanarak depolama hesabı veya kuyruğu için sas belirteci oluşturabilirsiniz:

    from datetime import datetime, timedelta
from azure.storage.queue import QueueServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    start=datetime.utcnow(),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

queue_service_client = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential=sas_token)

  2. Depolama hesabı paylaşılan anahtarı (diğer adıyla hesap anahtarı veya erişim anahtarı) kullanmak için anahtarı dize olarak sağlayın. Bu, Azure Portal'da "Erişim Anahtarları" bölümünde veya aşağıdaki Azure CLI komutunu çalıştırarak bulunabilir:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    İstemcinin kimliğini doğrulamak için kimlik bilgisi parametresi olarak anahtarını kullanın:

    from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")

  3. Azure Active Directory (AAD) belirteci kimlik bilgilerini kullanmak için azure-identity kitaplığından elde edilen istenen kimlik bilgisi türünün bir örneğini sağlayın. Örneğin, istemcinin kimliğini doğrulamak için DefaultAzureCredential kullanılabilir.

    Bunun için bazı ilk kurulumlar gerekir:

    İstemcinin kimliğini doğrulamak için döndürülen belirteç kimlik bilgilerini kullanın:

        from azure.identity import DefaultAzureCredential
    from azure.storage.queue import QueueServiceClient
    token_credential = DefaultAzureCredential()

    queue_service_client = QueueServiceClient(
        account_url="https://<my_account_name>.queue.core.windows.net",
        credential=token_credential
    )

İstemciyi bir bağlantı dizesi oluşturma

Kullanım örneğinize ve yetkilendirme yönteminize bağlı olarak, hesap URL'sini ve kimlik bilgilerini ayrı olarak sağlamak yerine depolama bağlantı dizesi bir istemci örneği başlatmayı tercih edebilirsiniz. Bunu yapmak için depolama bağlantı dizesi istemcinin from_connection_string sınıf yöntemine geçirin:

from azure.storage.queue import QueueServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = QueueServiceClient.from_connection_string(conn_str=connection_string)

Depolama hesabınıza bağlantı dizesi Azure Portal'da "Erişim Anahtarları" bölümünde veya aşağıdaki CLI komutunu çalıştırarak bulunabilir:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Önemli kavramlar

Aşağıdaki bileşenler Azure Kuyruk Hizmeti'ni oluşturur:

  • Depolama hesabının kendisi
  • Depolama hesabı içinde bir dizi ileti içeren bir kuyruk
  • Kuyruk içinde, herhangi bir biçimde 64 KiB'a kadar bir ileti

Python için Azure Depolama Kuyrukları istemci kitaplığı, ayrılmış bir istemci nesnesi kullanarak bu bileşenlerin her biriyle etkileşim kurmanızı sağlar.

Zaman Uyumsuz İstemciler

Bu kitaplık, Python 3.5+ üzerinde desteklenen tam bir zaman uyumsuz API içerir. Bunu kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Daha fazla bilgi için bkz. azure-core belgeleri .

Zaman uyumsuz istemciler ve kimlik bilgileri artık gerekli olmadığında kapatılmalıdır. Bu nesneler zaman uyumsuz bağlam yöneticileridir ve zaman uyumsuz close yöntemler tanımlar.

İstemciler

Kuyruk Hizmeti'nin çeşitli bileşenleriyle etkileşime geçmek için iki farklı istemci sağlanır:

  1. QueueServiceClient - bu istemci Azure depolama hesabının kendisiyle etkileşimi temsil eder ve içindeki kuyruklara erişmek için önceden yapılandırılmış istemci örnekleri almanıza olanak tanır. Hesap özelliklerini alma ve yapılandırmanın yanı sıra hesap içindeki kuyrukları listeleme, oluşturma ve silme işlemlerini sağlar. Belirli bir kuyrukta işlem gerçekleştirmek için yöntemini kullanarak get_queue_client bir istemci alın.
  2. QueueClient - bu istemci belirli bir kuyrukla etkileşimi temsil eder (henüz mevcut olması gerekmez). Kuyruk oluşturma, silme veya yapılandırma işlemleri sağlar ve içindeki iletileri gönderme, alma, göz atma, silme ve güncelleştirme işlemlerini içerir.

İletiler

  • Gönder - Kuyruğa bir ileti ekler ve isteğe bağlı olarak ileti için görünürlük zaman aşımı ayarlar.
  • Receive - Kuyruktan bir ileti alır ve diğer tüketiciler tarafından görünmez olmasını sağlar.
  • Gözatma - İleti görünürlüğünü değiştirmeden kuyruğun önünden bir ileti alır.
  • Güncelleştirme - bir iletinin ve/veya ileti içeriğinin görünürlük zaman aşımını Güncelleştirmeler.
  • Delete - Belirtilen iletiyi kuyruktan siler.
  • Temizle - Kuyruktan gelen tüm iletileri temizler.

Örnekler

Aşağıdaki bölümlerde, en yaygın Depolama Kuyruğu görevlerinden bazılarını kapsayan çeşitli kod parçacıkları sağlanmaktadır:

Kuyruk oluşturma

Depolama hesabınızda kuyruk oluşturma

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.create_queue()

Kuyruk oluşturmak için zaman uyumsuz istemciyi kullanma

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await queue.create_queue()

İleti gönderme

Kuyruğunuza ileti gönderme

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.send_message("I'm using queues!")
queue.send_message("This is my second message")

İletileri zaman uyumsuz olarak gönderme

import asyncio
from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await asyncio.gather(
    queue.send_message("I'm using queues!"),
    queue.send_message("This is my second message")
)

İleti alma

Kuyruğunuzdan ileti alma ve işleme

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

for message in response:
    print(message.content)
    queue.delete_message(message)

# Printed messages from the front of the queue:
# >> I'm using queues!
# >> This is my second message

İletileri toplu olarak alma ve işleme

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages(messages_per_page=10)

for message_batch in response.by_page():
    for message in message_batch:
        print(message.content)
        queue.delete_message(message)

İletileri zaman uyumsuz olarak alma ve işleme

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

async for message in response:
    print(message.content)
    await queue.delete_message(message)

İsteğe Bağlı Yapılandırma

İstemcide ve işlem düzeyinde geçirilebilen isteğe bağlı anahtar sözcük bağımsız değişkenleri.

İlke yapılandırmasını yeniden deneme

Yeniden deneme ilkesini yapılandırmak için bir istemci örneği oluştururken aşağıdaki anahtar sözcük bağımsız değişkenlerini kullanın:

  • retry_total (int): İzin vermek için toplam yeniden deneme sayısı. Diğer sayılardan önceliklidir. İstekleri retry_total=0 yeniden denemek istemiyorsanız geçiş yapın. Varsayılan değer 10'dır.
  • retry_connect (int): Bağlantıyla ilgili kaç hatanın yeniden denenebileceği. Varsayılan değer 3'tir.
  • retry_read (int): Okuma hatalarında yeniden deneme sayısı. Varsayılan değer 3'tir.
  • retry_status (int): Hatalı durum kodları üzerinde yeniden deneme sayısı. Varsayılan değer 3'tir.
  • retry_to_secondary (bool): mümkünse isteğin ikincil olarak yeniden denenip denenmeyeceği. Bu yalnızca RA-GRS hesaplarının etkinleştirilmesi gerekir ve eski olabilecek veriler işlenebilir. Varsayılan olarak olarak Falsegösterilir.

Diğer istemci /işlem başına yapılandırma

İstemcide veya işlem başına belirtilebilen diğer isteğe bağlı yapılandırma anahtar sözcük bağımsız değişkenleri.

İstemci anahtar sözcük bağımsız değişkenleri:

  • connection_timeout (int): İstemcinin sunucuyla bağlantı kurmak için bekleyeceği saniye sayısı. Varsayılan değer 20 saniyedir.
  • read_timeout (int): İstemcinin sunucudan gelen bir yanıt için ardışık okuma işlemleri arasında bekleyeceği saniye sayısı. Bu bir yuva düzeyi zaman aşımıdır ve genel veri boyutundan etkilenmez. İstemci tarafı okuma zaman aşımları otomatik olarak yeniden denenecek. Varsayılan değer 60 saniyedir.
  • transport (Any): HTTP isteğini göndermek için kullanıcı tarafından sağlanan aktarım.

İşlem başına anahtar sözcük bağımsız değişkenleri:

  • raw_response_hook (çağrılabilir): Verilen geri arama, hizmetten döndürülen yanıtı kullanır.
  • raw_request_hook (çağrılabilir): Verilen geri arama, hizmete gönderilmeden önce isteği kullanır.
  • client_request_id (str): İsteğin kullanıcı tarafından belirtilen isteğe bağlı kimliği.
  • user_agent (str): İstekle birlikte gönderilecek kullanıcı aracısı üst bilgisine özel değeri ekler.
  • logging_enable (bool): HATA AYıKLAMA düzeyinde günlüğe kaydetmeyi etkinleştirir. Varsayılan değer False'tur. Tüm istekler için etkinleştirmek üzere istemci düzeyinde de geçirilebilir.
  • logging_body (bool): İsteğin ve yanıt gövdesinin günlüğe kaydedilmesini sağlar. Varsayılan değer False'tur. Tüm istekler için etkinleştirmek üzere istemci düzeyinde de geçirilebilir.
  • headers (dict): Özel üst bilgileri anahtar, değer çiftleri olarak geçirin. Örneğin. headers={'CustomValue': value}

Sorun giderme

Genel

Depolama Kuyruğu istemcileri Azure Core'da tanımlanan özel durumları tetikler.

Bu liste, atılan özel durumları yakalamak için başvuru için kullanılabilir. Özel durumun belirli hata kodunu almak için özniteliğini error_code kullanın, örneğin. exception.error_code

Günlüğe Kaydetme

Bu kitaplık , günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumları (URL'ler, üst bilgiler vb.) hakkındaki temel bilgiler BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü, bir istemcide şu bağımsız değişkenle logging_enable etkinleştirilebilir:

import sys
import logging
from azure.storage.queue import QueueServiceClient

# Create a logger for the 'azure.storage.queue' SDK
logger = logging.getLogger('azure.storage.queue')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = QueueServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

service_client.get_service_stats(logging_enable=True)

Sonraki adımlar

Daha fazla örnek kod

Kuyruk örneklerimizi kullanmaya başlayın.

SDK'nın GitHub deposunda kullanabileceğiniz çeşitli Depolama Kuyrukları Python SDK örnekleri vardır. Bu örnekler, Depolama Kuyruklarıyla çalışırken yaygın olarak karşılaşılan ek senaryolar için örnek kod sağlar:

Diğer belgeler

Azure Kuyruk depolama hakkında daha kapsamlı belgeler için docs.microsoft.com'da Azure Kuyruk depolama belgelerine bakın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .