R6 Class representing files endpoints.

R6 Class representing Files resource.

Super class

sevenbridges2::Resource -> Files

Public fields

URL: List of URL endpoints for this resource.

Methods

Public methods

Files$new()
Files$query()
Files$get()
Files$delete()
Files$copy()
Files$create_folder()
Files$bulk_delete()
Files$bulk_get()
Files$bulk_update()
Files$bulk_edit()
Files$async_bulk_copy()
Files$async_bulk_delete()
Files$async_bulk_move()
Files$async_get_copy_job()
Files$async_get_delete_job()
Files$async_get_move_job()
Files$async_list_file_jobs()
Files$clone()

Method `new()`

Create new Files resource object.

Usage

Files$new(...)

Arguments

...: Other response arguments.

Method `query()`

This call returns a list of files and subdirectories in a specified project or directory within a project, with specified properties that you can access. The project or directory whose contents you want to list is specified as a query parameter in the call. Further properties to filter by can also be specified as query parameters.

Note that this call lists both files and subdirectories in the specified project or directory within a project, but not the contents of the subdirectories.
To list the contents of a subdirectory, make a new call and specify the subdirectory ID as the parent parameter.
For more details, see our API documentation.

Usage

Files$query(
  project = NULL,
  parent = NULL,
  name = NULL,
  metadata = NULL,
  origin = NULL,
  tag = NULL,
  limit = getOption("sevenbridges2")$limit,
  offset = getOption("sevenbridges2")$offset,
  ...
)

Arguments

project: Project identifier (ID) as string or a Project object. Project should not be used together with parent. If parent is used, the call will list the content of the specified folder, within the project to which the folder belongs. If project is used, the call will list the content at the root of the project's files.
parent: The parent folder identifier as string or a File object which must be of type FOLDER. Should not be used together with project. If parent is used, the call will list the content of the specified folder, within the project to which the folder belongs. If project is used, the call will list the content at the root of the project's files.
name: Name of the file. List files with this name. Note that the name must be an exact complete string for the results to match. Multiple names can be represented as a vector.
metadata: List file with this metadata field values. List only files that have the specified value in metadata field. Different metadata fields are represented as a named list. You can also define multiple instances of the same metadata field.
origin: Task object. List only files produced by task.
tag: Filters the files based on the specified tag(s). Each tag must be an exact, complete match, for the results to match. Tags may include spaces. Multiple tags should be provided as a vector of strings. The method will return files that have any of the specified tags.
limit: The maximum number of collection items to return for a single request. Minimum value is 1. The maximum value is 100 and the default value is 50. This is a pagination-specific attribute.
offset: The zero-based starting index in the entire collection of the first item to return. The default value is 0. This is a pagination-specific attribute.
...: Other arguments that can be passed to core api() function as 'fields', etc.

Returns

Collection of File objects.

Examples

\dontrun{
 files_object <- Files$new(auth = auth)

 # Query files in a project
 files_object$query(project = project)
}

Method `get()`

This call returns a single File object with its details. The call returns the file's name, its tags, and all of its metadata. Files are specified by their IDs, which you can obtain by making the API call to list all files in a project.

Usage

Files$get(id, ...)

Arguments

id: The file ID.
...: Other arguments that can be passed to core api() function as 'fields', etc.

Returns

File object.

Examples

\dontrun{
 files_object <- Files$new(auth = auth)

 # Get file using id
 files_object$get(id = id)
}

Method `delete()`

This call removes a file from the Seven Bridges Platform. Files are specified by their IDs, which you can obtain by using Files$query() to list files or by getting a single file using Files$get().

Usage

Files$delete(file, ...)

Arguments

file: File object or file ID.
...: Other arguments that can be passed to core api() function as 'fields', etc.

Examples

\dontrun{
 files_object <- Files$new(auth = auth)

 # Delete a file
 files_object$delete(file = file)
}

Method `copy()`

Copy file/files to the specified project. This call allows you to copy files between projects. Unlike the call to copy a file between projects, this call lets you batch the copy operation and copy a list of files at a time.
More information can be found here here.

Usage

Files$copy(files, destination_project)

Arguments

files: The list of files' IDs or list of File object to copy.
destination_project: Project object or project ID. where you want to copy files into.

Examples

\dontrun{
 files_object <- Files$new(auth = auth)

 # Copy files to a project
 files_object$copy(
               file = file,
               destination_project = project
              )
}

Method `create_folder()`

A method for creating a new folder. It allows you to create a new folder on the Platform within the root folder of a specified project or the provided parent folder. Remember that you should provide either the destination project (as the project parameter) or the destination folder (as the parent parameter), not both.
More information you may find here.

Usage

Files$create_folder(name, parent = NULL, project = NULL)

Arguments

name: The name of the folder you are about to create.
parent: The ID of the parent destination folder or a File object which must be of type FOLDER.
project: The ID of the destination project, or a Project object.

Examples

\dontrun{
 files_object <- Files$new(auth = auth)

 # Create folder in a project
 files_object$create_folder(
                name = name,
                project = project
               )
}

Method `bulk_delete()`

This method facilitates bulk file deletion. It accepts either a list of File objects or a list containing files' IDs.

Usage

Files$bulk_delete(files)

Arguments

files: Either a list of File objects or a list of strings (IDs) representing the files you intend to delete.

Returns

None. The function only displays the IDs of the deleted files in the console.

Examples

\dontrun{
 # Delete two files by providing their IDs
 a$files$bulk_delete(files = list("file_1_ID", "file_2_ID"))
}

\dontrun{
 # Delete two files by providing a list of File objects
 a$files$bulk_delete(files = list(File_Object_1, File_Object_2))
}

Method `bulk_get()`

This call returns the details of multiple specified files, including file names and file metadata. The maximum number of files you can retrieve the details for per call is 100.

Usage

Files$bulk_get(files)

Arguments

files: A list of File objects or list of strings (IDs) of the files you are querying for details.

Returns

Collection (list of File objects).

Examples

\dontrun{
 # Get details of multiple files
 a$files$bulk_get(
               files = list("file_1_ID", "file_2_ID")
              )
}

Method `bulk_update()`

A method that sets new information for specified files, replacing all existing information and erasing omitted parameters.

Usage

Files$bulk_update(files)

Arguments

files: List of File objects.

Details

For each of the specified files, the call sets a new name, new tags, and metadata.

When editing fields in the File objects you wish to update, keep the following in mind:

The name field should be a string representing the new name of the file.
The metadata field should be a named list of key-value pairs. The keys and values should be strings.
The tags field should be an unnamed list of values.

The maximum number of files you can update the details for per call is 100.

Returns

Collection (list of File objects).

Examples

\dontrun{
 # Update details of multiple files
 a$files$bulk_update(
               files = list(File_Object_1, File_Object_2)
              )
}

Method `bulk_edit()`

This method modifies the existing information for specified files or adds new information while preserving omitted parameters.

Usage

Files$bulk_edit(files)

Arguments

files: List of File objects.

Details

For each of the specified files, the call edits its name, tags, and metadata.

When editing fields in the File objects you wish to update, keep the following in mind:

The name field should be a string representing the new name of the file.
The metadata field should be a named list of key-value pairs. The keys and values should be strings.
The tags field should be an unnamed list of values.

The maximum number of files you can update the details for per call is 100.

Returns

Collection (list of File objects).

Examples

\dontrun{
 # Edit details of multiple files
 a$files$bulk_edit(
               files = list(File_Object_1, File_Object_2)
              )
}

Method `async_bulk_copy()`

This call lets you perform a bulk copy of files and folders. Any underlying folder structure will be preserved. You can copy:

to a folder within the same project,
to another project,
to a folder in another project.

Usage

Files$async_bulk_copy(items)

Arguments

items

Nested list of elements containing information about each file/folder to be copied. For each element, you must provide:

file - The ID of the file or folder you are copying. Copying the project root folder is not allowed. Use the API call for listing all files to obtain the ID.
parent - The ID of the folder you are copying files to. It should not be used together with project. If project is used, the items will be imported to the root of the project files. If parent is used, the import will take place into the specified folder, within the project to which the folder belongs.
project - The project you are copying the file to. It should not be used together with parent. If parent is used, the import will take place into the specified folder, within the project to which the folder belongs. If project is used, the items will be imported to the root of the project files.
name - Enter the new name for the file if you want to rename it in the destination folder.

Example of the list:

items <- list(
          list(
            file = '<file-id-1>',
            parent = '<folder-id>'
          ),
          list(
            file = '<file-id-2>',
            project = '<project-id-1>',
            name = 'copied_file.txt'
          ),
          list(
            file = '<file-id-3>',
            parent = '<parent-id-2>',
            name = 'copied_file2.txt'
          )
        )

Read more on how to perform async copy action on multiple files.

Returns

AsyncJob object.

Examples

\dontrun{
 # Copy multiple files
 a$files$async_bulk_copy(
   items = list(
           list(
             file = '<file-id-1>',
             parent = '<folder-id>'
           ),
           list(
             file = '<file-id-2>',
             project = '<project-id-1>',
             name = 'copied_file.txt'
           ),
           list(
             file = '<file-id-3>',
             parent = '<parent-id-2>',
             name = 'copied_file2.txt'
           )
         )
  )
}

Method `async_bulk_delete()`

This call lets you perform an asynchronous bulk deletion of files or folders. Deleting folders which aren't empty is allowed.

Usage

Files$async_bulk_delete(items)

Arguments

items: List of File objects (both file or folder type) or list of IDs of files/folders you want to delete. Read more on how to perform async delete action on multiple files.

Returns

AsyncJob object.

Examples

\dontrun{
 # Delete multiple files
 a$files$async_bulk_delete(
   items = list(file_obj1, file_obj2, "<folder-id-string>", "<file-id>")
 )
}

Method `async_bulk_move()`

This call lets you perform a bulk move operation of files and folders. You can move:

to a root project folder,
to a subfolder within the same project or a different project.

Usage

Files$async_bulk_move(items)

Arguments

items

Nested list of elements containing information about each file/folder to be moved. For each element, you must provide:

file - The ID of the file or folder you are moving. Use the API call for listing all files or folders to obtain the ID.
parent - The ID of the folder you are moving the files to, which should not be used along with project. If project is used, the items will be imported to the root of the project files. If parent is used, the import will take place into the specified folder, within the project to which the folder belongs.
project - The project you are moving the files to. It should not be used together with parent. If parent is used, the import will take place into the specified folder, within the project to which the folder belongs. If project is used, the items will be imported to the root of the project files.
name - Enter the new name for the file or folder if you want to rename at the destination.

Example of the list:

items <- list(
          list(
            file = '<file-id-1>',
            parent = '<folder-id>'
          ),
          list(
            file = '<file-id-2>',
            project = '<project-id-1>',
            name = 'moved_file.txt'
          ),
          list(
            file = '<file-id-3>',
            parent = '<parent-id-2>',
            name = 'moved_file2.txt'
          )
        )

Read more on how to perform async move action on multiple files.

Details

Rules for moving files and folders:

The file ID is preserved after the move.
The folder ID is changed after the move.
The destination must be an existing folder.
If the target folder contains a folder with the same name, the contents of both folders will be merged.
If a file with the same name already exists, the source file will be automatically renamed (by adding a numeric prefix).
You need to have WRITE permissions for both source and destination folders.

Returns

AsyncJob object.

Examples

\dontrun{
 # Move multiple files
 a$files$async_bulk_move(
   items = list(
           list(
             file = '<file-id-1>',
             parent = '<folder-id>'
           ),
           list(
             file = '<file-id-2>',
             project = '<project-id-1>',
             name = 'moved_file.txt'
           ),
           list(
             file = '<file-id-3>',
             parent = '<parent-id-2>',
             name = 'moved_file2.txt'
           )
         )
  )
}

Method `async_get_copy_job()`

This call retrieves the details of an asynchronous bulk copy job. This information will be available for up to a month after the job has been completed.

Usage

Files$async_get_copy_job(job_id)

Arguments

job_id: The ID of the copy job you are querying. This ID can be found within the API response for the call for copying files. The function also accepts an AsyncJob object and extracts the ID.

Returns

AsyncJob object.

Examples

\dontrun{
 # Get details of an async copy job
 a$files$async_get_copy_job(job_id = "job-id")
}

Method `async_get_delete_job()`

This call retrieves the details of an asynchronous bulk deletion job. This information will be available for up to a month after the job has been completed.

Usage

Files$async_get_delete_job(job_id)

Arguments

job_id: The ID of the delete job you are querying. This ID can be found within the API response for the call for deleting files. The function also accepts an AsyncJob object and extracts the ID.

Returns

AsyncJob object.

Examples

\dontrun{
 # Get details of an async delete job
 a$files$async_get_delete_job(job_id = "job-id")
}

Method `async_get_move_job()`

This call retrieves the details of an asynchronous bulk move job. This information will be available for up to a month after the job has been completed.

Usage

Files$async_get_move_job(job_id)

Arguments

job_id: The ID of the move job you are querying. This ID can be found within the API response for the call for moving files. The function also accepts an AsyncJob object and extracts the ID.

Returns

An AsyncJob object containing details of the move job.

Examples

\dontrun{
 # Get details of an async move job
 a$files$async_get_move_job(job_id = "job-id")
}

Method `async_list_file_jobs()`

This call retrieves the details for all asynchronous bulk jobs you have started. This information will be available for up to a month after the job has been completed.

Usage

Files$async_list_file_jobs(
  limit = getOption("sevenbridges2")$limit,
  offset = getOption("sevenbridges2")$offset
)

Arguments

limit: The maximum number of collection items to return for a single request. Minimum value is 1. The maximum value is 100 and the default value is 50. This is a pagination-specific attribute.
offset: The zero-based starting index in the entire collection of the first item to return. The default value is 0. This is a pagination-specific attribute.

Returns

A Collection object containing a list of AsyncJob objects.

Examples

\dontrun{
 # Get details of the first 5 async jobs
 a$files$async_list_file_jobs(limit = 5)
}

Method `clone()`

The objects of this class are cloneable with this method.

Usage

Files$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples


## ------------------------------------------------
## Method `Files$query`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 files_object <- Files$new(auth = auth)

 # Query files in a project
 files_object$query(project = project)
} # }


## ------------------------------------------------
## Method `Files$get`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 files_object <- Files$new(auth = auth)

 # Get file using id
 files_object$get(id = id)
} # }


## ------------------------------------------------
## Method `Files$delete`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 files_object <- Files$new(auth = auth)

 # Delete a file
 files_object$delete(file = file)
} # }


## ------------------------------------------------
## Method `Files$copy`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 files_object <- Files$new(auth = auth)

 # Copy files to a project
 files_object$copy(
               file = file,
               destination_project = project
              )
} # }


## ------------------------------------------------
## Method `Files$create_folder`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 files_object <- Files$new(auth = auth)

 # Create folder in a project
 files_object$create_folder(
                name = name,
                project = project
               )
} # }


## ------------------------------------------------
## Method `Files$bulk_delete`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Delete two files by providing their IDs
 a$files$bulk_delete(files = list("file_1_ID", "file_2_ID"))
} # }

if (FALSE) { # \dontrun{
 # Delete two files by providing a list of File objects
 a$files$bulk_delete(files = list(File_Object_1, File_Object_2))
} # }


## ------------------------------------------------
## Method `Files$bulk_get`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Get details of multiple files
 a$files$bulk_get(
               files = list("file_1_ID", "file_2_ID")
              )
} # }


## ------------------------------------------------
## Method `Files$bulk_update`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Update details of multiple files
 a$files$bulk_update(
               files = list(File_Object_1, File_Object_2)
              )
} # }


## ------------------------------------------------
## Method `Files$bulk_edit`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Edit details of multiple files
 a$files$bulk_edit(
               files = list(File_Object_1, File_Object_2)
              )
} # }


## ------------------------------------------------
## Method `Files$async_bulk_copy`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Copy multiple files
 a$files$async_bulk_copy(
   items = list(
           list(
             file = '<file-id-1>',
             parent = '<folder-id>'
           ),
           list(
             file = '<file-id-2>',
             project = '<project-id-1>',
             name = 'copied_file.txt'
           ),
           list(
             file = '<file-id-3>',
             parent = '<parent-id-2>',
             name = 'copied_file2.txt'
           )
         )
  )
} # }


## ------------------------------------------------
## Method `Files$async_bulk_delete`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Delete multiple files
 a$files$async_bulk_delete(
   items = list(file_obj1, file_obj2, "<folder-id-string>", "<file-id>")
 )
} # }


## ------------------------------------------------
## Method `Files$async_bulk_move`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Move multiple files
 a$files$async_bulk_move(
   items = list(
           list(
             file = '<file-id-1>',
             parent = '<folder-id>'
           ),
           list(
             file = '<file-id-2>',
             project = '<project-id-1>',
             name = 'moved_file.txt'
           ),
           list(
             file = '<file-id-3>',
             parent = '<parent-id-2>',
             name = 'moved_file2.txt'
           )
         )
  )
} # }


## ------------------------------------------------
## Method `Files$async_get_copy_job`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Get details of an async copy job
 a$files$async_get_copy_job(job_id = "job-id")
} # }


## ------------------------------------------------
## Method `Files$async_get_delete_job`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Get details of an async delete job
 a$files$async_get_delete_job(job_id = "job-id")
} # }


## ------------------------------------------------
## Method `Files$async_get_move_job`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Get details of an async move job
 a$files$async_get_move_job(job_id = "job-id")
} # }


## ------------------------------------------------
## Method `Files$async_list_file_jobs`
## ------------------------------------------------

if (FALSE) { # \dontrun{
 # Get details of the first 5 async jobs
 a$files$async_list_file_jobs(limit = 5)
} # }

Super class

Public fields

Methods

Public methods

Method new()

Usage

Arguments

Method query()

Usage

Arguments

Returns

Examples

Method get()

Usage

Arguments

Returns

Examples

Method delete()

Usage

Arguments

Examples

Method copy()

Usage

Arguments

Examples

Method create_folder()

Usage

Arguments

Examples

Method bulk_delete()

Usage

Arguments

Returns

Examples

Method bulk_get()

Usage

Arguments

Returns

Examples

Method bulk_update()

Usage

Arguments

Details

Returns

Examples

Method bulk_edit()

Usage

Arguments

Details

Returns

Examples

Method async_bulk_copy()

Usage

Arguments

Returns

Examples

Method async_bulk_delete()

Usage

Arguments

Returns

Examples

Method async_bulk_move()

Usage

Arguments

Details

Returns

Examples

Method async_get_copy_job()

Usage

Arguments

Returns

Examples

Method async_get_delete_job()

Usage

Arguments

Returns

Examples

Method async_get_move_job()

Usage

Method `new()`

Method `query()`

Method `get()`

Method `delete()`

Method `copy()`

Method `create_folder()`

Method `bulk_delete()`

Method `bulk_get()`

Method `bulk_update()`

Method `bulk_edit()`

Method `async_bulk_copy()`

Method `async_bulk_delete()`

Method `async_bulk_move()`

Method `async_get_copy_job()`

Method `async_get_delete_job()`

Method `async_get_move_job()`

Method `async_list_file_jobs()`

Method `clone()`