Azure Storage
=============

A custom storage system for Django using Windows Azure Storage backend.


Notes
*****

Be aware Azure file names have some extra restrictions. They can't:

  - end with a dot (``.``) or slash (``/``)
  - contain more than 256 slashes (``/``)
  - be longer than 1024 characters

This is usually not an issue, since some file-systems won't
allow this anyway.
There's ``default_storage.get_name_max_len()`` method
to get the ``max_length`` allowed. This is useful
for form inputs. It usually returns
``1024 - len(azure_location_setting)``.
There's ``default_storage.get_valid_name(...)`` method
to clean up file names when migrating to Azure.

Gzipping for static files must be done through Azure CDN.


Install
*******

Install Azure SDK::

  pip install django-storages[azure]


Private VS Public Access
************************

The ``AzureStorage`` allows a single container. The container may have either
public access or private access. When dealing with a private container, the
``AZURE_URL_EXPIRATION_SECS`` must be set to get temporary URLs.

A common setup is having private media files and public static files,
since public files allow for better caching (i.e: no query-string within the URL).

One way to support this is having two backends, a regular ``AzureStorage``
with the private container and expiration setting set, and a custom
backend (i.e: a subclass of ``AzureStorage``) for the public container.

Custom backend::

    # file: ./custom_storage/custom_azure.py
    class PublicAzureStorage(AzureStorage):
        account_name = 'myaccount'
        account_key = 'mykey'
        azure_container = 'mypublic_container'
        expiration_secs = None

Then on settings set::

    DEFAULT_FILE_STORAGE = 'storages.backends.azure_storage.AzureStorage'
    STATICFILES_STORAGE = 'custom_storage.custom_azure.PublicAzureStorage'


Settings
********

The following settings should be set within the standard django
configuration file, usually `settings.py`.

Set the default storage (i.e: for media files) and the static storage
(i.e: fo static files) to use the azure backend::

    DEFAULT_FILE_STORAGE = 'storages.backends.azure_storage.AzureStorage'
    STATICFILES_STORAGE = 'storages.backends.azure_storage.AzureStorage'

The following settings are available:

``AZURE_ACCOUNT_NAME``

    This setting is the Windows Azure Storage Account name, which in many cases
    is also the first part of the url for instance: http://azure_account_name.blob.core.windows.net/
    would mean::

       AZURE_ACCOUNT_NAME = "azure_account_name"

``AZURE_ACCOUNT_KEY``

    This is the private key that gives Django access to the Windows Azure Account.

``AZURE_CONTAINER``

    This is where the files uploaded through Django will be uploaded.
    The container must be already created, since the storage system will not attempt to create it.

``AZURE_SSL``

    Set a secure connection (HTTPS), otherwise it makes an insecure connection (HTTP). Default is ``True``

``AZURE_UPLOAD_MAX_CONN``

    Number of connections to make when uploading a single file. Default is ``2``

``AZURE_CONNECTION_TIMEOUT_SECS``

    Global connection timeout in seconds. Default is ``20``

``AZURE_BLOB_MAX_MEMORY_SIZE``

    Maximum memory used by a downloaded file before dumping it to disk. Unit is in bytes. Default is ``2MB``

``AZURE_URL_EXPIRATION_SECS``

    Seconds before a URL expires, set to ``None`` to never expire it.
    Be aware the container must have public read permissions in order
    to access a URL without expiration date. Default is ``None``

``AZURE_OVERWRITE_FILES``

    Overwrite an existing file when it has the same name as the file being uploaded.
    Otherwise, rename it. Default is ``False``

``AZURE_LOCATION``

    Default location for the uploaded files. This is a path that gets prepended to every file name.

``AZURE_EMULATED_MODE``

    Whether to use the emulator (i.e Azurite). Defaults to False.

``AZURE_ENDPOINT_SUFFIX``

    The host base component of the url, minus the account name. Defaults
    to Azure (``core.windows.net``). Override this to use the China cloud
    (``core.chinacloudapi.cn``).

``AZURE_CUSTOM_DOMAIN``

    The custom domain to use. This can be set in the Azure Portal. For
    example, ``www.mydomain.com`` or ``mycdn.azureedge.net``.

    It may contain a ``host:port`` when using the emulator
    (``AZURE_EMULATED_MODE = True``).

``AZURE_CONNECTION_STRING``

    If specified, this will override all other parameters.
    See http://azure.microsoft.com/en-us/documentation/articles/storage-configure-connection-string/
    for the connection string format.

``AZURE_CUSTOM_CONNECTION_STRING``

    This is similar to ``AZURE_CONNECTION_STRING``, but it's used
    when generating the file's URL. A custom domain or CDN may be
    specified here instead of within ``AZURE_CONNECTION_STRING``.
    Defaults to ``AZURE_CONNECTION_STRING``'s value.

``AZURE_TOKEN_CREDENTIAL``

    A token credential used to authenticate HTTPS requests. The token value
    should be updated before its expiration.


``AZURE_CACHE_CONTROL``

    A variable to set the Cache-Control HTTP response header. E.g. 
    ``AZURE_CACHE_CONTROL = "public,max-age=31536000,immutable"``
