drive_find: Find files on Google Drive

Description

This is the closest googledrive function to what you can do at https://drive.google.com: by default, you just get a listing of your files. You can also search in various ways, e.g., filter by file type or ownership or even work with Team Drive files, if you have access. This is a very powerful function. Together with the more specific drive_get(), this is the main way to identify files to target for downstream work.

Note: Team Drives are only available to users of certain enhanced Google services, such as G Suite Enterprise, G Suite Business, or G Suite for Education.

Usage

drive_find(pattern = NULL, trashed = FALSE, type = NULL,
  n_max = Inf, team_drive = NULL, corpus = NULL, ...,
  verbose = TRUE)

Arguments

pattern

Character. If provided, only the items whose names match this regular expression are returned. This is implemented locally on the results returned by the API.

trashed

Logical. Whether to search files that are not in the trash (trashed = FALSE, the default), only files that are in the trash (trashed = TRUE), or to search regardless of trashed status (trashed = NA).

type

Character. If provided, only files of this type will be returned. Can be anything that drive_mime_type() knows how to handle. This is processed by googledrive and sent as a query parameter.

n_max

Integer. An upper bound on the number of items to return. This applies to the results requested from the API, which may be further filtered locally, via the pattern argument.

team_drive

Anything that identifies one specific Team Drive: its name, its id or URL marked with as_id(), or a dribble. Is pre-processed with as_team_drive(). Read more about Team Drives.

corpus

Character, specifying the search collection. Only relevant in the Team Drives context. If specified, must be one of "user", "all", or "domain". Read more about Team Drives.

...

Other parameters to pass along in the request. The most likely candidate is q. See below and the API's Search for files and folders guide.

verbose

Logical, indicating whether to print informative messages (default TRUE).

Value

An object of class dribble, a tibble with one row per item.

File type

The type argument is pre-processed with drive_mime_type(), so you can use a few shortcuts and file extensions, in addition to full-blown MIME types. googledrive forms a search clause to pass to q.

Search parameters

Do advanced search on file properties by providing search clauses to the q parameter that is passed to the API via .... Multiple q clauses or vector-valued q are combined via 'and'.

Trash

By default, drive_find() sets trashed = FALSE and does not include files in the trash. Literally, it adds q = "trashed = false" to the query. To search only the trash, set trashed = TRUE. To see files regardless of trash status, set trashed = NA, which adds q = "(trashed = true or trashed = false)" to the query.

Sort order

By default, drive_find() sends orderBy = "recency desc", so the top files in your result have high "recency" (whatever that means). To suppress sending orderBy at all, do drive_find(orderBy = NULL). The orderBy parameter accepts sort keys in addition to recency, which are documented in the files.list endpoint. googledrive translates a snake_case specification of order_by into the lowerCamel form, orderBy.

Team Drives

If you have access to Team Drives, you'll know. Use team_drive or corpus to search one or more Team Drives or a domain. See Access Team Drives for more.

Examples

Run this code

# NOT RUN {
# list "My Drive" w/o regard for folder hierarchy
drive_find()

# filter for folders, the easy way and the hard way
drive_find(type = "folder")
drive_find(q = "mimeType = 'application/vnd.google-apps.folder'")

# filter for Google Sheets, the easy way and the hard way
drive_find(type = "spreadsheet")
drive_find(q = "mimeType='application/vnd.google-apps.spreadsheet'")

# files whose names match a regex
drive_find(pattern = "jt")

# search for files located directly in your root folder
drive_find(q = "'root' in parents")
# FYI: this is equivalent to
drive_ls("~/")

# control page size or cap the number of files returned
drive_find(pageSize = 50)
# all params passed through `...` can be camelCase or snake_case
drive_find(page_size = 50)
drive_find(n_max = 58)
drive_find(page_size = 5, n_max = 15)

# various ways to specify q search clauses
# multiple q's
drive_find(q = "name contains 'TEST'",
           q = "modifiedTime > '2017-07-21T12:00:00'")
# vector q
drive_find(q = c("starred = true", "visibility = 'anyoneWithLink'"))

# default `trashed = FALSE` excludes files in the trash
# `trashed = TRUE` consults ONLY file in the trash
drive_find(trashed = TRUE)
# `trashed = NA` disregards trash status completely
drive_find(trashed = NA)

# suppress the default sorting on recency
drive_find(order_by = NULL, n_max = 5)

# sort on various keys
drive_find(order_by = "quotaBytesUsed", n_max = 5)
drive_find(order_by = "modifiedByMeTime", n_max = 5)
# }
# NOT RUN {
# }

Run the code above in your browser using DataCamp Workspace