1
# Microsoft Azure SDK for Python
3
This project provides a set of Python packages that make it easy to access
4
the Microsoft Azure storage and queue services. For documentation on how
5
to host Python applications on Microsoft Azure, please see the
6
[Microsoft Azure](http://www.windowsazure.com/en-us/develop/python/)
7
Python Developer Center.
9
The SDK supports Python 2.7, 3.3, 3.4.
14
* create and delete tables
15
* create, query, insert, update, merge, and delete entities
17
* create, list, and delete containers, work with container metadata and permissions, list blobs in container
18
* create block and page blobs (from a stream, a file, or a string), work with blob blocks and pages, delete blobs
19
* work with blob properties, metadata, leases, snapshot a blob
21
* create, list, and delete queues, and work with queue metadata
22
* create, get, peek, update, delete messages
24
* Queues: create, list and delete queues; create, list, and delete subscriptions; send, receive, unlock and delete messages
25
* Topics: create, list, and delete topics; create, list, and delete rules
27
* storage accounts: create, update, delete, list, regenerate keys
28
* affinity groups: create, update, delete, list, get properties
30
* hosted services: create, update, delete, list, get properties
31
* deployment: create, get, delete, swap, change configuration, update status, upgrade, rollback
32
* role instance: reboot, reimage
33
* discover addresses and ports for the endpoints of other role instances in your service
34
* get configuration settings and access local resources
35
* get role instance information for current role and other role instances
36
* query and set the status of the current role
39
## Download Source Code
41
To get the source code of the SDK via **git** just type:
43
git clone https://github.com/Azure/azure-sdk-for-python.git
44
cd ./azure-sdk-for-python
48
Alternatively, to get the source code via the Python Package Index (PyPI), type
50
%SystemDrive%\Python27\Scripts\pip.exe install azure
52
You can use these packages against the cloud Microsoft Azure Services, or against
53
the local Storage Emulator (with the exception of Service Bus features).
55
1. To use the cloud services, you need to first create an account with Microsoft Azure. To use the storage services, you need to set the AZURE_STORAGE_ACCOUNT and the AZURE_STORAGE_ACCESS_KEY environment variables to the storage account name and primary access key you obtain from the Azure Portal. To use Service Bus, you need to set the AZURE_SERVICEBUS_NAMESPACE and the AZURE_SERVICEBUS_ACCESS_KEY environment variables to the service bus namespace and the default key you obtain from the Azure Portal.
56
2. To use the Storage Emulator, make sure the latest version of the Microsoft Azure SDK is installed on the machine, and set the EMULATED environment variable to any value ("true", "1", etc.)
61
To ensure a table exists, call **create\_table**:
64
from azure.storage import TableService
65
ts = TableService(account_name, account_key)
66
ts.create_table('tasktable')
69
A new entity can be added by calling **insert\_entity**:
72
from datetime import datetime
73
ts = TableService(account_name, account_key)
74
ts.create_table('tasktable')
78
'PartitionKey' : 'tasksSeattle',
80
'Description': 'Take out the trash',
81
'DueDate': datetime(2011, 12, 14, 12)
86
The method **get\_entity** can then be used to fetch the entity that was just inserted:
89
ts = TableService(account_name, account_key)
90
entity = ts.get_entity('tasktable', 'tasksSeattle', '1')
95
The **create\_container** method can be used to create a
96
container in which to store a blob:
99
from azure.storage import BlobService
100
blob_service = BlobService(account_name, account_key)
101
blob_service.create_container('images')
104
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:
107
from azure.storage import BlobService
108
blob_service = BlobService(account_name, account_key)
109
blob_service.put_block_blob_from_path('images', 'image.png', 'uploads/image.png')
112
To upload an already opened file to a blob named 'image.png', the method **put\_block\_blob\_from\_file** can be used instead:
115
with open('uploads/image.png') as file:
116
blob_service.put_block_blob_from_file('images', 'image.png', file)
119
To upload unicode text, use **put\_block\_blob\_from\_text** which will do the conversion to bytes using the specified encoding.
121
To upload bytes, use **put\_block\_blob\_from\_bytes**.
123
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:
126
from azure.storage import BlobService
127
blob_service = BlobService(account_name, account_key)
128
blob = blob_service.get_blob_to_path('images', 'image.png', 'downloads/image.png')
131
To download to an already opened file, use **get\_blob\_to\_file**.
133
To download to an array of bytes, use **get\_blob\_to\_bytes**.
135
To download to unicode text, use **get\_blob\_to\_text**.
140
The **create\_queue** method can be used to ensure a queue exists:
143
from azure.storage import QueueService
144
queue_service = QueueService(account_name, account_key)
145
queue_service.create_queue('taskqueue')
148
The **put\_message** method can then be called to insert the message into the queue:
151
from azure.storage import QueueService
152
queue_service = QueueService(account_name, account_key)
153
queue_service.put_message('taskqueue', 'Hello world!')
156
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.
159
from azure.storage import QueueService
160
queue_service = QueueService(account_name, account_key)
161
messages = queue_service.get_messages('taskqueue')
162
queue_service.delete_message('taskqueue', messages[0].message_id, messages[0].pop_receipt)
167
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).
169
The **create\_queue** method can be used to ensure a queue exists:
172
from azure.servicebus import ServiceBusService
173
sbs = ServiceBusService(service_namespace, account_key, 'owner')
174
sbs.create_queue('taskqueue')
177
The **send\_queue\_message** method can then be called to insert the message into the queue:
180
from azure.servicebus import ServiceBusService, Message
181
sbs = ServiceBusService(service_namespace, account_key, 'owner')
182
msg = Message('Hello World!')
183
sbs.send_queue_message('taskqueue', msg)
186
It is then possible to call the **receive\_queue\_message** method to dequeue the message.
189
from azure.servicebus import ServiceBusService
190
sbs = ServiceBusService(service_namespace, account_key, 'owner')
191
msg = sbs.receive_queue_message('taskqueue')
196
ServiceBus topics are an abstraction on top of ServiceBus Queues that make pub/sub scenarios easy to implement.
198
The **create\_topic** method can be used to create a server-side topic:
201
from azure.servicebus import ServiceBusService
202
sbs = ServiceBusService(service_namespace, account_key, 'owner')
203
sbs.create_topic('taskdiscussion')
206
The **send\_topic\_message** method can be used to send a message to a topic:
209
from azure.servicebus import ServiceBusService, Message
210
sbs = ServiceBusService(service_namespace, account_key, 'owner')
211
msg = Message('Hello World!')
212
sbs.send_topic_message('taskdiscussion', msg)
215
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.
218
from azure.servicebus import ServiceBusService, Message
219
sbs = ServiceBusService(service_namespace, account_key, 'owner')
220
sbs.create_subscription('taskdiscussion', 'client1')
221
msg = Message('Hello World!')
222
sbs.send_topic_message('taskdiscussion', msg)
223
msg = sbs.receive_subscription_message('taskdiscussion', 'client1')
227
## Service Management
229
### Set-up certificates
231
You need to create two certificates, one for the server (a .cer file) and one for the client (a .pem file). To create the .pem file using [OpenSSL](http://www.openssl.org), execute this:
233
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
235
To create the .cer certificate, execute this:
237
openssl x509 -inform pem -in mycert.pem -outform der -out mycert.cer
239
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](http://manage.windows.com).
241
To initialize the management service, pass in your subscription id and the path to the .pem file.
244
from azure.servicemanagement import ServiceManagementService
245
subscription_id = '00000000-0000-0000-0000-000000000000'
246
cert_file = 'mycert.pem'
247
sms = ServiceManagementService(subscription_id, cert_file)
250
### List Available Locations
253
locations = sms.list_locations()
254
for location in locations:
258
### Create a Storage Service
260
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.
263
name = "mystorageservice"
268
result = sms.create_storage_account(name, desc, label, location=location)
272
### Create a Cloud Service
274
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.
277
name = "myhostedservice"
282
result = sms.create_hosted_service(name, label, desc, location=location)
285
### Create a Deployment
287
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](https://www.windowsazure.com/en-us/develop/php/how-to-guides/powershell-cmdlets/), or with the [cspack commandline tool](http://msdn.microsoft.com/en-us/library/wingg432988.aspx).
290
service_name = "myhostedservice"
291
deployment_name = "v1"
293
package_url = "URL_for_.cspkg_file"
294
configuration = base64.b64encode(open(file_path, 'rb').read('path_to_.cscfg_file'))
297
result = sms.create_deployment(service_name,
304
operation = sms.get_operation_status(result.request_id)
305
print('Operation status: ' + operation.status)
309
** For more examples please see the [Microsoft Azure Python Developer Center](http://www.windowsazure.com/en-us/develop/python) **
313
Be sure to check out the Microsoft Azure [Developer Forums on Stack Overflow](http://go.microsoft.com/fwlink/?LinkId=234489) if you have trouble with the provided code.
315
# Contribute Code or Provide Feedback
317
If you would like to become an active contributor to this project please follow the instructions provided in [Microsoft Azure Projects Contribution Guidelines](http://windowsazure.github.com/guidelines.html).
319
If you encounter any bugs with the library please file an issue in the [Issues](https://github.com/WindowsAzure/azure-sdk-for-python/issues) section of the project.
322
[Microsoft Azure Python Developer Center](http://www.windowsazure.com/en-us/develop/python/)