233 строки
6.9 KiB
ReStructuredText
233 строки
6.9 KiB
ReStructuredText
Microsoft Azure Storage SDK for Python
|
|
======================================
|
|
|
|
.. image:: https://travis-ci.org/Azure/azure-storage-python.svg
|
|
:target: https://travis-ci.org/Azure/azure-storage-python
|
|
.. image:: https://img.shields.io/codecov/c/github/azure/azure-storage-python.svg
|
|
:target: https://codecov.io/gh/Azure/azure-storage-python
|
|
|
|
This project provides a client library in Python that makes it easy to
|
|
consume Microsoft Azure Storage services. For documentation please see
|
|
the Microsoft Azure `Python Developer Center`_ and our `API Reference`_ (also available on `readthedocs`_).
|
|
|
|
If you are looking for the Service Bus or Azure Management
|
|
libraries, please visit
|
|
https://github.com/Azure/azure-sdk-for-python.
|
|
|
|
|
|
Compatibility
|
|
=============
|
|
|
|
**IMPORTANT**: If you have an earlier version of the azure package
|
|
(version < 1.0), you should uninstall it before installing this package.
|
|
|
|
You can check the version using pip:
|
|
|
|
.. code:: shell
|
|
|
|
pip freeze
|
|
|
|
If you see azure==0.11.0 (or any version below 1.0), uninstall it first then install it again:
|
|
|
|
.. code:: shell
|
|
|
|
pip uninstall azure
|
|
pip install azure
|
|
|
|
If you are upgrading from a version older than 0.30.0, see the upgrade doc, the
|
|
usage samples in the samples directory, and the ChangeLog and BreakingChanges.
|
|
|
|
If you are encountering `problems`_ installing azure storage on Azure Web Apps,
|
|
`upgrading pip`_ might help.
|
|
|
|
**IMPORTANT**: If you have an earlier version of the azure-storage package
|
|
(version <= 0.36.0), you should uninstall it before installing the new split packages.
|
|
|
|
You can check the version using pip:
|
|
|
|
.. code:: shell
|
|
|
|
pip freeze
|
|
|
|
If you see azure-storage==0.36.0 (or any version below 0.36.0), uninstall it first:
|
|
|
|
.. code:: shell
|
|
|
|
pip uninstall azure-storage
|
|
|
|
Features
|
|
========
|
|
|
|
- Blob
|
|
|
|
- Create/Read/Update/Delete Containers
|
|
- Create/Read/Update/Delete Blobs
|
|
- Advanced Blob Operations
|
|
|
|
- Queue
|
|
|
|
- Create/Delete Queues
|
|
- Insert/Peek Queue Messages
|
|
- Advanced Queue Operations
|
|
|
|
- Files
|
|
|
|
- Create/Update/Delete Shares
|
|
- Create/Update/Delete Directories
|
|
- Create/Read/Update/Delete Files
|
|
- Advanced File Operations
|
|
|
|
Getting Started
|
|
===============
|
|
|
|
Download
|
|
--------
|
|
|
|
The Azure Storage SDK for Python is composed of 5 packages:
|
|
|
|
- azure-storage-blob
|
|
|
|
- Contains the blob service APIs.
|
|
|
|
- azure-storage-file
|
|
|
|
- Contains the file service APIs.
|
|
|
|
- azure-storage-queue
|
|
|
|
- Contains the queue service APIs.
|
|
|
|
- azure-storage-common
|
|
|
|
- Contains common code shared by blob, file and queue.
|
|
|
|
- azure-storage-nspkg
|
|
|
|
- Owns the azure.storage namespace, user should not use this directly.
|
|
|
|
**Note**: prior to and including version 0.36.0, there used to be a single package (azure-storage) containing all services.
|
|
It is no longer supported, and users should install the 3 before-mentioned service packages individually, depending on the need.
|
|
In addition, the **table** package is no longer releasing under the azure-storage namespace, please refer to `cosmosdb`_.
|
|
|
|
Option 1: Via PyPi
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
To install via the Python Package Index (PyPI), type:
|
|
::
|
|
|
|
pip install azure-storage-blob
|
|
pip install azure-storage-file
|
|
pip install azure-storage-queue
|
|
|
|
Option 2: Source Via Git
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To get the source code of the SDK via git just type:
|
|
|
|
::
|
|
|
|
git clone git://github.com/Azure/azure-storage-python.git
|
|
|
|
cd ./azure-storage-python/azure-storage-nspkg
|
|
python setup.py install
|
|
|
|
cd ../azure-storage-common
|
|
python setup.py install
|
|
|
|
cd ../azure-storage-blob
|
|
python setup.py install
|
|
|
|
|
|
Replace azure-storage-blob with azure-storage-file or azure-storage-queue, to install the other services.
|
|
|
|
Option 3: Source Zip
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Download a zip of the code via GitHub or PyPi. Then follow the same instructions in option 2.
|
|
|
|
Minimum Requirements
|
|
--------------------
|
|
|
|
- Python 2.7, 3.3, 3.4, 3.5, or 3.6.
|
|
- See setup.py for dependencies
|
|
|
|
Usage
|
|
-----
|
|
|
|
To use this SDK to call Microsoft Azure storage services, you need to
|
|
first `create an account`_.
|
|
|
|
Logging
|
|
-----------
|
|
|
|
To make debugging easier, it is recommended to turn on logging for the logger named 'azure.storage'.
|
|
Here are two example configurations:
|
|
|
|
.. code:: python
|
|
|
|
# Basic configuration: configure the root logger, including 'azure.storage'
|
|
logging.basicConfig(format='%(asctime)s %(name)-20s %(levelname)-5s %(message)s', level=logging.INFO)
|
|
|
|
.. code:: python
|
|
|
|
# More advanced configuration allowing more control
|
|
logger = logging.getLogger('azure.storage')
|
|
handler = logging.StreamHandler()
|
|
formatter = logging.Formatter('%(asctime)s %(name)-20s %(levelname)-5s %(message)s')
|
|
handler.setFormatter(formatter)
|
|
logger.addHandler(handler)
|
|
logger.setLevel(logging.INFO)
|
|
|
|
Here is how we use the logging levels, it is recommended to use INFO:
|
|
|
|
- DEBUG: log strings to sign
|
|
- INFO: log outgoing requests and responses, as well as retry attempts
|
|
- WARNING: not used
|
|
- ERROR: log calls that still failed after all the retries
|
|
|
|
Code Sample
|
|
-----------
|
|
|
|
See the samples directory for blob, queue, and file usage samples.
|
|
|
|
Need Help?
|
|
==========
|
|
|
|
Be sure to check out the Microsoft Azure `Developer Forums on MSDN`_ or
|
|
the `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 `Azure Projects Contribution
|
|
Guidelines`_. You can find more details for contributing in the `CONTRIBUTING.md doc`_.
|
|
|
|
If you encounter any bugs with the library, please file an issue in the
|
|
`Issues`_ section of the project.
|
|
|
|
Learn More
|
|
==========
|
|
|
|
- `Python Developer Center`_
|
|
- `Azure Storage Service`_
|
|
- `Azure Storage Team Blog`_
|
|
- `API Reference`_
|
|
|
|
.. _Python Developer Center: http://azure.microsoft.com/en-us/develop/python/
|
|
.. _API Reference: https://docs.microsoft.com/en-us/python/api/overview/azure/storage/client?view=azure-python
|
|
.. _readthedocs: https://azure-storage.readthedocs.io/
|
|
.. _here: https://github.com/Azure/azure-storage-python/archive/master.zip
|
|
.. _create an account: https://account.windowsazure.com/signup
|
|
.. _Developer Forums on MSDN: http://social.msdn.microsoft.com/Forums/windowsazure/en-US/home?forum=windowsazuredata
|
|
.. _Developer Forums on Stack Overflow: http://stackoverflow.com/questions/tagged/azure+windows-azure-storage
|
|
.. _Azure Projects Contribution Guidelines: http://azure.github.io/guidelines.html
|
|
.. _Issues: https://github.com/Azure/azure-storage-python/issues
|
|
.. _Azure Storage Service: http://azure.microsoft.com/en-us/documentation/services/storage/
|
|
.. _Azure Storage Team Blog: http://blogs.msdn.com/b/windowsazurestorage/
|
|
.. _CONTRIBUTING.md doc: CONTRIBUTING.md
|
|
.. _problems: https://github.com/Azure/azure-storage-python/issues/219
|
|
.. _upgrading pip: https://docs.microsoft.com/en-us/visualstudio/python/managing-python-on-azure-app-service
|
|
.. _cosmosdb: https://github.com/Azure/azure-cosmosdb-python
|