Azure SDK for Python Documentation

Transcription

1 Azure SDK for Python Documentation Release Microsoft May 13, 2015

2

3 Contents 1 Installation: 1 2 Documentation: 3 3 Features: 5 4 System Requirements: 7 5 Need Help?: 9 6 Contributing: Contribute Code or Provide Feedback: To run tests: To generate documentation: Learn More 13 8 Indices and tables Usage Need Help? Contribute Code or Provide Feedback Learn More Usage Need Help? Contribute Code or Provide Feedback Learn More Usage Need Help? Contribute Code or Provide Feedback Learn More azure package azure.http package azure.http.batchclient module azure.http.httpclient module azure.http.requestsclient module azure.http.winhttp module azure.servicebus package azure.servicebus.servicebusservice module azure.servicemanagement package i

4 8.22 azure.servicemanagement.schedulermanagementservice module azure.servicemanagement.servicebusmanagementservice module azure.servicemanagement.servicemanagementclient module azure.servicemanagement.servicemanagementservice module azure.servicemanagement.sqldatabasemanagementservice module azure.servicemanagement.websitemanagementservice module azure.storage package azure.storage.blobservice module azure.storage.cloudstorageaccount module azure.storage.queueservice module azure.storage.sharedaccesssignature module azure.storage.storageclient module azure.storage.tableservice module azure Python Module Index 319 ii

5 CHAPTER 1 Installation: You can use pip to install the latest released version of azure: pip install azure If you want to install azure from source: git clone git://github.com/azure/azure-sdk-for-python.git cd azure-sdk-for-python python setup.py install 1

6 2 Chapter 1. Installation:

7 CHAPTER 2 Documentation: ServiceManagement (API) ServiceBus (API) Storage (API) All Documentation 3

8 4 Chapter 2. Documentation:

9 CHAPTER 3 Features: Tables Blobs create and delete tables create, query, insert, update, merge, and delete entities create, list, and delete containers, work with container metadata and permissions, list blobs in container create block and page blobs (from a stream, a file, or a string), work with blob blocks and pages, delete blobs work with blob properties, metadata, leases, snapshot a blob Storage Queues create, list, and delete queues, and work with queue metadata create, get, peek, update, delete messages Service Bus Queues: create, list and delete queues; create, list, and delete subscriptions; send, receive, unlock and delete messages Topics: create, list, and delete topics; create, list, and delete rules Service Management storage accounts: create, update, delete, list, regenerate keys affinity groups: create, update, delete, list, get properties locations: list hosted services: create, update, delete, list, get properties deployment: create, get, delete, swap, change configuration, update status, upgrade, rollback role instance: reboot, reimage discover addresses and ports for the endpoints of other role instances in your service get configuration settings and access local resources get role instance information for current role and other role instances query and set the status of the current role 5

10 6 Chapter 3. Features:

11 CHAPTER 4 System Requirements: The supported Python versions are 2.7.x, 3.3.x, and 3.4.x To download Python, please visit We recommend Python Tools for Visual Studio as a development environment for developing your applications. Please visit for more information. 7

12 8 Chapter 4. System Requirements:

13 CHAPTER 5 Need Help?: Be sure to check out the Microsoft Azure Developer Forums on Stack Overflow if you have trouble with the provided code. 9

14 10 Chapter 5. Need Help?:

15 CHAPTER 6 Contributing: 6.1 Contribute Code or Provide Feedback: If you would like to become an active contributor to this project please follow the instructions provided in Microsoft Azure Projects Contribution Guidelines. If you encounter any bugs with the library please file an issue in the Issues section of the project. 6.2 To run tests: To run the tests for the Azure SDK for Python: TODO. 6.3 To generate documentation: To generate the documentation run: cd doc BuildDocs.bat 11

16 12 Chapter 6. Contributing:

17 CHAPTER 7 Learn More Microsoft Azure Python Developer Center 13

18 14 Chapter 7. Learn More

19 CHAPTER 8 Indices and tables genindex modindex search 8.1 Usage ServiceBus Queues ServiceBus 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-operaiton destructive reads, scheduled delivery) using push-style delivery (using long polling). The service can use Shared Access Signature authentication, or ACS authentication. Service bus namespaces created using the Azure portal after August 2014 no longer support ACS authentication. You can create ACS compatible namespaces with the Azure SDK. Shared Access Signature Authentication To use Shared Access Signature authentication, create the service bus service with: from azure.servicebus 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) ACS Authentication To use ACS authentication, create the service bus service with: from azure.servicebus import ServiceBusService account_key = '' # DEFAULT KEY from Azure portal issuer = 'owner' # DEFAULT ISSUER from Azure portal 15

20 sbs = ServiceBusService(service_namespace, account_key=account_key, issuer=issuer) Sending and Receiving Messages The create_queue method can be used to ensure a queue exists: sbs.create_queue('taskqueue') The send_queue_message method can then be called to insert the message into the queue: from azure.servicebus import Message msg = Message('Hello World!') sbs.send_queue_message('taskqueue', msg) It is then possible to call the receive_queue_message method to dequeue the message. msg = sbs.receive_queue_message('taskqueue') ServiceBus Topics ServiceBus topics are an abstraction on top of ServiceBus Queues that make pub/sub scenarios easy to implement. The create_topic method can be used to create a server-side topic: sbs.create_topic('taskdiscussion') The send_topic_message method can be used to send a message to a topic: from azure.servicebus import Message msg = Message('Hello World!') sbs.send_topic_message('taskdiscussion', msg) A client can then create a subscription and start consuming messages by calling the create_subscription method followed by the receive_subscription_message method. Please note that any messages sent before the subscription is created will not be received. from azure.servicebus import Message sbs.create_subscription('taskdiscussion', 'client1') msg = Message('Hello World!') sbs.send_topic_message('taskdiscussion', msg) msg = sbs.receive_subscription_message('taskdiscussion', 'client1') Event Hub Event Hubs enable the collection of event streams at high throughput, from a diverse set of devices and services. The create_event_hub method can be used to create an event hub: sbs.create_event_hub('myhub') To send an event: 16 Chapter 8. Indices and tables

21 sbs.send_event('myhub', '{ "DeviceId":"dev-01", "Temperature":"37.0" }') The event content is the event message or JSON-encoded string that contains multiple messages. 8.2 Need Help? Be sure to check out the Microsoft Azure Developer Forums on Stack Overflow if you have trouble with the provided code. 8.3 Contribute Code or Provide Feedback If you would like to become an active contributor to this project please follow the instructions provided in Microsoft Azure Projects Contribution Guidelines. If you encounter any bugs with the library please file an issue in the Issues section of the project. 8.4 Learn More Microsoft Azure Python Developer Center 8.5 Usage Service Management Set-up certificates You will need two certificates, one for the server (a.cer file) and one for the client (a.pem file). Using the Azure.PublishSettings certificate You can download your Azure publish settings file and use the certificate that is embedded in that file to create the client certificate. The server certificate already exists, so you won t need to upload one. To do this, download your publish settings then use this code to create the.pem file. from azure.servicemanagement import get_certificate_from_publish_settings subscription_id = get_certificate_from_publish_settings( publish_settings_path='myaccount.publishsettings', path_to_write_certificate='mycert.pem', subscription_id=' ', ) The subscription id parameter is optional. If there are more than one subscription in the publish settings, the first one will be used Need Help? 17

22 Creating and uploading new certificate with OpenSSL To create the.pem file using OpenSSL, execute this: openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem To create the.cer certificate, execute this: openssl x509 -inform pem -in mycert.pem -outform der -out mycert.cer After you have created the certificate, you will need to upload the.cer file to Microsoft Azure via the Upload action of the Settings tab of the management portal. Initialization To initialize the management service, pass in your subscription id and the path to the.pem file. from azure.servicemanagement import ServiceManagementService subscription_id = ' ' cert_file = 'mycert.pem' sms = ServiceManagementService(subscription_id, cert_file) List Available Locations locations = sms.list_locations() for location in locations: print(location.name) Create a Storage Service To create a storage service, you need a name for the service (between 3 and 24 lowercase characters and unique within Microsoft Azure), a label (up to 100 characters, automatically encoded to base-64), and either a location or an affinity group. name = "mystorageservice" desc = name label = name location = 'West US' result = sms.create_storage_account(name, desc, label, location=location) Create a Cloud Service A cloud service is also known as a hosted service (from earlier versions of Microsoft Azure). The create_hosted_service method allows you to create a new hosted service by providing a hosted service name (which must be unique in Microsoft Azure), a label (automatically encoded to base-64), and the location or the affinity group for your service. name = "myhostedservice" desc = name label = name location = 'West US' result = sms.create_hosted_service(name, label, desc, location=location) 18 Chapter 8. Indices and tables

23 Create a Deployment To make a new deployment to Azure you must store the package file in a Microsoft Azure Blob Storage account under the same subscription as the hosted service to which the package is being uploaded. You can create a deployment package with the Microsoft Azure PowerShell cmdlets, or with the cspack commandline tool. service_name = "myhostedservice" deployment_name = "v1" slot = 'Production' package_url = "URL_for_.cspkg_file" configuration = base64.b64encode(open(file_path, 'rb').read('path_to_.cscfg_file')) label = service_name result = sms.create_deployment(service_name, slot, deployment_name, package_url, label, configuration) operation = sms.get_operation_status(result.request_id) print('operation status: ' + operation.status) 8.6 Need Help? Be sure to check out the Microsoft Azure Developer Forums on Stack Overflow if you have trouble with the provided code. 8.7 Contribute Code or Provide Feedback If you would like to become an active contributor to this project please follow the instructions provided in Microsoft Azure Projects Contribution Guidelines. If you encounter any bugs with the library please file an issue in the Issues section of the project. 8.8 Learn More Microsoft Azure Python Developer Center 8.9 Usage Table Storage To ensure a table exists, call create_table: from azure.storage import TableService table_service = TableService(account_name, account_key) table_service.create_table('tasktable') 8.6. Need Help? 19

24 A new entity can be added by calling insert_entity: from datetime import datetime table_service = TableService(account_name, account_key) table_service.create_table('tasktable') table_service.insert_entity( 'tasktable', { 'PartitionKey' : 'tasksseattle', 'RowKey': '1', 'Description': 'Take out the trash', 'DueDate': datetime(2011, 12, 14, 12) } ) The method get_entity can then be used to fetch the entity that was just inserted: table_service = TableService(account_name, account_key) entity = table_service.get_entity('tasktable', 'tasksseattle', '1') If you want to give access to a table to a third party without revealing your account key, you can use a shared access signature. The shared access signature includes an access policy, with optional start, expiry and permission. To generate a shared access signature, use: from azure.storage import TableService, AccessPolicy, SharedAccessPolicy, TableSharedAccessPermission table_service = TableService(account_name, account_key) ap = AccessPolicy( expiry=' ', permission=tablesharedaccesspermissions.query, ) sas_token = table_service.generate_shared_access_signature( 'tasktable', SharedAccessPolicy(ap), ) Alternatively, you can define a named access policy on the server: from azure.storage import TableService, SharedAccessPolicy, TableSharedAccessPermissions, SignedIdent table_service = TableService(account_name, account_key) policy_name = 'readonlyvaliduntilnextyear' si = SignedIdentifier() si.id = policy_name si.access_policy.expiry = ' ' si.access_policy.permission = TableSharedAccessPermissions.QUERY identifiers = SignedIdentifiers() identifiers.signed_identifiers.append(si) table_service.set_queue_acl( table_name='tasktable', signed_identifiers=identifiers, ) And generate a shared access signature for that named access policy: sas_token = table_service.generate_shared_access_signature( 'tasktable', SharedAccessPolicy(signed_identifier=policy_name), ) 20 Chapter 8. Indices and tables

25 Using a predefined access policy has the advantage that it can be revoked from the server side. To revoke, call set_table_acl with the new list of signed identifiers. You can pass in None or an empty list to remove all. table_service.set_table_acl( table_name='tasktable', signed_identifiers=none, ) The third party can use the shared access signature token to authenticate, instead of an account key: from azure.storage import TableService table_service = TableService(account_name, sas_token=sas_token) entity = table_service.get_entity('tasktable', 'tasksseattle', '1') Blob Storage The create_container method can be used to create a container in which to store a blob: from azure.storage import BlobService blob_service = BlobService(account_name, account_key) blob_service.create_container('images') To upload a file uploads/image.png from disk to a blob named image.png, the method put_block_blob_from_path can be used: from azure.storage import BlobService blob_service = BlobService(account_name, account_key) blob_service.put_block_blob_from_path( 'images', 'image.png', 'uploads/image.png', max_connections=5, ) The max_connections parameter is optional, and lets you use multiple parallel connections to perform uploads and downloads. This parameter is available on the various upload and download methods described below. To upload an already opened file to a blob named image.png, the method put_block_blob_from_file can be used instead. The count parameter is optional, but you will get better performance if you specify it. This indicates how many bytes you want read from the file and uploaded to the blob. with open('uploads/image.png') as file: blob_service.put_block_blob_from_file( 'images', 'image.png', file, count=50000, max_connections=4, ) To upload unicode text, use put_block_blob_from_text which will do the conversion to bytes using the specified encoding. To upload bytes, use put_block_blob_from_bytes. To download a blob named image.png to a file on disk downloads/image.png, where the downloads folder already exists, the get_blob_to_path method can be used: 8.9. Usage 21

26 from azure.storage import BlobService blob_service = BlobService(account_name, account_key) blob = blob_service.get_blob_to_path( 'images', 'image.png', 'downloads/image.png', max_connections=8, ) To download to an already opened file, use get_blob_to_file. To download to an array of bytes, use get_blob_to_bytes. To download to unicode text, use get_blob_to_text. You can set public access to blobs in a container when the container is created: blob_service.create_container( container_name='images', x_ms_blob_public_access='blob', ) Or after it s created: blob_service.set_container_acl( container_name='images', x_ms_blob_public_access='blob', ) If x_ms_blob_public_access is set to blob : Blob data within this container can be read via anonymous request, but container data is not available. Clients cannot enumerate blobs within the container via anonymous request. If it s set to container : Container and blob data can be read via anonymous request. Clients can enumerate blobs within the container via anonymous request, but cannot enumerate containers within the storage account. The default is None: Container and blob data can be read by the account owner only. You can use BlobService to access public containers and blobs by omitting the account_key parameter: from azure.storage import BlobService blob_service = BlobService(account_name) blob = blob_service.get_blob_to_path( 'images', 'image.png', 'downloads/image.png', max_connections=8, ) You can get a full URL for the blob (for use in a web browser, etc): from azure.storage import BlobService blob_service = BlobService(account_name) url = blob_service.make_blob_url( container_name='images', blob_name='image.png', ) # url is: 22 Chapter 8. Indices and tables

27 If you want to give access to a container or blob to a third party without revealing your account key or making the container or blob public, you can use a shared access signature. The shared access signature includes an access policy, with optional start, expiry and permission. To generate a shared access signature, use: from azure.storage import BlobService, AccessPolicy, SharedAccessPolicy, BlobSharedAccessPermissions blob_service = BlobService(account_name, account_key) ap = AccessPolicy( expiry=' ', permission=blobsharedaccesspermissions.read, ) sas_token = blob_service.generate_shared_access_signature( container_name='images', blob_name='image.png', shared_access_policy=sharedaccesspolicy(ap), ) Note that a shared access signature can be created for a container, just pass None (which is the default) for the blob_name parameter. Alternatively, you can define a named access policy on the server: from azure.storage import BlobService, AccessPolicy, SharedAccessPolicy, BlobSharedAccessPermissions, blob_service = BlobService(account_name, account_key) policy_name = 'readonlyvaliduntilnextyear' si = SignedIdentifier() si.id = policy_name si.access_policy.expiry = ' ' si.access_policy.permission = BlobSharedAccessPermissions.READ identifiers = SignedIdentifiers() identifiers.signed_identifiers.append(si) blob_service.set_container_acl( container_name='images', signed_identifiers=identifiers, ) And generate a shared access signature for that named access policy: sas_token = blob_service.generate_shared_access_signature( container_name='images', blob_name='image.png', shared_access_policy=sharedaccesspolicy(signed_identifier=policy_name), ) Using a predefined access policy has the advantage that it can be revoked from the server side. To revoke, call set_container_acl with the new list of signed identifiers. You can pass in None or an empty list to remove all. blob_service.set_container_acl( container_name='images', signed_identifiers=none, ) The third party can use the shared access signature token to authenticate, instead of an account key: from azure.storage import BlobService blob_service = BlobService(account_name, sas_token=sas_token) blob = blob_service.get_blob_to_path( 8.9. Usage 23

28 ) 'images', 'image.png', 'downloads/image.png', max_connections=8, You can get a full URL for the blob (for use in a web browser, etc): from azure.storage import BlobService blob_service = BlobService(account_name) url = blob_service.make_blob_url( container_name='images', blob_name='image.png', sas_token=sas_token, ) Storage Queues The create_queue method can be used to ensure a queue exists: from azure.storage import QueueService queue_service = QueueService(account_name, account_key) queue_service.create_queue('taskqueue') The put_message method can then be called to insert the message into the queue: from azure.storage import QueueService queue_service = QueueService(account_name, account_key) queue_service.put_message('taskqueue', 'Hello world!') It is then possible to call the get_messages method, process the message and then call delete_message with the message id and receipt. This two-step process ensures messages don t get lost when they are removed from the queue. from azure.storage import QueueService queue_service = QueueService(account_name, account_key) messages = queue_service.get_messages('taskqueue') queue_service.delete_message('taskqueue', messages[0].message_id, messages[0].pop_receipt) If you want to give access to a queue to a third party without revealing your account key, you can use a shared access signature. The shared access signature includes an access policy, with optional start, expiry and permission. To generate a shared access signature, use: from azure.storage import QueueService, AccessPolicy, SharedAccessPolicy, QueueSharedAccessPermission queue_service = QueueService(account_name, account_key) ap = AccessPolicy( expiry=' ', permission=queuesharedaccesspermissions.read, ) sas_token = queue_service.generate_shared_access_signature( 'taskqueue', SharedAccessPolicy(ap), ) Alternatively, you can define a named access policy on the server: from azure.storage import QueueService, SharedAccessPolicy, QueueSharedAccessPermissions, SignedIdent queue_service = QueueService(account_name, account_key) 24 Chapter 8. Indices and tables

29 policy_name = 'readonlyvaliduntilnextyear' si = SignedIdentifier() si.id = policy_name si.access_policy.expiry = ' ' si.access_policy.permission = QueueSharedAccessPermissions.READ identifiers = SignedIdentifiers() identifiers.signed_identifiers.append(si) queue_service.set_queue_acl( queue_name='taskqueue', signed_identifiers=identifiers, ) And generate a shared access signature for that named access policy: sas_token = queue_service.generate_shared_access_signature( 'taskqueue', SharedAccessPolicy(signed_identifier=policy_name), ) Using a predefined access policy has the advantage that it can be revoked from the server side. To revoke, call set_queue_acl with the new list of signed identifiers. You can pass in None or an empty list to remove all. queue_service.set_container_acl( queue_name='taskqueue', signed_identifiers=none, ) The third party can use the shared access signature token to authenticate, instead of an account key: from azure.storage import QueueService queue_service = QueueService(account_name, sas_token=sas_token) messages = queue_service.peek_messages('taskqueue') 8.10 Need Help? Be sure to check out the Microsoft Azure Developer Forums on Stack Overflow if you have trouble with the provided code Contribute Code or Provide Feedback If you would like to become an active contributor to this project please follow the instructions provided in Microsoft Azure Projects Contribution Guidelines. If you encounter any bugs with the library please file an issue in the Issues section of the project Learn More Microsoft Azure Python Developer Center Need Help? 25

30 8.13 azure package Subpackages azure.http package Submodules azure.http.batchclient module azure.http.httpclient module azure.http.requestsclient module azure.http.winhttp module Module contents exception azure.http.httperror(status, message, respheader, respbody) Bases: exceptions.exception HTTP Exception when response status code >= 300 Creates a new HTTPError with the specified status, message, response headers and body class azure.http.httprequest Bases: object Represents an HTTP Request. An HTTP Request consists of the following attributes: host: the host name to connect to method: the method to use to connect (string such as GET, POST, PUT, etc.) path: the uri fragment query: query parameters specified as a list of (name, value) pairs headers: header values specified as (name, value) pairs body: the body of the request. protocol_override: specify to use this protocol instead of the global one stored in _HTTPClient. class azure.http.httpresponse(status, message, headers, body) Bases: object Represents a response from an HTTP request. An HTTPResponse has the following attributes: status: the status code of the response message: the message headers: the returned headers, as a list of (name, value) pairs body: the body of the response 26 Chapter 8. Indices and tables

31 azure.servicebus package Submodules azure.servicebus.servicebusservice module class azure.servicebus.servicebusservice.servicebussasauthentication(key_name, key_value) sign_request(request, httpclient) class azure.servicebus.servicebusservice.servicebusservice(service_namespace=none, account_key=none, issuer=none, x_ms_version= , host_base=.servicebus.windows.net, shared_access_key_name=none, shared_access_key_value=none, authentication=none, timeout=65) Bases: object Initializes the service bus service for a namespace with the specified authentication settings (SAS or ACS). service_namespace: Service bus namespace, required for all operations. AZURE_SERVICEBUS_NAMESPACE env variable. If None, the value is set to the account_key: ACS authentication account key. If None, the value is set to the AZURE_SERVICEBUS_ACCESS_KEY env variable. Note that if both SAS and ACS settings are specified, SAS is used. issuer: ACS authentication issuer. If None, the value is set to the AZURE_SERVICEBUS_ISSUER env variable. Note that if both SAS and ACS settings are specified, SAS is used. x_ms_version: Unused. Kept for backwards compatibility. host_base: Optional. Live host base url. Defaults to Azure url. Override this for on-premise. shared_access_key_name: SAS authentication key name. Note that if both SAS and ACS settings are specified, SAS is used. shared_access_key_value: SAS authentication key value. Note that if both SAS and ACS settings are specified, SAS is used. authentication: Instance of authentication class. If this is specified, then ACS and SAS parameters are ignored. timeout: Optional. Timeout for the http request, in seconds. account_key create_event_hub(hub_name, hub=none, fail_on_exist=false) Creates a new Event Hub. hub_name: Name of event hub. hub: Optional. Event hub properties. Instance of EventHub class. hub.message_retention_in_days: Number of days to retain the events for this Event Hub. hub.status: Status of the Event Hub (enabled or disabled). hub.user_metadata: User metadata. hub.partition_count: Number of shards on the Event Hub. fail_on_exist: Specify whether to throw an exception when the event hub exists azure package 27

32 create_queue(queue_name, queue=none, fail_on_exist=false) Creates a new queue. Once created, this queue s resource manifest is immutable. queue_name: Name of the queue to create. queue: Queue object to create. fail_on_exist: Specify whether to throw an exception when the queue exists. create_rule(topic_name, subscription_name, rule_name, rule=none, fail_on_exist=false) Creates a new rule. Once created, this rule s resource manifest is immutable. topic_name: Name of the topic. subscription_name: Name of the subscription. rule_name: Name of the rule. fail_on_exist: Specify whether to throw an exception when the rule exists. create_subscription(topic_name, subscription_name, subscription=none, fail_on_exist=false) Creates a new subscription. Once created, this subscription resource manifest is immutable. topic_name: Name of the topic. subscription_name: Name of the subscription. fail_on_exist: Specify whether throw exception when subscription exists. create_topic(topic_name, topic=none, fail_on_exist=false) Creates a new topic. Once created, this topic resource manifest is immutable. topic_name: Name of the topic to create. topic: Topic object to create. fail_on_exist: Specify whether to throw an exception when the topic exists. delete_event_hub(hub_name, fail_not_exist=false) Deletes an Event Hub. This operation will also remove all associated state. hub_name: Name of the event hub to delete. fail_not_exist: Specify whether to throw an exception if the event hub doesn t exist. delete_queue(queue_name, fail_not_exist=false) Deletes an existing queue. This operation will also remove all associated state including messages in the queue. queue_name: Name of the queue to delete. fail_not_exist: Specify whether to throw an exception if the queue doesn t exist. delete_queue_message(queue_name, sequence_number, lock_token) Completes processing on a locked message and delete it from the queue. This operation should only be called after processing a previously locked message is successful to maintain At-Least-Once delivery assurances. queue_name: Name of the queue. sequence_number: The sequence number of the message to be deleted as returned in BrokerProperties[ SequenceNumber ] by the Peek Message operation. lock_token: The ID of the lock as returned by the Peek Message operation in BrokerProperties[ LockToken ] 28 Chapter 8. Indices and tables

33 delete_rule(topic_name, subscription_name, rule_name, fail_not_exist=false) Deletes an existing rule. topic_name: Name of the topic. subscription_name: Name of the subscription. rule_name: Name of the rule to delete. DEFAULT_RULE_NAME=$Default. Use DE- FAULT_RULE_NAME to delete default rule for the subscription. fail_not_exist: Specify whether throw exception when rule doesn t exist. delete_subscription(topic_name, subscription_name, fail_not_exist=false) Deletes an existing subscription. topic_name: Name of the topic. subscription_name: Name of the subscription to delete. fail_not_exist: Specify whether to throw an exception when the subscription doesn t exist. delete_subscription_message(topic_name, subscription_name, sequence_number, lock_token) Completes processing on a locked message and delete it from the subscription. This operation should only be called after processing a previously locked message is successful to maintain At-Least-Once delivery assurances. topic_name: Name of the topic. subscription_name: Name of the subscription. sequence_number: The sequence number of the message to be deleted as returned in BrokerProperties[ SequenceNumber ] by the Peek Message operation. lock_token: The ID of the lock as returned by the Peek Message operation in BrokerProperties[ LockToken ] delete_topic(topic_name, fail_not_exist=false) Deletes an existing topic. This operation will also remove all associated state including associated subscriptions. topic_name: Name of the topic to delete. fail_not_exist: Specify whether throw exception when topic doesn t exist. get_event_hub(hub_name) Retrieves an existing event hub. hub_name: Name of the event hub. get_queue(queue_name) Retrieves an existing queue. queue_name: Name of the queue. get_rule(topic_name, subscription_name, rule_name) Retrieves the description for the specified rule. topic_name: Name of the topic. subscription_name: Name of the subscription. rule_name: Name of the rule. get_subscription(topic_name, subscription_name) Gets an existing subscription azure package 29

34 topic_name: Name of the topic. subscription_name: Name of the subscription. get_topic(topic_name) Retrieves the description for the specified topic. issuer topic_name: Name of the topic. list_queues() Enumerates the queues in the service namespace. list_rules(topic_name, subscription_name) Retrieves the rules that exist under the specified subscription. topic_name: Name of the topic. subscription_name: Name of the subscription. list_subscriptions(topic_name) Retrieves the subscriptions in the specified topic. topic_name: Name of the topic. list_topics() Retrieves the topics in the service namespace. peek_lock_queue_message(queue_name, timeout= 60 ) Automically retrieves and locks a message from a queue for processing. The message is guaranteed not to be delivered to other receivers (on the same subscription only) during the lock duration period specified in the queue description. Once the lock expires, the message will be available to other receivers. In order to complete processing of the message, the receiver should issue a delete command with the lock ID received from this operation. To abandon processing of the message and unlock it for other receivers, an Unlock Message command should be issued, or the lock duration period can expire. queue_name: Name of the queue. timeout: Optional. The timeout parameter is expressed in seconds. peek_lock_subscription_message(topic_name, subscription_name, timeout= 60 ) This operation is used to atomically retrieve and lock a message for processing. The message is guaranteed not to be delivered to other receivers during the lock duration period specified in buffer description. Once the lock expires, the message will be available to other receivers (on the same subscription only) during the lock duration period specified in the topic description. Once the lock expires, the message will be available to other receivers. In order to complete processing of the message, the receiver should issue a delete command with the lock ID received from this operation. To abandon processing of the message and unlock it for other receivers, an Unlock Message command should be issued, or the lock duration period can expire. topic_name: Name of the topic. subscription_name: Name of the subscription. timeout: Optional. The timeout parameter is expressed in seconds. read_delete_queue_message(queue_name, timeout= 60 ) Reads and deletes a message from a queue as an atomic operation. This operation should be used when a best-effort guarantee is sufficient for an application; that is, using this operation it is possible for messages to be lost if processing fails. queue_name: Name of the queue. 30 Chapter 8. Indices and tables

35 timeout: Optional. The timeout parameter is expressed in seconds. read_delete_subscription_message(topic_name, subscription_name, timeout= 60 ) Read and delete a message from a subscription as an atomic operation. This operation should be used when a best-effort guarantee is sufficient for an application; that is, using this operation it is possible for messages to be lost if processing fails. topic_name: Name of the topic. subscription_name: Name of the subscription. timeout: Optional. The timeout parameter is expressed in seconds. receive_queue_message(queue_name, peek_lock=true, timeout=60) Receive a message from a queue for processing. queue_name: Name of the queue. peek_lock: Optional. True to retrieve and lock the message. False to read and delete the message. Default is True (lock). timeout: Optional. The timeout parameter is expressed in seconds. receive_subscription_message(topic_name, subscription_name, peek_lock=true, timeout=60) Receive a message from a subscription for processing. topic_name: Name of the topic. subscription_name: Name of the subscription. peek_lock: Optional. True to retrieve and lock the message. False to read and delete the message. Default is True (lock). timeout: Optional. The timeout parameter is expressed in seconds. send_event(hub_name, message, device_id=none, broker_properties=none) Sends a new message event to an Event Hub. send_queue_message(queue_name, message=none) Sends a message into the specified queue. The limit to the number of messages which may be present in the topic is governed by the message size the MaxTopicSizeInMegaBytes. If this message will cause the queue to exceed its quota, a quota exceeded error is returned and the message will be rejected. queue_name: Name of the queue. message: Message object containing message body and properties. send_topic_message(topic_name, message=none) Enqueues a message into the specified topic. The limit to the number of messages which may be present in the topic is governed by the message size in MaxTopicSizeInBytes. If this message causes the topic to exceed its quota, a quota exceeded error is returned and the message will be rejected. topic_name: Name of the topic. message: Message object containing message body and properties. set_proxy(host, port, user=none, password=none) Sets the proxy server host and port for the HTTP CONNECT Tunnelling. host: Address of the proxy. Ex: port: Port of the proxy. Ex: 6000 user: User for proxy authorization. password: Password for proxy authorization azure package 31

36 timeout unlock_queue_message(queue_name, sequence_number, lock_token) Unlocks a message for processing by other receivers on a given subscription. This operation deletes the lock object, causing the message to be unlocked. A message must have first been locked by a receiver before this operation is called. queue_name: Name of the queue. sequence_number: The sequence number of the message to be unlocked as returned in BrokerProperties[ SequenceNumber ] by the Peek Message operation. lock_token: The ID of the lock as returned by the Peek Message operation in BrokerProperties[ LockToken ] unlock_subscription_message(topic_name, subscription_name, sequence_number, lock_token) Unlock a message for processing by other receivers on a given subscription. This operation deletes the lock object, causing the message to be unlocked. A message must have first been locked by a receiver before this operation is called. topic_name: Name of the topic. subscription_name: Name of the subscription. sequence_number: The sequence number of the message to be unlocked as returned in BrokerProperties[ SequenceNumber ] by the Peek Message operation. lock_token: The ID of the lock as returned by the Peek Message operation in BrokerProperties[ LockToken ] update_event_hub(hub_name, hub=none) Updates an Event Hub. hub_name: Name of event hub. hub: Optional. Event hub properties. Instance of EventHub class. hub.message_retention_in_days: Number of days to retain the events for this Event Hub. with_filter(filter) Returns a new service which will process requests with the specified filter. Filtering operations can include logging, automatic retrying, etc... The filter is a lambda which receives the HTTPRequest and another lambda. The filter can perform any pre-processing on the request, pass it off to the next lambda, and then perform any post-processing on the response. class azure.servicebus.servicebusservice.servicebuswraptokenauthentication(account_key, issuer) sign_request(request, httpclient) Module contents class azure.servicebus.authorizationrule(claim_type=none, claim_value=none, rights=none, key_name=none, primary_key=none, secondary_key=none) class azure.servicebus.eventhub(message_retention_in_days=none, user_metadata=none, partition_count=none) status=none, 32 Chapter 8. Indices and tables

37 class azure.servicebus.message(body=none, service_bus_service=none, location=none, custom_properties=none, type= application/atom+xml;type=entry;charset=utf-8, broker_properties=none) Message class that used in send message/get mesage apis. add_headers(request) add addtional headers to request for message request. delete() Deletes itself if find queue name or topic name and subscription name. unlock() Unlocks itself if find queue name or topic name and subscription name. class azure.servicebus.queue(lock_duration=none, max_size_in_megabytes=none, requires_duplicate_detection=none, requires_session=none, default_message_time_to_live=none, dead_lettering_on_message_expiration=none, duplicate_detection_history_time_window=none, max_delivery_count=none, enable_batched_operations=none, size_in_bytes=none, message_count=none) Queue class corresponding to Queue Description: class azure.servicebus.rule(filter_type=none, filter_expression=none, action_type=none, action_expression=none) Rule class corresponding to Rule Description: class azure.servicebus.subscription(lock_duration=none, requires_session=none, default_message_time_to_live=none, dead_lettering_on_message_expiration=none, dead_lettering_on_filter_evaluation_exceptions=none, enable_batched_operations=none, max_delivery_count=none, message_count=none) Subscription class corresponding to Subscription Description: class azure.servicebus.topic(default_message_time_to_live=none, max_size_in_megabytes=none, requires_duplicate_detection=none, duplicate_detection_history_time_window=none, enable_batched_operations=none, size_in_bytes=none) Topic class corresponding to Topic Description: max_size_in_mega_bytes azure package 33

38 azure.servicemanagement package Submodules azure.servicemanagement.schedulermanagementservice module class azure.servicemanagement.schedulermanagementservice.schedulermanagementservice(subscription_ cert_file=non host= manag request_session timeout=65) Bases: azure.servicemanagement.servicemanagementclient._servicemanagementclient Note that this class is a preliminary work on Scheduler management. Since it lack a lot a features, final version can be slightly different from the current one. Initializes the scheduler management service. subscription_id: Subscription to manage. cert_file: Path to.pem certificate file (httplib), or location of the certificate in your Personal certificate store (winhttp) in the CURRENT_USERmyCertificateName format. If a request_session is specified, then this is unused. host: Live ServiceClient URL. Defaults to Azure public cloud. request_session: Session object to use for http requests. If this is specified, it replaces the default use of httplib or winhttp. Also, the cert_file parameter is unused when a session is passed in. The session object handles authentication, and as such can support multiple types of authentication:.pem certificate, oauth. For example, you can pass in a Session instance from the requests library. To use.pem certificate authentication with requests library, set the path to the.pem file on the session.cert attribute. timeout: Optional. Timeout for the http request, in seconds. check_job_collection_name(cloud_service_id, job_collection_id) The Check Name Availability operation checks if a new job collection with the given name may be created, or if it is unavailable. The result of the operation is a Boolean true or false. cloud_service_id: The cloud service id job_collection_id: The name of the job_collection_id. create_cloud_service(cloud_service_id, label, description, geo_region) The Create Cloud Service request creates a new cloud service. When job collections are created, they are hosted within a cloud service. A cloud service groups job collections together in a given region. Once a cloud service has been created, job collections can then be created and contained within it. cloud_service_id: The cloud service id label: The name of the cloud service. description: The description of the cloud service. geo_region: The geographical region of the webspace that will be created. create_job(cloud_service_id, job_collection_id, job_id, job) The Create Job request creates a new job. cloud_service_id: The cloud service id job_collection_id: Name of the hosted service. 34 Chapter 8. Indices and tables

39 job_id: The job id you wish to create. job: A dictionary of the payload create_job_collection(cloud_service_id, job_collection_id, plan= Standard ) The Create Job Collection request is specified as follows. Replace <subscription-id> with your subscription ID, <cloud-service-id> with your cloud service ID, and <job-collection-id> with the ID of the job collection you d like to create. There are no default pre-existing job collections every job collection must be manually created. cloud_service_id: The cloud service id job_collection_id: Name of the hosted service. delete_cloud_service(cloud_service_id) The Get Cloud Service operation gets all the resources (job collections) in the cloud service. cloud_service_id: The cloud service id delete_job(cloud_service_id, job_collection_id, job_id) The Delete Job request creates a new job. cloud_service_id: The cloud service id job_collection_id: Name of the hosted service. job_id: The job id you wish to create. delete_job_collection(cloud_service_id, job_collection_id) The Delete Job Collection request is specified as follows. Replace <subscription-id> with your subscription ID, <cloud-service-id> with your cloud service ID, and <job-collection-id> with the ID of the job collection you d like to delete. cloud_service_id: The cloud service id job_collection_id: Name of the hosted service. get_all_jobs(cloud_service_id, job_collection_id) The Get All Jobs operation gets all the jobs in a job collection. The full list of jobs can be accessed by excluding any job ID in the GET call (i.e. /jobs.) The return type is cloud_service_id: The cloud service id job_collection_id: Name of the hosted service. get_cloud_service(cloud_service_id) The Get Cloud Service operation gets all the resources (job collections) in the cloud service. cloud_service_id: The cloud service id get_job(cloud_service_id, job_collection_id, job_id) The Get Job operation gets the details (including the current job status) of the specified job from the specified job collection. The return type is cloud_service_id: The cloud service id job_collection_id: Name of the hosted service. job_id: The job id you wish to create azure package 35

40 get_job_collection(cloud_service_id, job_collection_id) The Get Job Collection operation gets the details of a job collection cloud_service_id: The cloud service id job_collection_id: Name of the hosted service. list_cloud_services() List the cloud services for scheduling defined on the account. azure.servicemanagement.servicebusmanagementservice module class azure.servicemanagement.servicebusmanagementservice.servicebusmanagementservice(subscriptio cert_file=n host= man request_sess timeout=65) Bases: azure.servicemanagement.servicemanagementclient._servicemanagementclient Initializes the service bus management service. subscription_id: Subscription to manage. cert_file: Path to.pem certificate file (httplib), or location of the certificate in your Personal certificate store (winhttp) in the CURRENT_USERmyCertificateName format. If a request_session is specified, then this is unused. host: Live ServiceClient URL. Defaults to Azure public cloud. request_session: Session object to use for http requests. If this is specified, it replaces the default use of httplib or winhttp. Also, the cert_file parameter is unused when a session is passed in. The session object handles authentication, and as such can support multiple types of authentication:.pem certificate, oauth. For example, you can pass in a Session instance from the requests library. To use.pem certificate authentication with requests library, set the path to the.pem file on the session.cert attribute. timeout: Optional. Timeout for the http request, in seconds. check_namespace_availability(name) Checks to see if the specified service bus namespace is available, or if it has already been taken. name: Name of the service bus namespace to validate. create_namespace(name, region) Create a new service bus namespace. name: Name of the service bus namespace to create. region: Region to create the namespace in. delete_namespace(name) Delete a service bus namespace. name: Name of the service bus namespace to delete. get_metrics_data_notification_hub(name, hub_name, metric, rollup, filter_expresssion) Retrieves the list of supported metrics for this namespace and topic name: Name of the service bus namespace. hub_name: Name of the service bus notification hub in this namespace. metric: name of a supported metric 36 Chapter 8. Indices and tables