Cloud Storage¶
Cloud Storage for Firebase keeps user files (photos, videos, documents) in a Google Cloud Storage bucket, with uploads that survive bad networks and access controlled by security rules.
from pyios_firebase.storage import Storage
ref = Storage.storage().reference().child(f"users/{uid}/avatar.jpg")
ref.put_file("/path/to/avatar.jpg", "image/jpeg", callback=on_uploaded)
ref.download_url(lambda url, error: show_image(url))
Installation¶
- Add the
FirebaseStorageSwift package product (Installation). - In the console, open Storage and create the default bucket.
-
Write security rules:
App configuration¶
What the app's build needs for this product. To combine several products, list
them all in one products; see App configuration.
[[tool.kivy.ios.include_files]]
dest = "."
sources = ["GoogleService-Info.plist"]
[tool.kivy.ios.native.swift_packages.Firebase]
url = "https://github.com/firebase/firebase-ios-sdk.git"
requirement = { from = "13.1.1" }
products = ["FirebaseStorage"]
[tool.kivy.ios.xcode.build_settings]
OTHER_LDFLAGS = "$(inherited) -ObjC"
- File > Add Package Dependencies...,
https://github.com/firebase/firebase-ios-sdk.git, and pickFirebaseStorage. - Build Settings > Other Linker Flags: add
-ObjC. - Add
GoogleService-Info.plistto the app target.
References¶
storage = Storage.storage()
root = storage.reference()
avatar = root.child("users/ada/avatar.jpg") # or storage.reference_with_path("users/ada/avatar.jpg")
same = storage.reference_for_url("gs://my-app.appspot.com/users/ada/avatar.jpg")
avatar.name, avatar.full_path, avatar.bucket, avatar.gs_url
avatar.parent(), avatar.root()
A reference is only a path: making one does nothing on the server.
Upload¶
from pyios_firebase.storage import StorageMetadata, StorageTaskStatus
def on_uploaded(metadata, error):
if error is not None:
return show(error.name)
print("Uploaded", metadata.size, "bytes")
# from memory
task = avatar.put_data(jpeg_bytes, "image/jpeg", on_uploaded)
# from a file: large files go in chunks, and resume after a network change
task = avatar.put_file("/path/to/avatar.jpg", callback=on_uploaded)
# with metadata
metadata = StorageMetadata(
content_type="image/jpeg",
cache_control="public, max-age=3600",
custom_metadata={"owner": uid},
)
task = avatar.put_file(path, callback=on_uploaded, metadata=metadata)
Uploading to an existing path replaces the file. Without a content_type,
put_file guesses it from the extension.
Progress, pause, resume, cancel¶
Uploads and downloads return a task:
def on_progress(snapshot):
bar.value = snapshot.fraction_completed # 0.0 to 1.0
handle = task.observe(StorageTaskStatus.PROGRESS, on_progress)
task.observe(StorageTaskStatus.SUCCESS, lambda snapshot: show("Done"))
task.observe(StorageTaskStatus.FAILURE, lambda snapshot: show(snapshot.error.name))
task.pause()
task.resume()
task.cancel() # the callback gets CANCELLED
task.remove_observer(handle)
StorageTaskStatus |
When |
|---|---|
RESUME |
The task starts or resumes |
PROGRESS |
More bytes went through |
PAUSE |
It was paused |
SUCCESS |
It finished |
FAILURE |
It failed (snapshot.error) |
A snapshot has bytes_transferred, total_bytes, fraction_completed,
status, metadata, error and reference. Observers are released when the
task ends.
Download¶
# into memory: max_size guards against huge files
avatar.get_data(5 * 1024 * 1024, lambda data, error: show_image_bytes(data))
# to a file (large files)
avatar.write_to_file("/path/to/cache/avatar.jpg", lambda path, error: show_image_file(path))
# a long-lived https:// URL, for an image widget or to share
avatar.download_url(lambda url, error: setattr(image, "source", url))
A file bigger than max_size fails with DOWNLOAD_SIZE_EXCEEDED.
pyios-firebase checks the bytes received as well: the SDK checks only from
download progress, which a small download may never report.
Download URLs are public
Anyone with a download URL can read the file, whatever the rules say. It
stays valid until you revoke it in the console. Use get_data or
write_to_file for files only the user may read.
Metadata¶
def on_metadata(metadata, error):
print(metadata.content_type, metadata.size, metadata.updated, metadata.custom_metadata)
metadata.cache_control = "public, max-age=300"
metadata.content_language = None # delete this field
metadata.custom_metadata = {**metadata.custom_metadata, "reviewed": "yes"}
avatar.update_metadata(metadata, on_updated)
avatar.get_metadata(on_metadata)
Settable: content_type, cache_control, content_disposition,
content_encoding, content_language, custom_metadata. Read-only:
bucket, path, name, size, md5_hash, generation, metageneration,
time_created, updated. Only the fields you change are sent.
List files¶
def on_list(result, error):
for item in result.items: # files
print(item.full_path)
for prefix in result.prefixes: # "folders"
print(prefix.full_path + "/")
if result.page_token is not None:
folder.list(100, on_list, result.page_token) # the next page
folder = Storage.storage().reference().child(f"users/{uid}")
folder.list(100, on_list)
folder.list_all(on_list) # everything at once: only for small folders
Listing needs rules_version = '2'.
Delete¶
Deleting a missing file gives OBJECT_NOT_FOUND.
Several buckets¶
Retries¶
storage = Storage.storage()
storage.max_upload_retry_time = 60 # seconds (default 600)
storage.max_download_retry_time = 60
storage.max_operation_retry_time = 30 # metadata, delete, list (default 120)
Errors¶
Errors are StorageErrors (name from StorageErrorCode):
StorageErrorCode |
Means |
|---|---|
OBJECT_NOT_FOUND |
No file at that path |
UNAUTHENTICATED |
The rules need a signed-in user |
UNAUTHORIZED |
The rules do not allow it |
QUOTA_EXCEEDED |
The project's quota is used up |
RETRY_LIMIT_EXCEEDED |
It kept failing for longer than the retry time |
DOWNLOAD_SIZE_EXCEEDED |
The file is bigger than max_size |
CANCELLED |
You cancelled the task |
NON_MATCHING_CHECKSUM |
The file was corrupted on the way |
Use the local emulator¶
Emulator quirk: stale metadata after delete
The Storage emulator sends the file's own Cache-Control on metadata
responses, so iOS can cache them: with a cacheable cache_control (say
"public, max-age=300"), get_metadata may still find a file you just
deleted. Use "no-cache" on test files. Production is not affected.