/ 
Google-RestApi-2.1.0
River stage zero No dependents
/ Google::RestApi::DriveApi3

NAME

Google::RestApi::DriveApi3 - API to Google Drive API V3.

SYNOPSIS

Basic Setup

use Google::RestApi;
use Google::RestApi::DriveApi3;

# Create the REST API instance
my $rest_api = Google::RestApi->new(
  config_file => '/path/to/config.yaml',
);

# Create the Drive API instance
my $drive = Google::RestApi::DriveApi3->new(api => $rest_api);

Listing and Searching Files

# List files matching a query (uses Google Drive query syntax)
my @files = $drive->list(filter => "name contains 'report'");
my @files = $drive->list(filter => "mimeType = 'application/vnd.google-apps.spreadsheet'");
my @files = $drive->list(filter => "'folder_id' in parents and trashed = false");

# With custom fields
my @files = $drive->list(
  filter => "name contains 'doc'",
  params => { fields => 'files(id, name, mimeType, createdTime)' },
);

Working with Files

# Get a file object by ID
my $file = $drive->file(id => 'file_id_here');

# Get file metadata
my $metadata = $file->get();
my $metadata = $file->get(fields => 'id, name, mimeType, size, webViewLink');

# Copy a file
my $copy = $file->copy(name => 'Copy of Document');

# Update file metadata
$file->update(name => 'New Name', description => 'Updated description');

# Delete a file (moves to trash)
$file->delete();

# Export Google Docs to other formats
my $pdf_content = $file->export(mime_type => 'application/pdf');

File Permissions

# List permissions on a file
my @perms = $file->permissions();

# Create a new permission
my $perm = $file->permission()->create(
  type => 'user',
  role => 'reader',
  email_address => 'user@example.com',
);

# Or share with anyone
$file->permission()->create(
  type => 'anyone',
  role => 'reader',
);

# Get a specific permission
my $perm = $file->permission(id => 'permission_id');
my $details = $perm->get();

# Update permission
$perm->update(role => 'writer');

# Delete permission
$perm->delete();

File Revisions

# List revisions
my @revisions = $file->revisions();

# Get a specific revision
my $rev = $file->revision(id => 'revision_id');
my $details = $rev->get();

# Update revision (keep forever)
$rev->update(keep_forever => 1);

# Delete a revision
$rev->delete();

Comments and Replies

# List comments on a file
my @comments = $file->comments();

# Create a comment
my $comment = $file->comment()->create(
  content => 'Great work on this document!',
);

# Create a comment with quoted content
$file->comment()->create(
  content        => 'This needs revision',
  quoted_content => 'The text being commented on',
);

# Get a comment
my $comment = $file->comment(id => 'comment_id');
my $details = $comment->get();

# Update a comment
$comment->update(content => 'Updated comment text');

# Delete a comment
$comment->delete();

# Work with replies
my @replies = $comment->replies();

# Create a reply
my $reply = $comment->reply()->create(
  content => 'Thanks for the feedback!',
);

# Create a reply that resolves the comment
$comment->reply()->create(
  content => 'Fixed!',
  action  => 'resolve',
);

User and Storage Information

# Get About object
my $about = $drive->about();

# Get user information
my $user = $about->user();
say "Email: $user->{emailAddress}";
say "Name: $user->{displayName}";

# Get storage quota
my $quota = $about->storage_quota();
say "Used: $quota->{usage} bytes";
say "Limit: $quota->{limit} bytes";

# Get supported export formats
my $formats = $about->export_formats();

# Get supported import formats
my $imports = $about->import_formats();

Change Tracking

# Get a Changes object
my $changes = $drive->changes();

# Get starting page token for tracking changes
my $token = $changes->get_start_page_token();

# List changes since a token
my $result = $changes->list(page_token => $token);
for my $change ($result->{changes}->@*) {
  say "File: $change->{fileId}";
  say "Removed: $change->{removed}";
}

# The result includes the new token for next poll
$token = $result->{newStartPageToken};

Shared Drives

# List all shared drives
my @drives = $drive->list_drives();

# Create a new shared drive (requires unique request ID)
my $shared = $drive->create_drive(
  name       => 'Team Documents',
  request_id => 'unique-request-id-123',
);

# Get a shared drive object
my $sd = $drive->shared_drive(id => 'drive_id');

# Get shared drive metadata
my $info = $sd->get();

# Update shared drive
$sd->update(name => 'New Team Name');

# Hide/unhide shared drive
$sd->hide();
$sd->unhide();

# Delete shared drive (must be empty)
$sd->delete();

Utility Operations

# Pre-generate file IDs for later use
my @ids = $drive->generate_ids(count => 10);

# Empty the trash (permanent deletion!)
$drive->empty_trash();

DESCRIPTION

Google::RestApi::DriveApi3 provides a Perl interface to the Google Drive API V3. It enables comprehensive file management including:

  • File operations (list, get, copy, update, delete, export)

  • Permission management (share files with users, groups, domains, or anyone)

  • Revision tracking (view and manage file version history)

  • Comments and replies (collaborate with comments on files)

  • Change tracking (monitor file changes over time)

  • Shared drive management (team drives)

  • User and storage information

It is assumed that you are familiar with the Google Drive API: https://developers.google.com/drive/api/v3/reference

Architecture

The API uses a hierarchical object model where child objects delegate API calls to their parent:

DriveApi3 (top-level)
  |-- about()           -> About
  |-- changes()         -> Changes
  |-- shared_drive()    -> Drive (Shared Drives)
  |-- file(id => ...)   -> File
       |-- permission() -> Permission
       |-- revision()   -> Revision
       |-- comment()    -> Comment
            |-- reply() -> Reply

Each object provides CRUD operations appropriate to its resource type.

NAVIGATION

SUBROUTINES

new(%args)

Creates a new DriveApi3 instance.

my $drive = Google::RestApi::DriveApi3->new(api => $rest_api);

%args consists of:

  • api Google::RestApi: Required. A configured RestApi instance.

  • endpoint <string>: Optional. Override the default Drive API endpoint.

api(%args)

Low-level method to make API calls. You would not normally call this directly unless making a Google API call not currently supported by this framework.

%args consists of:

  • uri <string>: Path segments to append to the Drive endpoint.

  • %args: Additional arguments passed to Google::RestApi's api() (content, params, method, etc).

Returns the response hash from the Google API.

list(%args)

Lists files matching the given query filter.

my @files = $drive->list(filter => "name contains 'report'");

# With custom parameters
my @files = $drive->list(
  filter => "mimeType = 'application/pdf'",
  params => { fields => 'files(id, name, size)', orderBy => 'modifiedTime desc' },
);

# Limit to 2 pages of results
my @files = $drive->list(filter => "name contains 'report'", max_pages => 2);

%args consists of:

  • filter <string>: Required. Google Drive query filter string.

  • max_pages <int>: Optional. Limits the number of pages fetched (default 0 = unlimited).

  • page_callback <coderef>: Optional. Called after each page with the API result hashref. Return true to continue fetching, false to stop. See "PAGE CALLBACKS" in Google::RestApi.

  • params <hashref>: Optional. Additional query parameters.

See https://developers.google.com/drive/api/v3/search-files for query syntax.

Returns a list of file hashrefs with id and name (or custom fields).

filter_files(%args)

Alias for list(). Provided for backward compatibility.

file(%args)

Returns a File object for the given file ID.

my $file = $drive->file(id => 'file_id');

%args consists of:

  • id <string>: Optional. The file ID. Required for most operations.

  • name <string>: Optional. File name (for informational purposes).

about()

Returns an About object for accessing user and storage information.

my $about = $drive->about();
my $user = $about->user();
my $quota = $about->storage_quota();

changes()

Returns a Changes object for tracking file changes.

my $changes = $drive->changes();
my $token = $changes->get_start_page_token();
my $result = $changes->list(page_token => $token);

shared_drive(%args)

Returns a Drive object for working with shared drives.

my $sd = $drive->shared_drive(id => 'drive_id');

%args consists of:

  • id <string>: Optional. The shared drive ID. Required for get/update/delete.

list_drives(%args)

Lists all shared drives accessible to the user.

my @drives = $drive->list_drives();

# With custom parameters and page limit
my @drives = $drive->list_drives(
  max_pages => 2,
  params    => { fields => 'drives(id, name, createdTime)' },
);

max_pages limits the number of pages fetched (default 0 = unlimited). Supports page_callback, see "PAGE CALLBACKS" in Google::RestApi.

Returns a list of drive hashrefs.

create_drive(%args)

Creates a new shared drive.

my $sd = $drive->create_drive(
  name       => 'Team Documents',
  request_id => 'unique-request-id-123',
);

%args consists of:

  • name <string>: Required. The name for the shared drive.

  • request_id <string>: Required. An idempotency key. Using the same request_id will return the same drive rather than creating a duplicate.

  • Additional args are passed as drive metadata.

Returns a Drive object for the created shared drive.

generate_ids(%args)

Generates a set of file IDs that can be used for later file creation.

my @ids = $drive->generate_ids(count => 10);

%args consists of:

  • count <integer>: Number of IDs to generate. Default: 10. Max: 1000.

  • space <string>: The space for the IDs. Default: 'drive'. Can be 'drive' or 'appDataFolder'.

Returns a list of generated file ID strings.

empty_trash()

Permanently deletes all files in the user's trash. Use with caution!

$drive->empty_trash();

Returns the API response (empty on success).

upload_endpoint()

Returns the upload endpoint URL for file uploads. Used internally.

rest_api()

Returns the underlying Google::RestApi instance.

QUERY SYNTAX

The list() method accepts Google Drive query syntax. Common examples:

# By name
"name = 'Exact Name'"
"name contains 'partial'"

# By MIME type
"mimeType = 'application/vnd.google-apps.spreadsheet'"
"mimeType = 'application/pdf'"

# By parent folder
"'folder_id' in parents"

# Exclude trashed files
"trashed = false"

# Combine conditions
"name contains 'report' and mimeType = 'application/pdf' and trashed = false"

# By owner
"'user@example.com' in owners"

# Modified time
"modifiedTime > '2024-01-01T00:00:00'"

See https://developers.google.com/drive/api/v3/search-files for full documentation.

SEE ALSO

AUTHORS

  • Robin Murray mvsjes@cpan.org

COPYRIGHT

Copyright (c) 2019-2026 Robin Murray. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.