Drives and files#
A drive holds files in a workspace, like a shared folder.
To use this page, first make sure you can Connect to Nominal and obtain a client.
Create a drive#
create takes the drive’s ID, the name Nominal shows as its title. It can use letters, digits, ., _ and -, and must be unique in the workspace.
let drive = client.drives().create("test-reports").await?;
Fetch a drive#
If you know a drive’s RID or ID, you can fetch it directly without searching.
let drive = client.drives().get("<ri.file-store.instance.drive.identifier>").await?;
// Or by its ID, a name that's unique in its workspace
let drive = client.drives().get_by_id("test-reports").await?;
Find drives#
list returns the workspace’s drives.
for drive in client.drives().list(false).await? { // false leaves out archived drives
println!("{}: {}", drive.id(), drive.rid());
}
Put a file#
Put a file in a drive through the REST API. Follow the Put a file in a drive example to upload it, then place it at a path in the drive.
List a folder#
files returns an object for accessing one drive’s files.
use nominal::core::FileEntry;
let drive_files = client.files(drive.rid());
for entry in drive_files.list("reports", false).await? { // false leaves out removed files
match entry {
FileEntry::File(file) => println!("{} ({} bytes)", file.path(), file.size_bytes()),
FileEntry::Directory(directory) => println!("{}/", directory.path()),
}
}
Note
"" is the drive’s root. Paths have no leading prefix, such as / or C:\.
Download a file#
download returns a reader of a file’s contents.
// The reader streams from a link that expires, so copy from it right away
let mut reader = drive_files.download("reports/run-12.pdf").await?;
let mut local_file = tokio::fs::File::create("run-12.pdf").await?;
tokio::io::copy(&mut reader, &mut local_file).await?;
Move and remove files#
To move or remove a file, pass the RID of its current revision. The call fails if another change has replaced that revision since.
let file = drive_files.get("reports/run-12.pdf").await?;
let revision = file.current_revision_rid().ok_or("no current revision")?;
// Move the file. This fails if a file is already at the new path.
let moved = drive_files.move_file(revision, "archive/run-12.pdf").await?;
// Remove it. list shows it again only with removed files included.
let revision = moved.current_revision_rid().ok_or("no current revision")?;
drive_files.remove(revision).await?;
Restore an earlier revision#
list_revisions lists a file’s revisions, oldest first. restore puts an earlier revision back. While the file is in the drive, the revision replaces its current one. Once the file is removed, restore a revision at any path where no file is yet.
use nominal::core::FileOperationDestination;
let file = drive_files.get("reports/run-12.pdf").await?;
let file_rid = file.managed_file_rid().ok_or("no file RID")?;
let revisions = drive_files.list_revisions(file_rid).await?;
let first = &revisions[0];
// Put the first revision back in place of the file's current one
let current = file.current_revision_rid().ok_or("no current revision")?;
drive_files.restore(first.file_revision_rid(), FileOperationDestination::file_revision_rid(current)).await?;
// For a removed file, find it with list(…, true), then restore one of its revisions at a path where no file is yet
drive_files.restore("<ri.file-store.instance.drive-file-revision.identifier>", "reports/run-12.pdf").await?;
To access your drives from a terminal, see nomctl fs.