Rövid útmutató: Azure Queue Storage-ügyfélkódtár Pythonhoz

  • Cikk

Ismerkedés a PythonHoz készült Azure Queue Storage ügyfélkódtárával. Az Azure Queue Storage szolgáltatás nagy mennyiségű üzenet tárolására szolgál későbbi lekéréshez és feldolgozáshoz. Az alábbi lépések végrehajtásával telepítheti a csomagot, és kipróbálhatja az alapműveletek példakódját.

API-referenciadokumentáció Kódtár forráskódcsomagja | (Python-csomagindex)Minták | |

A PythonHoz készült Azure Queue Storage-ügyfélkódtár használatával:

  • Üzenetsor létrehozása
  • Üzenetek hozzáadása üzenetsorhoz
  • Üzenetsor üzeneteibe való betekintés
  • Üzenet frissítése üzenetsorban
  • Az üzenetsor hosszának lekérése
  • Üzenetek fogadása üzenetsorból
  • Üzenetek törlése üzenetsorból
  • Üzenetsor törlése

Előfeltételek

Beállítás

Ez a szakasz végigvezeti egy projekt előkészítésén a Pythonhoz készült Azure Queue Storage-ügyfélkódtár használatához.

A projekt létrehozása

Hozzon létre egy queues-quickstart nevű Python-alkalmazást.

  1. Egy konzolablakban (például parancsmag, PowerShell vagy Bash) hozzon létre egy új könyvtárat a projekthez.

    mkdir queues-quickstart

  2. Váltson az újonnan létrehozott queues-quickstart könyvtárra .

    cd queues-quickstart

A csomagok telepítése

A projektkönyvtárból telepítse a Python-csomaghoz készült Azure Queue Storage-ügyfélkódtárat a pip install parancs használatával. Az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatokhoz az Azure-identitáscsomagra van szükség.

pip install azure-storage-queue azure-identity

Az alkalmazás-keretrendszer beállítása

  1. Új szövegfájl megnyitása a kódszerkesztőben

  2. Utasítások hozzáadása import

  3. A program struktúrájának létrehozása, beleértve az alapvető kivételkezelést is

    A kód a következő:

    import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.queue import QueueServiceClient, QueueClient, QueueMessage, BinaryBase64DecodePolicy, BinaryBase64EncodePolicy

try:
    print("Azure Queue storage - Python quickstart sample")
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

  4. Mentse az új fájlt queues-quickstart.py a queues-quickstart könyvtárban.

Hitelesítés az Azure-ban

A legtöbb Azure-szolgáltatáshoz irányuló alkalmazáskéréseket engedélyezni kell. DefaultAzureCredential Az Azure Identity-ügyfélkódtár által biztosított osztály használata ajánlott módszer az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatok implementálásához a kódban.

Az Azure-szolgáltatásokra irányuló kéréseket közvetlenül jelszóval, kapcsolati sztring vagy más hitelesítő adatokkal is engedélyezheti. Ezt a megközelítést azonban körültekintően kell alkalmazni. A fejlesztőknek szorgalmasnak kell lenniük ahhoz, hogy ezeket a titkos kulcsokat soha ne fedje fel nem biztonságos helyen. Bárki, aki hozzáfér a jelszóhoz vagy titkos kulcshoz, hitelesítheti magát. DefaultAzureCredential továbbfejlesztett felügyeleti és biztonsági előnyöket kínál a fiókkulcson keresztül a jelszó nélküli hitelesítés engedélyezéséhez. Az alábbi példában mindkét lehetőség látható.

DefaultAzureCredential A PythonHoz készült Azure Identity-ügyfélkódtár által biztosított osztály. További információkért DefaultAzureCredentialtekintse meg a DefaultAzureCredential áttekintését. DefaultAzureCredential több hitelesítési módszert támogat, és meghatározza, hogy melyik metódust kell használni futásidőben. Ez a megközelítés lehetővé teszi, hogy az alkalmazás különböző hitelesítési módszereket használjon különböző környezetekben (helyi és éles környezetben) környezetspecifikus kód implementálása nélkül.

Az alkalmazás például helyi fejlesztéskor hitelesítheti a Visual Studio Code bejelentkezési hitelesítő adataival, majd használhat felügyelt identitást az Azure-ban való üzembe helyezés után. Ehhez az áttűnéshez nincs szükség kódmódosításra.

Helyi fejlesztéskor győződjön meg arról, hogy az üzenetsor-adatokat elérő felhasználói fiók rendelkezik a megfelelő engedélyekkel. A várólista adatainak olvasásához és írásához tárolósoradat-közreműködőre lesz szükség. A szerepkör hozzárendeléséhez hozzá kell rendelnie a Felhasználói hozzáférés Rendszergazda istrator szerepkört, vagy egy másik szerepkört, amely tartalmazza a Microsoft.Authorization/roleAssignments/write műveletet. Azure RBAC-szerepköröket rendelhet egy felhasználóhoz az Azure Portal, az Azure CLI vagy az Azure PowerShell használatával. A szerepkör-hozzárendelések elérhető hatóköreiről a hatókör áttekintési oldalán tudhat meg többet.

Ebben a forgatókönyvben engedélyeket rendel hozzá a felhasználói fiókjához, amely a tárfiókra terjed ki, hogy kövesse a minimális jogosultság elvét. Ez a gyakorlat csak a minimálisan szükséges engedélyeket biztosítja a felhasználóknak, és biztonságosabb éles környezeteket hoz létre.

Az alábbi példa a Storage Queue Data Contributor szerepkört rendeli hozzá a felhasználói fiókjához, amely olvasási és írási hozzáférést biztosít a tárfiók üzenetsoradataihoz.

Fontos

A szerepkör-hozzárendelés propagálása a legtöbb esetben egy-két percet vesz igénybe az Azure-ban, de ritkán akár nyolc percet is igénybe vehet. Ha hitelesítési hibákat kap a kód első futtatásakor, várjon néhány percet, és próbálkozzon újra.

  1. Az Azure Portalon keresse meg a tárfiókot a fő keresősávon vagy a bal oldali navigációs sávon.

  2. A tárfiók áttekintési lapján válassza a Hozzáférés-vezérlés (IAM) lehetőséget a bal oldali menüben.

  3. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelések lapot.

  4. Válassza a +Hozzáadás lehetőséget a felső menüből, majd a szerepkör-hozzárendelés hozzáadása lehetőséget az eredményül kapott legördülő menüből.

A screenshot showing how to assign a role.

  1. A keresőmezővel szűrheti az eredményeket a kívánt szerepkörre. Ebben a példában keresse meg a Tárolási várólista adatszolgáltatóját, és válassza ki a megfelelő eredményt, majd válassza a Tovább gombot.

  2. A Hozzáférés hozzárendelése területen válassza a Felhasználó, csoport vagy szolgáltatásnév lehetőséget, majd válassza a + Tagok kijelölése lehetőséget.

  3. A párbeszédpanelen keresse meg a Microsoft Entra-felhasználónevet (általában a user@domain e-mail-címét), majd válassza a Párbeszédpanel alján található Kiválasztás lehetőséget.

  4. Válassza a Véleményezés + hozzárendelés lehetőséget a végső lapra való ugráshoz, majd a folyamat befejezéséhez a Véleményezés + hozzárendelés lehetőséget.

Objektummodell

Az Azure Queue Storage szolgáltatás nagy számú üzenet tárolására szolgál. Az üzenetsor-üzenetek mérete legfeljebb 64 KB lehet. Az üzenetsorok több millió üzenetet tartalmazhatnak, akár a tárfiók teljes kapacitáskorlátját is. Az üzenetsorokat gyakran használják az aszinkron feldolgozáshoz használt teendőlista létrehozásához. A Queue Storage három típusú erőforrást kínál:

  • Tárfiók: Az Azure Storage-hoz való minden hozzáférés egy tárfiókon keresztül történik. További információ a tárfiókokról: Tárfiókok áttekintése
  • Üzenetsor: Az üzenetsorok üzenetek készleteit tartalmazzák. Az összes üzenetnek üzenetsorban kell lennie. Vegye figyelembe, hogy az üzenetsor neve csak kisbetűket tartalmazhat. Az üzenetsorok elnevezésével kapcsolatos információkat lásd: Naming Queues and Metadata (Üzenetsorok és metaadatok elnevezése).
  • Üzenet: Egy legfeljebb 64 KB méretű, tetszőleges méretű üzenet. Egy üzenet legfeljebb 7 napig maradhat az üzenetsorban. A 2017-07-29-es vagy újabb verzió esetén a maximális élettartam bármilyen pozitív szám lehet, vagy -1, amely azt jelzi, hogy az üzenet nem jár le. Ha ez a paraméter nincs megadva, az alapértelmezett élettartam hét nap.

Az alábbi ábra az ezen erőforrások közötti kapcsolatot mutatja be.

Diagram of Queue storage architecture

Az alábbi Python-osztályok használatával kezelheti ezeket az erőforrásokat:

  • QueueServiceClient: Ez QueueServiceClient lehetővé teszi a tárfiók összes üzenetsorának kezelését.
  • QueueClient: Az QueueClient osztály lehetővé teszi az egyes üzenetsorok és azok üzeneteinek kezelését és kezelését.
  • QueueMessage: Az QueueMessage osztály az üzenetsor hívása receive_messages során visszaadott egyes objektumokat jelöli.

Kódpéldák

Ezek a példakódrészletek a következő műveleteket mutatják be a Pythonhoz készült Azure Queue Storage-ügyfélkódtár használatával:

Hozzáférés engedélyezése és ügyfélobjektum létrehozása

Győződjön meg arról, hogy ugyanazzal a Microsoft Entra-fiókkal van hitelesítve, amelyhez a szerepkört hozzárendelte. Hitelesítést az Azure CLI-vel, a Visual Studio Code-tal vagy az Azure PowerShell-lel végezhet.

Jelentkezzen be az Azure-ba az Azure CLI-vel a következő paranccsal:

az login

A hitelesítés után létrehozhat és engedélyezheti az objektumokat QueueClientDefaultAzureCredential a tárfiók üzenetsoradatainak eléréséhez. DefaultAzureCredential automatikusan felderíti és használja az előző lépésben bejelentkezett fiókot.

A használat engedélyezéséhez DefaultAzureCredentialgyőződjön meg arról, hogy hozzáadta az Azure-Identity-csomagot a csomagok telepítésében leírtak szerint. Emellett mindenképpen adja hozzá a következő importálási utasítást a queues-quickstart.py fájlhoz:

from azure.identity import DefaultAzureCredential

Döntse el az üzenetsor nevét, és hozza létre az QueueClient osztály egy példányát engedélyezés DefaultAzureCredential céljából. Ezt az ügyfélobjektumot használjuk a tárfiók üzenetsor-erőforrásának létrehozásához és használatához.

Fontos

Az üzenetsornevek csak kisbetűket, számokat és kötőjeleket tartalmazhatnak, és betűvel vagy számmal kell kezdődniük. A kötőjelek előtt és után csak nem kötőjel karakter állhat. A névnek 3 és 63 karakter közötti hosszúságúnak kell lennie. Az üzenetsorok elnevezésével kapcsolatos további információkért lásd az elnevezési üzenetsorokat és a metaadatokat.

Adja hozzá a következő kódot a try blokkba, és cserélje le a <storage-account-name> helyőrző értékét:

    print("Azure Queue storage - Python quickstart sample")

    # Create a unique name for the queue
    queue_name = "quickstartqueues-" + str(uuid.uuid4())

    account_url = "https://<storageaccountname>.queue.core.windows.net"
    default_credential = DefaultAzureCredential()

    # Create the QueueClient object
    # We'll use this object to create and interact with the queue
    queue_client = QueueClient(account_url, queue_name=queue_name ,credential=default_credential)

Az üzenetsor-üzenetek szövegként vannak tárolva. Ha bináris adatokat szeretne tárolni, állítsa be a Base64 kódolási és dekódolási függvényeket, mielőtt üzenetet helyez az üzenetsorba.

Az ügyfélobjektum létrehozásakor a Base64 kódolási és dekódolási függvényei konfigurálhatók:

# Setup Base64 encoding and decoding functions
base64_queue_client = QueueClient.from_connection_string(
                            conn_str=connect_str, queue_name=q_name,
                            message_encode_policy = BinaryBase64EncodePolicy(),
                            message_decode_policy = BinaryBase64DecodePolicy()
                        )

Üzenetsor létrehozása

QueueClient Az objektum használatával hívja meg a metódust, create_queue hogy létrehozza az üzenetsort a tárfiókban.

Adja hozzá ezt a kódot a blokk végéhez try :

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Üzenetek hozzáadása üzenetsorhoz

Az alábbi kódrészlet a metódus meghívásával üzeneteket ad hozzá az send_message üzenetsorhoz. A harmadik send_message hívásból visszaadott adatokat is mentiQueueMessage. A saved_message program az üzenet tartalmának frissítésére szolgál.

Adja hozzá ezt a kódot a blokk végéhez try :

    print("\nAdding messages to the queue...")

    # Send several messages to the queue
    queue_client.send_message(u"First message")
    queue_client.send_message(u"Second message")
    saved_message = queue_client.send_message(u"Third message")

Üzenetsor üzeneteibe való betekintés

A metódus meghívásával peek_messages pillanthat meg az üzenetsor üzeneteibe. Ez a metódus egy vagy több üzenetet kér le az üzenetsor elejéről, de nem módosítja az üzenet láthatóságát.

Adja hozzá ezt a kódot a blokk végéhez try :

    print("\nPeek at the messages in the queue...")

    # Peek at messages in the queue
    peeked_messages = queue_client.peek_messages(max_messages=5)

    for peeked_message in peeked_messages:
        # Display the message
        print("Message: " + peeked_message.content)

Üzenet frissítése üzenetsorban

Frissítse az üzenet tartalmát a update_message metódus meghívásával. Ez a módszer módosíthatja az üzenetek láthatóságának időtúllépését és tartalmát. Az üzenet tartalmának legfeljebb 64 KB méretű UTF-8 kódolt sztringnek kell lennie. Az új tartalommal együtt adja meg a kódban korábban mentett üzenet értékeit. Az saved_message értékek azonosítják a frissíteni kívánt üzenetet.

    print("\nUpdating the third message in the queue...")

    # Update a message using the message saved when calling send_message earlier
    queue_client.update_message(saved_message, pop_receipt=saved_message.pop_receipt, \
        content="Third message has been updated")

Az üzenetsor hosszának lekérése

Megbecsülheti egy üzenetsorban található üzenetek számát.

A get_queue_properties metódus az üzenetsor tulajdonságait adja vissza, beleértve a approximate_message_count.

properties = queue_client.get_queue_properties()
count = properties.approximate_message_count
print("Message count: " + str(count))

Az eredmény hozzávetőleges, mivel az üzenetek hozzáadhatók vagy eltávolíthatók, miután a szolgáltatás válaszolt a kérésére.

Üzenetek fogadása üzenetsorból

A korábban hozzáadott üzeneteket a receive_messages metódus meghívásával töltheti le.

Adja hozzá ezt a kódot a blokk végéhez try :

    print("\nReceiving messages from the queue...")

    # Get messages from the queue
    messages = queue_client.receive_messages(max_messages=5)

A metódus meghívásakor receive_messages megadhat egy értéket max_messages, amely az üzenetsorból lekérendő üzenetek száma. Az alapértelmezett érték 1 üzenet, a maximum 32 üzenet. Megadhat egy értéket visibility_timeoutis, amely elrejti az üzeneteket más műveletekből az időtúllépési időszakra vonatkozóan. Az alapértelmezett érték 30 másodperc.

Üzenetek törlése üzenetsorból

Üzenetek törlése az üzenetsorból a beérkezés és a feldolgozás után. Ebben az esetben a feldolgozás csak az üzenetet jeleníti meg a konzolon.

Az alkalmazás szünetelteti a felhasználói bevitelt, input mielőtt feldolgozza és törli az üzeneteket. A törlés előtt ellenőrizze az Azure Portalon , hogy az erőforrások megfelelően lettek-e létrehozva. A kifejezetten nem törölt üzenetek végül ismét láthatóvá válnak az üzenetsorban, hogy újra feldolgozzák őket.

Adja hozzá ezt a kódot a blokk végéhez try :

    print("\nPress Enter key to 'process' messages and delete them from the queue...")
    input()

    for msg_batch in messages.by_page():
            for msg in msg_batch:
                # "Process" the message
                print(msg.content)
                # Let the service know we're finished with
                # the message and it can be safely deleted.
                queue_client.delete_message(msg)

Üzenetsor törlése

Az alábbi kód megtisztítja az alkalmazás által létrehozott erőforrásokat az üzenetsor törlésével a delete_queue metódus használatával.

Adja hozzá ezt a kódot a try blokk végéhez, és mentse a fájlt:

    print("\nPress Enter key to delete the queue...")
    input()

    # Clean up
    print("Deleting queue...")
    queue_client.delete_queue()

    print("Done")

A kód futtatása

Ez az alkalmazás három üzenetet hoz létre és ad hozzá egy Azure-üzenetsorhoz. A kód felsorolja az üzenetsorban lévő üzeneteket, majd lekéri és törli őket, mielőtt véglegesen törölené az üzenetsort.

A konzolablakban keresse meg a queues-quickstart.py fájlt tartalmazó könyvtárat, majd futtassa az alkalmazást az alábbi python paranccsal.

python queues-quickstart.py

Az alkalmazás kimenete a következő példához hasonló:

Azure Queue Storage client library - Python quickstart sample
Creating queue: quickstartqueues-<UUID>

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

First message
Second message
Third message has been updated

Press Enter key to delete the queue...

Deleting queue...
Done

Amikor az alkalmazás szünetelteti az üzenetek fogadását, ellenőrizze a tárfiókot az Azure Portalon. Ellenőrizze, hogy az üzenetek szerepelnek-e az üzenetsorban.

Nyomja le a billentyűt az Enter üzenetek fogadásához és törléséhez. Amikor a rendszer kéri, nyomja le ismét a billentyűt az Enter üzenetsor törléséhez és a bemutató befejezéséhez.

Következő lépések

Ebben a rövid útmutatóban megtanulta, hogyan hozhat létre üzenetsort, és hogyan adhat hozzá üzeneteket Python-kóddal. Ezután megtanulta betekinteni, lekérni és törölni az üzeneteket. Végül megtanulta, hogyan törölhet egy üzenetsort.

Oktatóanyagok, minták, rövid útmutatók és egyéb dokumentációk:

Azure Python-fejlesztőknek