Azure Storage¶
A custom storage system for Django using Microsoft 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.
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:
# django < 4.2
DEFAULT_FILE_STORAGE = 'storages.backends.azure_storage.AzureStorage'
STATICFILES_STORAGE = 'custom_storage.custom_azure.PublicAzureStorage'
# django >= 4.2
STORAGES = {
"default": {"BACKEND": "storages.backends.azure_storage.AzureStorage"},
"staticfiles": {"BACKEND": "custom_storage.custom_azure.PublicAzureStorage"},
}
Private VS Public URL¶
The difference between public and private URLs is that private includes the SAS token. With private URLs you can override certain properties stored for the blob by specifying query parameters as part of the shared access signature. These properties include the cache-control, content-type, content-encoding, content-language, and content-disposition. See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-properties#remarks
You can specify these parameters by:
az_storage = AzureStorage()
az_url = az_storage.url(blob_name, parameters={'content_type': 'text/html;'})
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: for static files) to use the Azure backend:
# django < 4.2
DEFAULT_FILE_STORAGE = 'storages.backends.azure_storage.AzureStorage'
STATICFILES_STORAGE = 'storages.backends.azure_storage.AzureStorage'
# django >= 4.2
STORAGES = {
"default": {"BACKEND": "storages.backends.azure_storage.AzureStorage"},
"staticfiles": {"BACKEND": "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 isTrue
AZURE_UPLOAD_MAX_CONN
Number of connections to make when uploading a single file. Default is2
AZURE_CONNECTION_TIMEOUT_SECS
Global connection timeout in seconds. Default is20
AZURE_BLOB_MAX_MEMORY_SIZE
Maximum memory used by a downloaded file before dumping it to disk. Unit is in bytes. Default is2MB
AZURE_URL_EXPIRATION_SECS
Seconds before a URL expires, set toNone
to never expire it. Be aware the container must have public read permissions in order to access a URL without expiration date. Default isNone
AZURE_OVERWRITE_FILES
Overwrite an existing file when it has the same name as the file being uploaded. Otherwise, rename it. Default isFalse
AZURE_LOCATION
Default location for the uploaded files. This is a path that gets prepended to every file name.
AZURE_ENDPOINT_SUFFIX
Defaults tocore.windows.net
. Usecore.chinacloudapi.cn
for azure.cn accounts.
AZURE_CUSTOM_DOMAIN
The custom domain to use for generating URLs for files. For example,www.mydomain.com
ormycdn.azureedge.net
.
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_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"
AZURE_OBJECT_PARAMETERS
Use this to set content settings on all objects. To set these on a per-object basis, subclass the backend and override
AzureStorage.get_object_parameters
.This is a Python
dict
and the possible parameters are:content_type
,content_encoding
,content_language
,content_disposition
,cache_control
, andcontent_md5
.
AZURE_API_VERSION
The api version to use. The default value isNone
.