File Browser#
This article outlines the file-browser APIs available in the CTERA Portal, enabling programmatic access to files and directories.
The API supports both synchronous and asynchronous implementations, allowing developers to choose the most suitable model for their integration use case—whether real-time interactions or background processing.
Synchronous API#
User Roles#
The file access APIs are available to the following user roles:
Global Administrators with the Access End User Folders permission enabled.
Team Portal Administrators with the Access End User Folders permission enabled.
End Users, accessing their personal cloud drive folders.
For more information, See: Customizing Administrator Roles
List#
- FileBrowser.listdir(path, depth=None, include_deleted=False)
List Directory
- Parameters:
path (str) – Path
include_deleted (bool,optional) – Include deleted files, defaults to False
"""List directories as a Global Administrator"""
with GlobalAdmin('tenant.ctera.com') as admin:
admin.login('admin-user', 'admin-pass')
"""List all sub-directories"""
for f in admin.files.listdir('Users/John Smith/My Files'):
if f.isFolder:
print({
f.name,
f.href,
f.permalink # a URL that links directly to a specific file
})
"""List directories as a Team Portal Administrator or End User"""
with ServicesPortal('tenant.ctera.com') as user:
user.login('username', 'user-password')
for f in user.files.listdir('My Files/Documents'):
if not f.isFolder:
print({
f.name,
f.href,
f.size,
f.lastmodified,
f.permalink # a URL that links directly to a specific file
})
"""List all deleted files"""
deleted_files = [f.href for f in user.files.listdir('My Files/Documents', include_deleted=True) if f.isDeleted]
print(deleted_files)
- FileBrowser.walk(path, include_deleted=False)
Walk Directory Contents
- Parameters:
path (str) – Path to walk
include_deleted (bool,optional) – Include deleted files, defaults to False
with GlobalAdmin('tenant.ctera.com') as admin:
admin.login('admin-user', 'admin-pass')
for element in admin.files.walk('Users/John Smith/My Files'):
print(element.name) # traverse John Smith's 'My Files' directory and print the name of all files and folders
with ServicesPortal('tenant.ctera.com') as user:
user.login('username', 'user-password')
for element in user.files.walk('My Files/Documents'):
print(element.name) # as a user, traverse all and print the name of all files and folders in 'My Files/Documents'
Versions#
- FileBrowser.versions(path)
List snapshots of a file or directory
- Parameters:
path (str) – Path
"""When logged in as a Global Administrator"""
versions = admin.files.versions('Users/John Smith/My Files/Documents')
for version in versions:
if not version.current:
for item in admin.files.listdir(version): # list items from previous versions
print(version.calculatedTimestamp, item.name)
"""When logged in as a Team Portal Administrator End User"""
versions = user.files.versions('My Files/Documents')
for version in versions:
if not version.current:
for item in user.files.listdir(version): # list items from previous versions
print(version.calculatedTimestamp, item.name)
Download#
- FileBrowser.download(path, destination=None)
Download a file
- Parameters:
path (str) – Path
destination (str,optional) – File destination, if it is a directory, the original filename will be kept, defaults to the default directory
"""When logged in as a Global Administrator"""
admin.files.download('Users/John Smith/My Files/Documents/Sample.docx')
"""When logged in as a Team Portal Administrator End User"""
user.files.download('My Files/Documents/Sample.docx')
- FileBrowser.download_many(target, objects, destination=None)
Download selected files and/or directories as a ZIP archive.
Warning
The provided list of objects is not validated. Only existing files and directories will be included in the resulting ZIP file.
- Parameters:
target (str) – Path to the cloud folder containing the files and directories to download.
objects (list[str]) – List of file and/or directory names to include in the download.
destination (str) – Optional. Path to the destination file or directory. If a directory is provided, the original filename will be preserved. Defaults to the default download directory.
"""When logged in as a Global Administrator"""
admin.files.download_many('Users/John Smith/My Files/Documents', ['Sample.docx', 'Wizard Of Oz.docx'])
"""When logged in as a Team Portal Administrator End User"""
user.files.download_many('My Files/Documents', ['Sample.docx', 'Wizard Of Oz.docx'])
Copy#
- FileBrowser.copy(*paths, destination=None)
Copy one or more files or folders
- Parameters:
paths (list[str]) – List of paths
destination (str) – Destination
"""When logged in as a Team Portal Administrator End User"""
user.files.copy(*['My Files/Documents/Sample.docx', 'My Files/Documents/Burndown.xlsx'], destination='The/quick/brown/fox')
Create Public Link#
- FileBrowser.public_link(path, access='RO', expire_in=30)
Create a public link to a file or a folder
- Parameters:
path (str) – The path of the file to create a link to
access (str,optional) – Access policy of the link, defaults to ‘RO’
expire_in (int,optional) – Number of days until the link expires, defaults to 30
"""
Access:
- RW: Read Write
- RO: Read Only
- NA: No Access
"""
"""When logged in as a Team Portal Administrator End User"""
"""Create a Read Only public link to a file that expires in 30 days"""
user.files.public_link('My Files/Documents/Sample.docx')
"""When logged in as a Team Portal Administrator End User"""
"""Create a Read Write public link to a folder that expires in 45 days"""
user.files.public_link('My Files/Documents/Sample.docx', 'RW', 45)
Get Permalink#
- FileBrowser.permalink(path)
Get Permalink for Path.
- Parameters:
path (str) – Path.
"""When logged in as a Team Portal Administrator End User"""
"""Create permalink to a file"""
user.files.permalink('My Files/Documents/Sample.docx')
"""When logged in as a Team Portal Administrator End User"""
"""Create permalink to a folder"""
user.files.permalink('My Files/Documents')
Create Directories#
- CloudDrive.mkdir(path)
Create a new directory
- Parameters:
path (str) – Directory path
"""When logged in as a Global Administrator"""
admin.files.mkdir('Users/John Smith/My Files/Documents')
"""When logged in as a Team Portal Administrator End User"""
user.files.mkdir('My Files/Documents')
- CloudDrive.makedirs(path)
Create a directory recursively
- Parameters:
path (str) – Directory path
"""When logged in as a Global Administrator"""
admin.files.makedirs('Users/John Smith/My Files/The/quick/brown/fox')
"""When logged in as a Team Portal Administrator End User"""
user.files.makedirs('The/quick/brown/fox')
Rename#
- CloudDrive.rename(path, name)
Rename a file
- Parameters:
path (str) – Path of the file or directory to rename
name (str) – The name to rename to
"""When logged in as a Global Administrator"""
admin.files.rename('Users/John Smith/My Files/Documents/Sample.docx', 'Wizard Of Oz.docx')
"""When logged in as a tenant user or admin"""
user.files.makedirs('My Files/Documents/Sample.docx', 'Wizard Of Oz.docx')
Delete#
- CloudDrive.delete(*paths)
Delete one or more files or folders
- Parameters:
path (str) – Path
"""When logged in as a Global Administrator"""
admin.files.delete(*['Users/John Smith/My Files/Documents/Sample.docx', 'Users/John Smith/My Files/Documents/Wizard Of Oz.docx'])
"""When logged in as a Team Portal Administrator End User"""
user.files.delete(*['My Files/Documents/Sample.docx', 'My Files/Documents/Wizard Of Oz.docx'])
Undelete#
- CloudDrive.undelete(*paths)
Recover one or more files or folders
- Parameters:
path (str) – Path
"""When logged in as a Global Administrator"""
admin.files.undelete(*['Users/John Smith/My Files/Documents/Sample.docx', 'Users/John Smith/My Files/Documents/Wizard Of Oz.docx'])
"""When logged in as a Team Portal Administrator End User"""
user.files.undelete(*['My Files/Documents/Sample.docx', 'My Files/Documents/Wizard Of Oz.docx'])
Move#
- CloudDrive.move(*paths, destination=None)
Move one or more files or folders
- Parameters:
paths (list[str]) – List of paths
destination (str) – Destination
"""When logged in as a Global Administrator"""
admin.files.move(*['Users/John Smith/My Files/Documents/Sample.docx', 'Users/John Smith/My Files/Documents/Wizard Of Oz.docx'], destination='Users/John Smith/The/quick/brown/fox')
"""When logged in as a Team Portal Administrator End User"""
user.files.move(*['My Files/Documents/Sample.docx', 'My Files/Documents/Wizard Of Oz.docx'], destination='The/quick/brown/fox')
Upload#
- CloudDrive.upload(name, size, destination, handle)#
Upload from file handle.
- Parameters:
name (str) – File name.
size (str) – File size.
destination (str) – Path to remote directory.
handle (object) – Handle.
"""When logged in as a Global Administrator"""
admin.files.upload(r'C:\Users\admin\Downloads\Tree.jpg', 'Users/John Smith/My Files/Images')
"""When logged in as a Team Portal Administrator End User"""
user.files.upload(r'C:\Users\admin\Downloads\Tree.jpg', 'My Files/Images')
Managing S3 Credentials#
Starting CTERA 8.0, CTERA Portal features programmatic access via the S3 protocol, also known as CTERA Fusion For more information on how to enable CTERA Fusion and the supported extensions of the S3 protocol, please refer to the following article
The following section includes examples on how to instantiate an S3 client using the Amazon SDK for Python boto3
credentials = user.credentials.s3.create() # if logged in as a user
# credentials = admin.credentials.s3.create(core_types.UserAccount('username', 'domain')) # if logged in as a Global Admin
"""Instantiate the boto3 client"""
client = boto3.client(
's3',
endpoint_url=https://domain.ctera.com:8443, # your CTERA Portal tenant domain
aws_access_key_id=credentials.accessKey,
aws_secret_access_key=credentials.secretKey,
verify=False # disable certificate verification (Optional)
)
"""List Buckets"""
response = client.list_buckets()
for bucket in response['Buckets']:
print(bucket['Name'])
"""Upload a file"""
client.upload_file(r'./document.docx', 'my-bucket-name', 'data-management-document.docx')
"""List files"""
response = client.list_objects_v2(Bucket='my-bucket-name')
for item in response['Contents']:
print(item['Key'], item['LastModified'])
"""List files, using Pagination"""
paginator = client.get_paginator('list_objects_v2')
for page in paginator.paginate(Bucket='my-bucket-name'):
for item in page['Contents']:
print(item['Key'], item['LastModified'])
"""Download a file"""
client.download_file(r'./data-management-document.docx', 'my-bucket-name', 'data-management-document-copy.docx')
# for more information, please refer to the Amazon SDK for Python (boto3) documentation.
Asynchronous API#
- async FileBrowser.handle(path)
Get File Handle.
- Parameters:
path (str) – Path to a file
- async FileBrowser.handle_many(directory, *objects)
Get a Zip Archive File Handle.
- Parameters:
directory (str) – Path to a folder
objects (args) – List of files and folders
- async FileBrowser.download(path, destination=None)
Download a file
- Parameters:
path (str) – Path
destination (str,optional) – File destination, if it is a directory, the original filename will be kept, defaults to the default directory
- async FileBrowser.download_many(target, objects, destination=None)
Download selected files and/or directories as a ZIP archive.
Warning
The provided list of objects is not validated. Only existing files and directories will be included in the resulting ZIP file.
- Parameters:
target (str) – Path to the cloud folder containing the files and directories to download.
objects (list[str]) – List of file and/or directory names to include in the download.
destination (str) – Optional. Path to the destination file or directory. If a directory is provided, the original filename will be preserved. Defaults to the default download directory.
- async FileBrowser.listdir(path, depth=None, include_deleted=False)
List Directory
- Parameters:
path (str) – Path
include_deleted (bool,optional) – Include deleted files, defaults to False
- async FileBrowser.versions(path)
List snapshots of a file or directory
- Parameters:
path (str) – Path
- async FileBrowser.walk(path, include_deleted=False)
Walk Directory Contents
- Parameters:
path (str) – Path to walk
include_deleted (bool,optional) – Include deleted files, defaults to False
- async FileBrowser.public_link(path, access='RO', expire_in=30)
Create a public link to a file or a folder
- Parameters:
path (str) – The path of the file to create a link to
access (str,optional) – Access policy of the link, defaults to ‘RO’
expire_in (int,optional) – Number of days until the link expires, defaults to 30
- async FileBrowser.copy(*paths, destination=None)
Copy one or more files or folders
- Parameters:
paths (list[str]) – List of paths
destination (str) – Destination
- async CloudDrive.move(*paths, destination=None)
Move one or more files or folders
- Parameters:
paths (list[str]) – List of paths
destination (str) – Destination
- async FileBrowser.permalink(path)
Get Permalink for Path.
- Parameters:
path (str) – Path.
- async CloudDrive.upload(name, size, destination, handle)
Upload from file handle.
- Parameters:
name (str) – File name.
size (str) – File size.
destination (str) – Path to remote directory.
handle (object) – Handle.
- async CloudDrive.upload_file(path, destination)
Upload a file.
- Parameters:
path (str) – Local path
destination (str) – Remote path
- async CloudDrive.mkdir(path)
Create a new directory
- Parameters:
path (str) – Directory path
- async CloudDrive.makedirs(path)
Create a directory recursively
- Parameters:
path (str) – Directory path
- async CloudDrive.rename(path, name)
Rename a file
- Parameters:
path (str) – Path of the file or directory to rename
name (str) – The name to rename to
- async CloudDrive.delete(*paths)
Delete one or more files or folders
- Parameters:
path (str) – Path
- async CloudDrive.undelete(*paths)
Recover one or more files or folders
- Parameters:
path (str) – Path
"""Access a Global Administrator"""
async with AsyncGlobalAdmin('global.ctera.com') as admin:
await admin.login('username', 'password')
await admin.portals.browse('corp') # access files in the 'corp' Team Portal tenant
"""Create directories recursively"""
await admin.files.makedirs('Users/John Smith/My Files/the/quick/brown/fox')
"""Create a 'Documents' directory"""
await admin.files.mkdir('Users/John Smith/Documents')
"""Walk 'John Smith's My Files directory"""
async for i in admin.files.walk('Users/John Smith/My Files'):
print(i.name, i.size, i.lastmodified, i.permalink)
"""List all files in a directory"""
documents = [i.name async for i in admin.files.listdir('Users/John Smith/Documents') if i.isfile]
"""Rename a directory"""
await admin.files.rename('Users/John Smith/Documents', 'Documents360')
"""Download"""
await admin.files.download('Users/John Smith/My Files/Sunrise.png')
await admin.files.download('Users/John Smith/My Files/Sunrise.png', 'c:/users/jsmith/downloads/Patagonia.png')
await admin.files.download_many('Users/John Smith/Pictures', ['Sunrise.png', 'Gelato.pptx'])
await admin.files.download_many('Users/John Smith/Pictures', ['Sunrise.png', 'Gelato.pptx'], 'c:/users/jsmith/downloads/Images.zip')
"""Upload"""
await admin.files.upload_file('c:/users/jsmith/downloads/Sunset.png', '/Users/John Smith/Pictures')
"""Public Link"""
url = await admin.files.public_link('Users/John Smith/Pictures/Sunrise.png')
print(url)
"""Access a Team Portal Administrator or End User"""
async with AsyncservicesPortal('tenant.ctera.com') as user:
await user.login('username', 'password')
"""Create directories as an End User"""
await user.files.makedirs('My Files/the/quick/brown/fox') # Create a directory in your own account
"""Create directories as Team Portal Administrator"""
await user.files.makedirs('Users/John Smith/My Files/the/quick/brown/fox') # Create a directory in a user's account