File Operations

Once storage is configured, the following file and directory operations are supported.

Uploading a File

This section describes how to upload files to Oracle Backend with Firebase APIs Object Storage, covering both DBFS and OCI Object Storage backends. Using the platform-specific SDKs, developers can:

Prerequisites

Before uploading files, ensure the following setup is complete:

Uploading Files Flow

File uploads are performed using the Oracle Backend with Firebase APIs SDK or REST API. The operation uses the addDoc() method to create a new document representing the file.

Document Structure

Each uploaded file is represented as a document with fields such as:

{
  "uuid": "<user_id>",
  "url": "<file_url>",
  "storageRef": "<internal_reference>",
  "createdAt": "<timestamp>"
}

The file content is stored in the backend (DBFS or OCI OBJS), and the document includes a reference to the storage location (using the storageRef field).

Uploading Large Objects

When uploading large files:

Console-Based Uploads

Developers can upload files directly using the Oracle Backend with Firebase APIs Console.

The Console UI allows:

Uploaded files are automatically linked to the backend and can be referenced in documents.

See Also: Storage Console Tasks for detailed steps on how to perform upload related tasks

Error Handling

If the upload fails, the service returns a structured error response:

{
  "error": "<error_message>"
}

Common causes for errors include invalid bucket or path, insufficient access rights, or expired or malformed token.

Managing and Monitoring Uploads

Monitoring upload progress involves tracking the state of a file upload while it is in progress, updating the user interface (UI) to reflect the current upload status, and handling potential errors or completion of the upload. This is useful in scenarios where users upload large files, such as images or videos, and you want to display a progress bar or percentage to inform them about the upload status. Upload operations supports managing the upload task using pause, resume, and cancel methods.

Security Considerations

Uploaded files are subject to Object Storage security rules. These rules determine:

Security rules are written in CEL and can use variables like request.auth, request.resource, and path.

The followg example rule restricts uploads to the owner:

match /users/{userid}/photos/{photoid} {
  allow create: if request.auth != null &&
                 request.auth.uid == request.resource.data.uuid;
}

Downloading a File

This chapter explains how developers can retrieve files stored in Oracle Backend with Firebase APIs Object Storage. It covers both DBFS and OCI Object Storage backends, outlines supported download mechanisms, and highlights Console-based capabilities.

Prerequisites

Before downloading files, ensure that:

Downloading Files Flow

Download of storage files can be done using the file reference of the particular object. First step is to create a reference and pass the same to the download method.

Files are downloaded by referencing their storage location, typically stored in a document field such as:

{
  "url": "https://storage.oracle.com/obj123.jpg",
  "storageRef": "obj123"
}

The actual download is performed by issuing a GET request to the file’s URL or using the SDK’s get() method to retrieve the document and extract the file reference.

Public Download URL Generation

Oracle Backend with Firebase APIs supports generating public URLs for files stored in Object Storage.

The following example shows the security rule for public access:

match /users/{userid}/photos/{photoid} {
  allow get: if resource.data.isPublic == true;
}

Note: Public access must be carefully controlled to avoid exposing sensitive data.

Console-Based Downloads

Developers can download files directly using the Oracle Backend with Firebase APIs Console:

See Also: Storage Console Tasks for detailed steps on how to perform download related tasks

Error Handling

If a download fails, the service returns a structured error response:

{
  "error": "<error_message>"
}

Common causes for errors include file not found, invalid or expired signed URL, insufficient access rights, missing or incorrect storageRef.

Security Considerations

Access to files stored in Oracle Backend with Firebase APIs Object Storage is governed by CEL-based security rules. These rules determine whether a user can retrieve (GET) or list files from a collection or path. Developers must ensure that appropriate rules are defined to protect sensitive content and enable valid access.

Rule Structure

Security rules for downloading files typically use the get and list methods:

match /users/{userid}/photos/{photoid} {
  allow get: if <condition>;
  allow list: if <condition>;
}

Rules can evaluate:

Common Download Scenarios

1. Public Access

Allow any user to download a file if it is marked as public:

match /posts/{postId} {
  allow get: if resource.data.isPublic == true;
}

2. Owner-Only Access

Allow only the owner of the file to download it:

match /users/{userid}/photos/{photoid} {
  allow get: if request.auth != null &&
              request.auth.uid == resource.data.uuid;
}

3. Conditional Listing

Allow listing of files only if they are public and the user is authenticated:

match /posts/{postId} {
  allow list: if request.auth != null &&
               resource.data.isPublic == true;
}

Wild Card Rules

Use wildcards to apply rules across multiple documents:

match /tasks/{taskId} {
  allow get: if request.auth != null &&
              taskId.matches('^task_' + request.auth.uid + '_.*$');
}

Advanced Rule Logic

Use CEL functions for complex conditions:

For example:

match /projects/{projectId} {
  allow get: if get(/projects/$(projectId)).data.status == "active";
}

Common Pitfalls

File Management Operations

This section outlines the operations available for managing files stored in Oracle Backend with Firebase APIs Object Storage. It includes listing files, reading metadata, deleting files, and folder creation (if supported). These operations apply to both DBFS and OCI Object Storage backends.

Listing Files

Developers can list files within a specific folder or path using the list method. This operation retrieves all documents representing files under a given collection or subcollection.

The following is an example of a collection path:

users/{userId}/photos
users/{userId}/recipes/{recipeId}/photos

Reading File Metadata

Object Storage supports the use of the following metadata at the application level.

Deleting a File

Using reference of a file, delete operation can be called. The actual file in Object Storage is deleted based on the storageRef.

db.collection("users")
  .doc("Scott")
  .collection("recipes")
  .doc("Cookies")
  .collection("photos")
  .doc("photo1")
  .delete()

Note: Subcollections are not automatically deleted. Manual cleanup may be required.

Directory Operations

Folder creation is backend-dependent. For DBFS, you can have folder-like structures using path conventions. For OCI Object Storage, flat namespace is used wherein folders are simulated using prefixes.

To create a folder:

Example 27-1 Path Convention

bucket/photos/2025/
bucket/recipes/Cookies/photos/

Oracle Backend with Firebase APIs does not expose a dedicated “create folder” API. Folder structures are inferred from document paths and storage references.

Console-Based File Management

The Oracle Backend with Firebase APIs Console supports:

See Also: Storage Console Tasks for detailed steps on how to perform file management tasks

Storage CLI Commands

Prerequisite

Ensure that the setup of CLI for Oracle Backend with Firebase APIs is complete.

See Also: Configure the CLI for detailed steps on how to set up the CLI for Oracle Backend with Firebase APIs