Librerie del bus di servizio per PythonService Bus libraries for Python
Il bus di servizio di Microsoft Azure supporta un set di tecnologie middleware orientate ai messaggi e basate sul cloud, incluso l'accodamento dei messaggi affidabile e la messaggistica di pubblicazione e sottoscrizione permanente.Microsoft Azure Service Bus supports a set of cloud-based, message-oriented middleware technologies including reliable message queuing and durable publish/subscribe messaging.
- Codice sorgente dell'SDKSDK source code
- Documentazione di riferimento sull'SDKSDK reference documentation
Novità della versione 0.50.0What's new in v0.50.0?
A partire dalla versione 0.50.0 è disponibile una nuova API basata su AMQP per l'invio e la ricezione di messaggi.As of version 0.50.0 a new AMQP-based API is available for sending and receiving messages. Questo aggiornamento include modifiche di rilievo.This update involves breaking changes.
Per determinare se l'aggiornamento è attualmente opportuno per le proprie esigenze, vedere Migrazione dalla versione 0.21.1 alla versione 0.50.0.Please read Migration from v0.21.1 to v0.50.0 to determine if upgrading is right for you at this time.
La nuova API basata su AMQP offre maggiore affidabilità nel passaggio dei messaggi, migliori prestazioni e l'estensione del supporto di funzionalità per il futuro.The new AMQP-based API offers improved message passing reliability, performance and expanded feature support going forward. La nuova API offre anche il supporto di operazioni asincrone (basato su asyncio) per l'invio, la ricezione e la gestione dei messaggi.The new API also offers support for asynchronous operations (based on asyncio) for sending, receiving and handling messages.
Per informazioni sulle operazioni basate su HTTP legacy, vedere Uso delle operazioni basate su HTTP dell'API legacy.For documentation on the legacy HTTP-based operations please see Using HTTP-based operations of the legacy API.
PrerequisitiPrerequisites
- Sottoscrizione di Azure. Creare un account gratuitoAzure subscription - Create a free account
- Credenziali di gestione e spazio dei nomi del bus di servizio di AzureAzure Service Bus namespace and management credentials
- Python 2.7-3.7Python 2.7-3.7
InstallazioneInstallation
pip install azure-servicebus
Connettersi al bus di servizio di AzureConnect to Azure Service Bus
Ottenere le credenzialiGet credentials
Usare il frammento dell'interfaccia della riga di comando di Azure riportato di seguito per popolare una variabile di ambiente con la stringa di connessione del bus di servizio (questo valore è disponibile anche nel portale di Azure).Use the Azure CLI snippet below to populate an environment variable with the Service Bus connection string (you can also find this value in the Azure portal). Il frammento è presentato nel formato per la shell Bash.The snippet is formatted for the Bash shell.
RES_GROUP=<resource-group-name>
NAMESPACE=<servicebus-namespace>
export SB_CONN_STR=$(az servicebus namespace authorization-rule keys list \
--resource-group $RES_GROUP \
--namespace-name $NAMESPACE \
--name RootManageSharedAccessKey \
--query primaryConnectionString \
--output tsv)
Creare il clientCreate client
Dopo aver popolato la variabile di ambiente SB_CONN_STR, è possibile creare ServiceBusClient.Once you've populated the SB_CONN_STR environment variable, you can create the ServiceBusClient.
import os
from azure.servicebus import ServiceBusClient
connection_str = os.environ['SB_CONN_STR']
sb_client = ServiceBusClient.from_connection_string(connection_str)
Se si vogliono usare operazioni asincrone, usare lo spazio dei nomi azure.servicebus.aio.If you wish to use asynchronous operations, please use the azure.servicebus.aio namespace.
import os
from azure.servicebus.aio import ServiceBusClient
connection_str = os.environ['SB_CONN_STR']
sb_client = ServiceBusClient.from_connection_string(connection_str)
Code del bus di servizioService Bus queues
Le code del bus di servizio sono un'alternativa alle code di archiviazione e possono essere utili negli scenari in cui sono necessarie funzionalità di messaggistica più avanzate (come messaggi di dimensioni maggiori, ordinamento dei messaggi, letture distruttive a operazione singola e recapito pianificato) con recapito di tipo push (tramite polling prolungato).Service Bus queues are an alternative to Storage queues that might be useful in scenarios where more advanced messaging features are needed (larger message sizes, message ordering, single-operation destructive reads, scheduled delivery) using push-style delivery (using long polling).
Crea codaCreate queue
Il codice seguente crea una nuova coda nello spazio dei nomi del bus di servizio.This creates a new queue within the Service Bus namespace. Se nello spazio dei nomi esiste già una coda con lo stesso nome, verrà generato un errore.If a queue of the same name already exists within the namespace an error will be raised.
sb_client.create_queue("MyQueue")
È anche possibile specificare parametri facoltativi per configurare il comportamento della coda.Optional parameters to configure the queue behavior can also be specified.
sb_client.create_queue(
"MySessionQueue",
requires_session=True # Create a sessionful queue
max_delivery_count=5 # Max delivery attempts per message
)
Ottenere un client di codaGet a queue client
È possibile usare QueueClient per inviare e ricevere messaggi dalla coda, nonché per altre operazioni.A QueueClient can be used to send and receive messages from the queue, along with other operations.
queue_client = sb_client.get_queue("MyQueue")
Invio di messaggiSending messages
Il client di coda può inviare uno o più messaggi contemporaneamente:The queue client can send one or more messages at a time:
from azure.servicebus import Message
message = Message("Hello World")
queue_client.send(message)
message_one = Message("First")
message_two = Message("Second")
queue_client.send([message_one, message_two])
Ogni chiamata a QueueClient.send creerà una nuova connessione al servizio.Each call to QueueClient.send will create a new service connection. Per riusare la stessa connessione per più chiamate di invio, è possibile aprire un mittente:To reuse the same connection for multiple send calls, you can open a sender:
message_one = Message("First")
message_two = Message("Second")
with queue_client.get_sender() as sender:
sender.send(message_one)
sender.send(message_two)
Se si usa un client asincrono, le operazioni precedenti useranno la sintassi di async:If you are using an asynchronous client, the above operations will use async syntax:
from azure.servicebus.aio import Message
message = Message("Hello World")
await queue_client.send(message)
message_one = Message("First")
message_two = Message("Second")
async with queue_client.get_sender() as sender:
await sender.send(message_one)
await sender.send(message_two)
Ricezione di messaggiReceiving messages
È possibile ricevere messaggi da una coda in un iteratore continuo.Messages can be received from a queue as a continuous iterator. La modalità predefinita per la ricezione dei messaggi è PeekLock, con cui ogni messaggio deve essere completato in modo esplicito per essere rimosso dalla coda.The default mode for message receiving is PeekLock, which requires each message to be explicitly completed in order that it be removed from the queue.
messages = queue_client.get_receiver()
for message in messages:
print(message)
message.complete()
La connessione al servizio rimarrà aperta fino alla fine dell'iteratore.The service connection will remain open for the entirety of the iterator. Se l'iterazione del flusso di messaggi viene effettuata solo parzialmente, è consigliabile eseguire il ricevitore in un'istruzione with affinché la connessione venga chiusa:If you find yourself only partially iterating the message stream, you should run the receiver in a with statement to ensure the connection is closed:
with queue_client.get_receiver() as messages:
for message in messages:
print(message)
message.complete()
break
Se si usa un client asincrono, le operazioni precedenti useranno la sintassi di async:If you are using an asynchronous client, the above operations will use async syntax:
async with queue_client.get_receiver() as messages:
async for message in messages:
print(message)
await message.complete()
break
Argomenti e sottoscrizioni del bus di servizioService Bus topics and subscriptions
Gli argomenti e le sottoscrizioni del bus di servizio sono un'astrazione basata sulle code del bus di servizio e offrono una forma di comunicazione uno-a-molti, con un schema di pubblicazione/sottoscrizione.Service Bus topics and subscriptions are an abstraction on top of Service Bus queues that provide a one-to-many form of communication, in a publish/subscribe pattern. I messaggi vengono inviati a un argomento e recapitati a una o più sottoscrizioni associate, supportando la scalabilità per un numero elevato di destinatari.Messages are sent to a topic and delivered to one or more associated subscriptions, which is useful for scaling to large numbers of recipients.
Creare un argomentoCreate topic
Il codice seguente crea un nuovo argomento nello spazio dei nomi del bus di servizio.This creates a new topic within the Service Bus namespace. Se esiste già un argomento con lo stesso nome, verrà generato un errore.If a topic of the same name already exists an error will be raised.
sb_client.create_topic("MyTopic")
Ottenere un client di argomentoGet a topic client
È possibile usare TopicClient per inviare messaggi all'argomento, nonché per altre operazioni.A TopicClient can be used to send messages to the topic, along with other operations.
topic_client = sb_client.get_topic("MyTopic")
Creare la sottoscrizioneCreate subscription
Il codice seguente crea una nuova sottoscrizione per l'argomento specificato nello spazio dei nomi del bus di servizio.This creates a new subscription for the specified topic within the Service Bus namespace.
sb_client.create_subscription("MyTopic", "MySubscription")
Ottenere un client di sottoscrizioneGet a subscription client
È possibile usare SubscriptionClient per ricevere messaggi dall'argomento, nonché per altre operazioni.A SubscriptionClient can be used to receive messages from the topic, along with other operations.
topic_client = sb_client.get_subscription("MyTopic", "MySubscription")
Migrazione dalla versione 0.21.1 alla versione 0.50.0Migration from v0.21.1 to v0.50.0
Nella versione 0.50.0 sono state introdotte importanti modifiche di rilievo.Major breaking changes were introduced in version 0.50.0. Nella versione 0.50.0 è ancora disponibile l'API basata su HTTP originale, ma si trova in un nuovo spazio dei nomi: azure.servicebus.control_client.The original HTTP-based API is still available in v0.50.0 - however it now exists under a new namesapce: azure.servicebus.control_client.
È consigliabile eseguire l'aggiornamento?Should I upgrade?
Il nuovo pacchetto (versione 0.50.0) non offre nessun miglioramento rispetto alla versione 0.21.1 nelle operazioni basate su HTTP.The new package (v0.50.0) offers no improvements in HTTP-based operations over v0.21.1. L'API basata su HTTP è identica tranne per il fatto che si trova ora in un nuovo spazio dei nomi.The HTTP-based API is identical except that it now exists under a new namespace. Per questo motivo, se si vogliono usare solo operazioni basate su HTTP (create_queue, delete_queue e così via), l'aggiornamento non offrirà attualmente alcun vantaggio aggiuntivo.For this reason if you only wish to use HTTP-based operations (create_queue, delete_queue etc) - there will be no additional benefit in upgrading at this time.
Come si esegue la migrazione del codice alla nuova versione?How do I migrate my code to the new version?
Per trasferire il codice scritto per la versione 0.21.0 alla versione 0.50.0 è sufficiente modificare lo spazio dei nomi di importazione:Code written against v0.21.0 can be ported to version 0.50.0 by simply changing the import namespace:
# from azure.servicebus import ServiceBusService <- This will now raise an ImportError
from azure.servicebus.control_client import ServiceBusService
key_name = 'RootManageSharedAccessKey' # SharedAccessKeyName from Azure portal
key_value = '' # SharedAccessKey from Azure portal
sbs = ServiceBusService(service_namespace,
shared_access_key_name=key_name,
shared_access_key_value=key_value)
Uso delle operazioni basate su HTTP dell'API legacyUsing HTTP-based operations of the legacy API
Le informazioni seguenti illustrano l'API legacy e sono destinate a coloro che vogliono trasferire il codice esistente alla versione 0.50.0 senza apportare modifiche aggiuntive.The following documentation describes the legacy API and should be used for those wishing to port existing code to v0.50.0 without making any additional changes. Queste informazioni di riferimento possono essere usate anche come indicazioni per gli utenti della versione 0.21.1.This reference can also be used as guidance by those using v0.21.1. Se si scrive nuovo codice, è consigliabile usare la nuova API descritta sopra.For those writing new code, we recommend using the new API described above.
Code del bus di servizioService Bus queues
Autenticazione con firma di accesso condivisoShared Access Signature (SAS) authentication
Per usare l'autenticazione con firma di accesso condiviso, creare il servizio del bus di servizio con il codice seguente:To use Shared Access Signature authentication, create the service bus service with:
from azure.servicebus.control_client import ServiceBusService
key_name = 'RootManageSharedAccessKey' # SharedAccessKeyName from Azure portal
key_value = '' # SharedAccessKey from Azure portal
sbs = ServiceBusService(service_namespace,
shared_access_key_name=key_name,
shared_access_key_value=key_value)
Autenticazione con il Servizio di controllo di accesso (ACS)Access Control Service (ACS) authentication
Il Servizio di controllo di accesso non è supportato nei nuovi spazi dei nomi del bus di servizio.ACS is not supported on new Service Bus namespaces. È consigliabile eseguire la migrazione delle applicazioni all'autenticazione con firma di accesso condiviso.We recommend migrating applications to SAS authentication. Per usare l'autenticazione ACS in uno spazio dei nomi precedente del bus di servizio, creare ServiceBusService con:To use ACS authentication within an older Service Bus namesapce, create the ServiceBusService with:
from azure.servicebus.control_client import ServiceBusService
account_key = '' # DEFAULT KEY from Azure portal
issuer = 'owner' # DEFAULT ISSUER from Azure portal
sbs = ServiceBusService(service_namespace,
account_key=account_key,
issuer=issuer)
Invio e ricezione di messaggiSending and receiving messages
È possibile usare il metodo create_queue per rendere disponibile una coda:The create_queue method can be used to ensure a queue exists:
sbs.create_queue('taskqueue')
È quindi possibile chiamare il metodo send_queue_message per inserire il messaggio nella coda:The send_queue_message method can then be called to insert the message into the queue:
from azure.servicebus.control_client import Message
msg = Message('Hello World!')
sbs.send_queue_message('taskqueue', msg)
È quindi possibile chiamare il metodo send_queue_message_batch per inviare più messaggi contemporaneamente:The send_queue_message_batch method can then be called to send several messages at once:
from azure.servicebus.control_client import Message
msg1 = Message('Hello World!')
msg2 = Message('Hello World again!')
sbs.send_queue_message_batch('taskqueue', [msg1, msg2])
È quindi possibile chiamare il metodo receive_queue_message per rimuovere il messaggio dalla coda.It is then possible to call the receive_queue_message method to dequeue the message.
msg = sbs.receive_queue_message('taskqueue')
Argomenti del bus di servizioService Bus topics
Per creare un argomento sul lato server è possibile usare il metodo create_topic:The create_topic method can be used to create a server-side topic:
sbs.create_topic('taskdiscussion')
Per inviare un messaggio a un argomento è possibile usare il metodo send_topic_message:The send_topic_message method can be used to send a message to a topic:
from azure.servicebus.control_client import Message
msg = Message(b'Hello World!')
sbs.send_topic_message('taskdiscussion', msg)
Per inviare più messaggi contemporaneamente è possibile usare il metodo send_topic_message_batch:The send_topic_message_batch method can be used to send several messages at once:
from azure.servicebus.control_client import Message
msg1 = Message(b'Hello World!')
msg2 = Message(b'Hello World again!')
sbs.send_topic_message_batch('taskdiscussion', [msg1, msg2])
Si noti che un messaggio str avrà la codifica UTF-8 in Python 3 e sarà necessario gestire la codifica manualmente in Python 2.Please consider that in Python 3 a str message will be utf-8 encoded and you should have to manage your encoding yourself in Python 2.
Un client può quindi creare una sottoscrizione e iniziare a utilizzare i messaggi chiamando il metodo create_subscription seguito dal metodo receive_subscription_message.A client can then create a subscription and start consuming messages by calling the create_subscription method followed by the receive_subscription_message method. Si noti che tutti i messaggi inviati prima della creazione della sottoscrizione non verranno ricevuti.Please note that any messages sent before the subscription is created will not be received.
from azure.servicebus.control_client import Message
sbs.create_subscription('taskdiscussion', 'client1')
msg = Message('Hello World!')
sbs.send_topic_message('taskdiscussion', msg)
msg = sbs.receive_subscription_message('taskdiscussion', 'client1')
Hub eventiEvent Hub
Hub eventi consente la raccolta di flussi di eventi a velocità effettiva elevata da diversi set di dispositivi e servizi.Event Hubs enable the collection of event streams at high throughput, from a diverse set of devices and services.
Per creare un hub eventi è possibile usare il metodo create_event_hub:The create_event_hub method can be used to create an event hub:
sbs.create_event_hub('myhub')
Per inviare un evento:To send an event:
sbs.send_event('myhub', '{ "DeviceId":"dev-01", "Temperature":"37.0" }')
Il contenuto di un evento è il messaggio o la stringa con codifica JSON contenente più messaggi.The event content is the event message or JSON-encoded string that contains multiple messages.
Funzionalità avanzateAdvanced features
Proprietà broker e proprietà utenteBroker properties and user properties
Questa sezione descrive come usare le proprietà Broker e User definite qui:This section describes how to use Broker and User properties defined here:
sent_msg = Message(b'This is the third message',
broker_properties={'Label': 'M3'},
custom_properties={'Priority': 'Medium',
'Customer': 'ABC'}
)
È possibile usare valori datetime, int, float o booleaniYou can use datetime, int, float or boolean
props = {'hello': 'world',
'number': 42,
'active': True,
'deceased': False,
'large': 8555111000,
'floating': 3.14,
'dob': datetime(2011, 12, 14),
'double_quote_message': 'This "should" work fine',
'quote_message': "This 'should' work fine"}
sent_msg = Message(b'message with properties', custom_properties=props)
Per motivi di compatibilità con la versione precedente di questa libreria, è possibile definire broker_properties anche come stringa JSON.For compatibility reason with old version of this library, broker_properties could also be defined as a JSON string.
In questo caso sarà necessario scrivere una stringa JSON valida; Python non eseguirà alcuna verifica prima dell'invio all'API Rest.If this situation, you're responsible to write a valid JSON string, no check will be made by Python before sending to the RestAPI.
broker_properties = '{"ForcePersistence": false, "Label": "My label"}'
sent_msg = Message(b'receive message',
broker_properties = broker_properties
)