azure sdk for python documentation - read the docs...microsoft azure python developer center 13...

Azure SDK for Python DocumentationRelease 0.20.0

Microsoft

September 30, 2015

Contents

1 Installation: 1

2 Documentation: 3

3 Features: 5

4 System Requirements: 7

5 Need Help?: 9

6 Contributing: 116.1 Contribute Code or Provide Feedback: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

7 Learn More 13

8 Indices and tables 158.1 Blob Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158.2 Queue Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188.3 Table Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198.4 File Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218.5 azure package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228.6 azure.storage package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248.7 azure.storage.auth module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.8 azure.storage.blob package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.9 azure.storage.blob.blobservice module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.10 azure.storage.blob.models module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.11 azure.storage.cloudstorageaccount module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.12 azure.storage.connection module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.13 azure.storage.constants module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.14 azure.storage.file package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.15 azure.storage.file.fileservice module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.16 azure.storage.file.models module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.17 azure.storage.models module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.18 azure.storage.queue package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.19 azure.storage.queue.models module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.20 azure.storage.queue.queueservice module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.21 azure.storage.sharedaccesssignature module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.22 azure.storage.storageclient module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.23 azure.storage.table package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

i

8.24 azure.storage.table.models module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.25 azure.storage.table.tableservice module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.26 azure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Python Module Index 29

ii

CHAPTER 1

Installation:

You can use pip to install the latest released version of azure-storage:

pip install azure-storage

If you want to install azure-storage from source:

git clone git://github.com/Azure/azure-storage-python.gitcd azure-storage-pythonpython setup.py install

If you are looking for Azure Service Bus or the Azure management libraries, please visithttps://github.com/Azure/azure-sdk-for-python

1

https://github.com/Azure/azure-sdk-for-python

Azure SDK for Python Documentation, Release 0.20.0

2 Chapter 1. Installation:

CHAPTER 2

Documentation:

• Blob – (API)

• Queue – (API)

• Table – (API)

• File – (API)

• All Documentation

3


4 Chapter 2. Documentation:

CHAPTER 3

Features:

• Blobs

– 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, deleteblobs

– work with blob properties, metadata, leases, snapshot a blob

• Queues

– create, list, and delete queues, and work with queue metadata

– create, get, peek, update, delete messages

• Tables

– create and delete tables

– create, query, insert, update, merge, and delete entities

• Files

– create, list, and delete shares, work with share metadata, list directories and files in share

– create and delete directories, work with directory properties and metdata

– create files (from a stream, a local file, or a string)

– work with file and directory properties and metadata

5


6 Chapter 3. Features:

CHAPTER 4

System Requirements:

The supported Python versions are 2.7.x, 3.3.x, and 3.4.x To download Python, please visithttps://www.python.org/download/

We recommend Python Tools for Visual Studio as a development environment for developing your applications. Pleasevisit http://aka.ms/python for more information.

7

https://www.python.org/download/

http://aka.ms/python


8 Chapter 4. System Requirements:

CHAPTER 5

Need Help?:

Be sure to check out the Microsoft Azure Developer Forums on Stack Overflow if you have trouble with the providedcode.

9

http://go.microsoft.com/fwlink/?LinkId=234489


10 Chapter 5. Need Help?:

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 MicrosoftAzure Projects Contribution Guidelines.

If you encounter any bugs with the library please file an issue in the Issues section of the project.

11

http://windowsazure.github.com/guidelines.html

http://windowsazure.github.com/guidelines.html

https://github.com/Azure/azure-storage-python/issues


12 Chapter 6. Contributing:

CHAPTER 7

Learn More

Microsoft Azure Python Developer Center

13

http://azure.microsoft.com/en-us/develop/python/


14 Chapter 7. Learn More

CHAPTER 8

Indices and tables

• genindex

• modindex

• search

8.1 Blob Storage

The create_container method can be used to create a container in which to store a blob:

from azure.storage.blob import BlobServiceblob_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_pathcan be used:

from azure.storage.blob import BlobServiceblob_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 anddownloads. 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 usedinstead. The count parameter is optional, but you will get better performance if you specify it. This indicates howmany 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,

)

15


To upload unicode text, use put_block_blob_from_text which will do the conversion to bytes using the specifiedencoding.

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 alreadyexists, the get_blob_to_path method can be used:

from azure.storage.blob import BlobServiceblob_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. Clientscannot 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 containervia 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.blob import BlobServiceblob_service = BlobService(account_name)blob = blob_service.get_blob_to_path(


)

You can get a full URL for the blob (for use in a web browser, etc):

16 Chapter 8. Indices and tables


from azure.storage.blob import BlobServiceblob_service = BlobService(account_name)url = blob_service.make_blob_url(

container_name='images',blob_name='image.png',

)# url is: https://<account_name>.blob.core.windows.net/images/image.png

If you want to give access to a container or blob to a third party without revealing your account key or making thecontainer 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 AccessPolicy, SharedAccessPolicyfrom azure.storage.blob import BlobService, BlobSharedAccessPermissionsblob_service = BlobService(account_name, account_key)ap = AccessPolicy(

expiry='2016-10-12',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 theblob_name parameter.

Alternatively, you can define a named access policy on the server:

from azure.storage import AccessPolicy, SharedAccessPolicy, SignedIdentifierfrom azure.storage.blob import BlobService, BlobSharedAccessPermissionsblob_service = BlobService(account_name, account_key)

policy_name = 'readonlyvaliduntilnextyear'

si = SignedIdentifier()si.id = policy_namesi.access_policy.expiry = '2016-01-01'si.access_policy.permission = BlobSharedAccessPermissions.READidentifiers = 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, callset_container_acl with the new list of signed identifiers. You can pass in None or an empty list to remove all.

8.1. Blob Storage 17


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.blob import BlobServiceblob_service = BlobService(account_name, sas_token=sas_token)blob = blob_service.get_blob_to_path(


)

You can get a full URL for the blob (for use in a web browser, etc):

from azure.storage.blob import BlobServiceblob_service = BlobService(account_name)url = blob_service.make_blob_url(

container_name='images',blob_name='image.png',sas_token=sas_token,

)

8.2 Queue Storage

The create_queue method can be used to ensure a queue exists:

from azure.storage.queue import QueueServicequeue_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.queue import QueueServicequeue_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 themessage id and receipt. This two-step process ensures messages don’t get lost when they are removed from the queue.

from azure.storage.queue import QueueServicequeue_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 accesssignature. The shared access signature includes an access policy, with optional start, expiry and permission.


from azure.storage import AccessPolicy, SharedAccessPolicyfrom azure.storage.queue import QueueService, QueueSharedAccessPermissionsqueue_service = QueueService(account_name, account_key)ap = AccessPolicy(

expiry='2016-10-12',



permission=QueueSharedAccessPermissions.READ,)sas_token = queue_service.generate_shared_access_signature(

'taskqueue',SharedAccessPolicy(ap),

)


from azure.storage import SharedAccessPolicy, SignedIdentifierfrom azure.storage.queue import QueueService, QueueSharedAccessPermissionsqueue_service = QueueService(account_name, account_key)


si = SignedIdentifier()si.id = policy_namesi.access_policy.expiry = '2016-01-01'si.access_policy.permission = QueueSharedAccessPermissions.READidentifiers = SignedIdentifiers()identifiers.signed_identifiers.append(si)

queue_service.set_queue_acl(queue_name='taskqueue',signed_identifiers=identifiers,

)


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, callset_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,

)


from azure.storage.queue import QueueServicequeue_service = QueueService(account_name, sas_token=sas_token)messages = queue_service.peek_messages('taskqueue')

8.3 Table Storage

To ensure a table exists, call create_table:

from azure.storage.table import TableServicetable_service = TableService(account_name, account_key)table_service.create_table('tasktable')

A new entity can be added by calling insert_entity:

8.3. Table Storage 19


from datetime import datetimetable_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 accesssignature. The shared access signature includes an access policy, with optional start, expiry and permission.


from azure.storage import AccessPolicy, SharedAccessPolicyfrom azure.storage.table import TableService, TableSharedAccessPermissionstable_service = TableService(account_name, account_key)ap = AccessPolicy(

expiry='2016-10-12',permission=TableSharedAccessPermissions.QUERY,

)sas_token = table_service.generate_shared_access_signature(

'tasktable',SharedAccessPolicy(ap),

)


from azure.storage import SharedAccessPolicy, SignedIdentifierfrom azure.storage.table import TableService, TableSharedAccessPermissionstable_service = TableService(account_name, account_key)


si = SignedIdentifier()si.id = policy_namesi.access_policy.expiry = '2016-01-01'si.access_policy.permission = TableSharedAccessPermissions.QUERYidentifiers = SignedIdentifiers()identifiers.signed_identifiers.append(si)

table_service.set_queue_acl(table_name='tasktable',signed_identifiers=identifiers,

)


sas_token = table_service.generate_shared_access_signature('tasktable',



SharedAccessPolicy(signed_identifier=policy_name),)

Using a predefined access policy has the advantage that it can be revoked from the server side. To revoke, callset_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,

)


from azure.storage.table import TableServicetable_service = TableService(account_name, sas_token=sas_token)entity = table_service.get_entity('tasktable', 'tasksSeattle', '1')

8.4 File Storage

The create_share method can be used to create a share in which to store a directory or file:

from azure.storage.file import FileServicefile_service = FileService(account_name, account_key)file_service.create_share('myshare')

To create a directory ‘uploads’ within the share, the method create_directory can be used:

from azure.storage.file import FileServicefile_service = FileService(account_name, account_key)file_service.create_directory(

'myshare','uploads',

)

To upload a file ‘localimage.png’ from disk to a file named ‘image.png’, the method put_file_from_path can be used:

from azure.storage.file import FileServicefile_service = FileService(account_name, account_key)file_service.put_file_from_path(


'image.png','localimage.png',max_connections=5,

)

The max_connections parameter is optional, and lets you use multiple parallel connections to perform uploads anddownloads. This parameter is available on the various upload and download methods described below.

To upload an already opened local file to an Azure file named ‘localimage.png’, the method put_file_from_streamcan be used instead. The count parameter is required and indicates how many bytes you want read from the local fileand upload to the Azure file.

with open('localimage.png') as localfile:file_service.put_file_from_stream(


8.4. File Storage 21


'image.png',localfile,count=50000,max_connections=4,

)

To upload unicode text, use put_file_from_text which will do the conversion to bytes using the specified encoding.

To upload bytes, use put_file_from_bytes.

To download a file named ‘image.png’ to a file on disk ‘downloads/localimage.png’, where the ‘downloads’ folderalready exists, the get_file_to_path method can be used:

from azure.storage._file import FileServicefile_service = FileService(account_name, account_key)file = file_service.get_file_to_path(


'image.png','downloads/localimage.png',max_connections=8,

)

To download to an already opened file, use get_file_to_stream.

To download to an array of bytes, use get_file_to_bytes.

To download to unicode text, use get_file_to_text.

8.5 azure package

8.5.1 Subpackages

azure.storage package

Subpackages

azure.storage.blob package

Submodules

azure.storage.blob.blobservice module

azure.storage.blob.models module

Module contents

azure.storage.file package

Submodules



azure.storage.file.fileservice module

azure.storage.file.models module

Module contents

azure.storage.queue package

Submodules

azure.storage.queue.models module

azure.storage.queue.queueservice module

Module contents

azure.storage.table package

Submodules

azure.storage.table.models module

azure.storage.table.tableservice module

Module contents

Submodules

azure.storage.auth module

azure.storage.cloudstorageaccount module

azure.storage.connection module

azure.storage.constants module

azure.storage.models module

azure.storage.sharedaccesssignature module

azure.storage.storageclient module

8.5. azure package 23


Module contents

8.5.2 Module contents

8.6 azure.storage package

8.6.1 Subpackages


Submodules



Module contents


Submodules



Module contents


Submodules



Module contents


Submodules





8.6. azure.storage package 25


Module contents

8.6.2 Submodules









8.7 azure.storage.auth module

8.8 azure.storage.blob package

8.8.1 Submodules




8.9 azure.storage.blob.blobservice module

8.10 azure.storage.blob.models module

8.11 azure.storage.cloudstorageaccount module

8.12 azure.storage.connection module

8.13 azure.storage.constants module

8.14 azure.storage.file package

8.14.1 Submodules




8.15 azure.storage.file.fileservice module

8.16 azure.storage.file.models module

8.17 azure.storage.models module

8.18 azure.storage.queue package

8.18.1 Submodules




8.19 azure.storage.queue.models module

8.20 azure.storage.queue.queueservice module

8.21 azure.storage.sharedaccesssignature module

8.22 azure.storage.storageclient module

8.23 azure.storage.table package

8.23.1 Submodules




8.24 azure.storage.table.models module

8.25 azure.storage.table.tableservice module

8.26 azure

8.26.1 azure package

Subpackages

azure.storage package



Subpackages


Submodules



Module contents


Submodules



Module contents


Submodules



Module contents


Submodules



Module contents

8.26. azure 27


Submodules








Module contents

Module contents


Python Module Index

aazure, 28

29


30 Python Module Index

Index

Aazure (module), 24, 28

31

azure sdk for python documentation - read the docs...microsoft azure python developer center 13...

Documents