SYNOPSIS

my $gd_v3 = Net::Google::Drive::Simple->new( 'version' => 3 );
# same as:
my $gd_v3 = Net::Google::Drive::Simple::V3->new();

$gd->changes(...);
$gd->create_comment(...);
$gd->delete_file(...);

DESCRIPTION

This is a complete implementation of the Google Drive API V3. You can use all the documented methods below.

Uploading files over 5 MB require reading the UPLOADING section below.

METHODS

`new`

my $gd = Net::Google::Drive::Simple::V3->new();

Create a new instance.

You can also create an instance using Net::Google::Drive::Simple:

my $gd = Net::Google::Drive::Simple->new( 'version' => 3 );

`about`

my $about = $gd->about({%params});

This serves the path to /about.

It's also referred to as about.get.

You can read about the parameters on the Google Drive API page.

`getStartPageToken`

my $data = $gd->getStartPageToken({%params});

Parameters are optional.

This serves the path to /changes/startPageToken.

This is also known as changes_getStartPageToken.

You can read about the parameters on the Google Drive API page.

`changes`

my $changes_list = $gd->changes({%params});

This serves the path to /changes.

This is also known as changes.list.

You can read about the parameters on the Google Drive API page.

`watch_changes`

my $data = $gd->watch_changes({%params});

Parameters are optional.

This serves the path to /changes/watch.

This is also known as changes.watch.

You can read about the parameters on the Google Drive API page.

`stop_channels`

$gd->stop_channels({%params});

This serves the path to /channels/stop.

This is also known as channels.stop.

You can read about the parameters on the Google Drive API page.

`create_comment`

my $comment = $gd->create_comment( $fileId, {%params} );

This serves the path to /files/$fileId/comments.

This is also known as comments.create.

You can read about the parameters on the Google Drive API page.

`delete_comment( $fileId, $commentId )`

$gd->delete_comment( $fileId, $commentId );

This serves the path to /files/$fileId/comments/$commentId.

This is also known as comments.delete.

You can read about the parameters on the Google Drive API page.

`get_comment( $fileId, $commentId, $params )`

my $comment = $gd->get_comment( $fileId, $commentId, {%params} );

This serves the path to /files/$fileId/comments/$commentId.

This is also known as comments.get.

You can read about the parameters on the Google Drive API page.

`comments`

my $comments = $gd->comments( $fileId, {%params} );

This serves the path to /files/$fileId/comments.

This is also known as comments.list.

You can read about the parameters on the Google Drive API page.

`update_comment`

my $comment = $gd->update_comment( $fileId, $commentId, {%params} );

This serves the path to /files/$fileId/comments/$commentId.

This is also known as comments.update.

You can read about the parameters on the Google Drive API page.

`copy_file`

my $file = $gd->copy_file( $fileId, {%params} );

This serves the path to /files/$fileId/copy.

This is also known as files.copy.

You can read about the parameters on the Google Drive API page.

`create_folder`

my $folder_data = $gd->create_folder( $name, $parent_id );
print $folder_data->{'id'};

This method is just for convenience. It's effectively:

$self->create_file({
    'name'     => $name,
    'mimeType' => "application/vnd.google-apps.folder",
    'parents'  => [$parent_id],
});

`create_file`

my $file = $gd->create_file({%params});

This serves the path to /files.

This is also known as files.create.

You can read about the parameters on the Google Drive API page.

This one is ONLY for creating metadata for a file. It will not upload any content. If you want to set content, use the following methods below: upload_media_file(), upload_multipart_file, create_resumable_upload(), upload_file_content_single(), upload_file_content_multiple(), and upload_file_content_iterator.

Read more about uploading under UPLOADING below. If you want a simple way to upload files, check upload_file().

`upload_file`

my $result = $gd->upload_file( $filename, {%params} );

Parameters are optional.

This method combines the different mechanisms for uploading a file and makes it easy to upload large files. There are disadvantages, but for most cases, this method should serve you well.

Read more about uploading under UPLOADING below.

`upload_media_file`

my $file = $gd->upload_media_file( $filename, {%params} );

Parameters are optional.

This serves the path to /files.

This is also known as files.create.

You can read about the parameters on the Google Drive API page.

This one is for uploading a file without metadata. File size limitation is 5 MB and we read it 4K at a time.

Read more about uploading under UPLOADING below.

`upload_multipart_file`

my $file = $gd->upload_multipart_file( $filename, {%params} );

Parameters are optional.

This serves the path to /files.

This is also known as files.create.

You can read about the parameters on the Google Drive API page.

This one is for uploading both a file and its metadata. File size limitation is 5 MB and we read the entire file into memory at once before uploading.

Read more about uploading under UPLOADING below.

`create_resumable_upload_for`

my $upload_id = $gd->upload_multimedia_file( $filename, {%params} );

Parameters are optional.

This serves the path to /files.

This is also known as files.create.

You can read about the parameters on the Google Drive API page.

This method starts a resumable upload for a specific file on disk. It provides you with an ID that you can then feed to the following methods: upload_file_content_single(), upload_file_content_multiple(), and upload_file_content_iterator().

File size limitation for any resumable upload is 5120 GB and create_resumable_upload_for() checks for this limit.

Read more about uploading under UPLOADING below.

`create_resumable_upload`

my $upload_id = $gd->create_resumable_upload( {%params} );

Parameters are optional.

This serves the path to /files.

This is also known as files.create.

You can read about the parameters on the Google Drive API page.

This method starts a resumable upload. It provides you with an ID that you can then feed to the following methods: upload_file_content_single(), upload_file_content_multiple(), and upload_file_content_iterator().

File size limitation for any resumable upload is 5120 GB and create_resumable_upload_for() checks for this limit.

Read more about uploading under UPLOADING below.

`upload_file_content_single`

my $result = $gd->upload_file_content_single( $upload_uri, $filename );

This serves the path to the upload URI you provide it.

There is a limitation of 5120 GB for the file. With this method, we feed the file 4K at a time.

Read more about uploading under UPLOADING.

`upload_file_content_multiple`

my $result = $gd->upload_file_content_multiple( $upload_uri, $file, $chunk_size );

Chunk size is optional, defaults to 10 MB.

This serves the path to the upload URI you provide it.

There is a limitation of 5120 GB for the file. With this method, we feed the file in chunks defined by the chunk size you provide or the default 10 MB.

Read more about uploading under UPLOADING.

The difference between upload_file_content_single() and upload_file_content_multiple() is that this variation will work better for long files, in theory. More importantly, it uses upload_file_content_iterator() which really allows you to control matters.

`upload_file_content_iterator`

use JSON qw< from_json >;

my $iter_cb = $gd->upload_file_content_iterator( $filename, $file, $chunk_size );

while ( my $request = $iter->() ) {
    my $response = handle_http_request($request);
    # anything else - we're confused, so it's an error no matter what

    # 200 - Done!
    if ( $response->code() == 200 ) {
        return from_json( $response->decoded_content() );
    }

    # 308 - Continue uploading!
    # anything else - not what we're expecting
    if ( $response->code() != 308 ) {
        die "Error: " . $response->code();
    }
}

Chunk size is optional, defaults to 10 MB.

This returns a callback that allows you to control how to handle the uploading. It's especially valuable when you want to connect the uploading to an event loop like IO::Async, POE, AnyEvent, or others.

The callback returns an object of HTTP::Request which represent the request that needs to be done. Once requested, if you receive a 308, it means you can continue, and if you receive a 200, it means you are done uploading.

There is a limitation of 5120 GB for the file. With this method, we feed the file in chunks defined by the chunk size you provide or the default 10 MB.

Read more about uploading under UPLOADING.

`delete_file`

$gd->delete_file( $fileId, {%params} );

Parameters are optional.

This serves the path to /files/$fileId.

This is also known as files.delete.

You can read about the parameters on the Google Drive API page.

`export_file`

my $file_content_in_bytes = $gd->export_file( $fileId, {%params} );

This serves the path to /files/$fileId/export.

This is also known as files.export.

You can read about the parameters on the Google Drive API page.

`generateIds`

my $data = $gd->generateIds({%params});

Parameters are optional.

This serves the path to /files/generateIds.

This is also known as files.generateIds.

You can read about the parameters on the Google Drive API page.

`get_file`

my $file_metadata = $gd->get_file( $fileId, {%params} );

my $file_content = $gd->get_file(
    $fileId,
    {
        'alt'              => 'media',      # get the content
        'acknowledgeAbuse' => JSON::true(), # (optional) when there's risk
    },
);

Parameters are optional.

This serves the path to /files/$fileId.

This is also known as files.get.

You can read about the parameters on the Google Drive API page.

`files`

my $files = $gd->files({%params});

Parameters are optional.

This serves the path to /files.

This is also known as files.list.

You can read about the parameters on the Google Drive API page.

`update_file`

my $file = $gd->update_file( $fileId, {%params} );

This serves the path to /files/$fileId.

This is also known as files.update.

This is for updating a file's metadata and content.

You can read about the parameters on the Google Drive API page.

`update_file_metadata`

my $file = $gd->update_file_metadata( $fileId, {%params} );

This serves the path to /files/$fileId.

This is also known as files.update.

This one is only for updating a file's metadata, even though it shares a moniker with the update_file() method in the Google Drive API.

You can read about the parameters on the Google Drive API page.

`watch_file`

my $data = $gd->watch_file( $fileId, {%params} );

This serves the path to /files/$fileId/watch.

This is also known as files.watch.

You can read about the parameters on the Google Drive API page.

`empty_trash`

$gd->empty_trash({%params})

Parameters are optional.

This serves the path to /files/trash.

This is also known as files.emptyTrash.

You can read about the parameters on the Google Drive API page.

`create_permission`

my $permission = $gd-><create_permission( $fileId, {%params} );

This serves the path to /files/$fileId/permissions.

This is also known as permissions.create.

You can read about the parameters on the Google Drive API page.

`delete_permission`

$gd->delete_permission( $fileId, $permissionId, {%params} );

Parameters are optional.

This serves the path to /files/$fileId/permissions/$permissionId.

This is also known as permissions.delete.

You can read about the parameters on the Google Drive API page.

`get_permission`

my $permission = $gd->get_permission( $fileId, $permissionId, {%params} );

Parameters are optional.

This serves the path to /files/$fileId/permissions/$permissionId.

This is also known as permissions.get.

You can read about the parameters on the Google Drive API page.

`permissions`

my $permissions = $gd->permissions( $fileId, {%params} );

Parameters are optional.

This serves the path to /files/$fileId/permissions.

This is also known as permissions.list.

You can read about the parameters on the Google Drive API page.

`update_permission`

my $permission = $gd->update_permission( $fileId, $permissionId, {%params} );

Parameters are optional.

This serves the path to /files/$fileId/permissions/$permissionId.

This is also known as permissions.update.

You can read about the parameters on the Google Drive API page.

`create_reply`

my $reply = $gd->create_reply( $fileId, $commentId, {%params} );

This serves the path to /files/$fileId/comments/$commentId/replies.

This is also known as replies.create.

You can read about the parameters on the Google Drive API page.

`delete_reply( $fileId, $commentId, $replyId )`

$gd->delete_reply( $fileId, $commentId, $replyId );

This serves the path to /files/$fileId/comments/$commentId/replies/$replyId.

This is also known as replies.delete.

You can read about the parameters on the Google Drive API page.

`get_reply`

my $reply = %gd->get_reply( $fileId, $commentId, $replyId, {%params} );

This serves the path to /files/$fileId/comments/$commentId/replies/$replyId.

This is also known as replies.get.

You can read about the parameters on the Google Drive API page.

`replies`

my $replies = $gd->replies( $fileId, $commentId, {%params} );

This serves the path to /files/$fileId/comments/$commentId/replies.

This is also known as replies.list.

You can read about the parameters on the Google Drive API page.

`update_reply`

my $reply = $gd->update_reply( $fileId, $commentId, $replyId, {%params} );

This serves the path to /files/$fileId/comments/$commentId/replies/$replyId.

This is also known as replies.update.

You can read about the parameters on the Google Drive API page.

`delete_revision`

$gd->delete_revision( $fileId, {%params} );

This serves the path to /files/$fileId/revisions/$revisionId.

This is also known as revisions.delete.

You can read about the parameters on the Google Drive API page.

`get_revision( $fileId, $revisionId, $params )`

my $revision = $gd->get_revision( $fileId, $revisionId, {%params} );

Parameters are optional.

This serves the path to /files/$fileId/revisions/$revisionId.

This is also known as revisions.get.

You can read about the parameters on the Google Drive API page.

`revisions`

my $revisions = $gd->revisions( $fileId, {%params} );

Parameters are optional.

This serves the path to /files/$fileId/revisions.

This is also known as revisions.list.

You can read about the parameters on the Google Drive API page.

`update_revision`

my $revision = $gd->update_revision( $fileId, $revisionId, {%params} );

This serves the path to /files/$fileId/revisions/$revisionId.

This is also known as revisions.update.

You can read about the parameters on the Google Drive API page.

`create_drive`

my $drive = $gd->create_drive({%params});

This serves the path to /drives.

This is also known as drives.create.

You can read about the parameters on the Google Drive API page.

`delete_drive`

$gd->delete_drive($driveId);

This serves the path to /drives/$driveId.

This is also known as drives.delete.

You can read about the parameters on the Google Drive API page.

`get_drive`

my $drive = $gd->get_drive( $driveId, {%params} );

Parameters are optional.

This serves the path to /drives/$driveId.

This is also known as drives.get.

You can read about the parameters on the Google Drive API page.

`hide_drive`

my $drive = $gd->hide_drive($driveId);

This serves the path to /drives/$driveId/hide.

This is also known as drives.hide.

You can read about the parameters on the Google Drive API page.

`drives`

my $drives = $gd->drives({%params});

Parameters are optional.

This serves the path to /drives.

This is also known as drives.list.

You can read about the parameters on the Google Drive API page.

`unhide_drive`

my $drive = $gd->unhide_drive($driveId);

This serves the path to /drives/$driveId/unhide.

This is also known as drives.unhide.

You can read about the parameters on the Google Drive API page.

`update_drive`

my $drive = $gd->update_drive( $driveId, {%params} );

This serves the path to /drives/$driveId.

This is also known as drives.update.

You can read about the parameters on the Google Drive API page.

`children`

my $children = $gd->children( '/path/to', {%params}, {%extra_params} )>

The parameters and extra parameters are both optional.

Return the entries under a given path on the Google Drive as a reference to an array. Each entry is an object composed of the JSON data returned by the Google Drive API. Each object offers methods named like the fields in the JSON data, e.g. originalFilename(), downloadUrl, etc.

Will return all entries found unless pageSize is set:

my $children = $gd->children( "/path/to", { pageSize => 3 } )

Due to the somewhat capricious ways Google Drive handles its directory structures, the method needs to traverse the path component by component and determine the ID of each directory to get to the next level. To speed up subsequent lookups, it also returns the ID of the last component to the caller:

my( $children, $parent ) = $gd->children( "/path/to" );

If the caller now wants to e.g. insert a file into the directory, its ID is available in $parent.

Each child comes back as a files#resource type and gets mapped into an object that offers access to the various fields via methods:

for my $child ( @$children ) {
    print $child->kind(), " ", $child->name(), "\n";
}

Please refer to

https://developers.google.com/drive/v3/reference/files#resource

for details on which fields are available.

`children_by_folder_id`

my $children = $gd->children_by_folder_id($folderId);

# Search with a particular query and stop at the first page
my $children = $gd->children_by_folder_id(
    $folderId,
    { 'q' => q{name contains 'hello'} },
    { 'auto_paging' => 0 },
);

Similar to children() but uses a folder ID.

The second parameter is the parameters the files() method receives.

The third parameter is for additional options on how to conduct this search. Only one option is supported: auto_paging.

When auto_paging is turned on (which is the default), the search will be done on every page of the results instead of stopping at the first page.

UPLOADING

Uploading of a 5 MB file or lower is simple, but uploading a larger file is more difficult. This module supports every possible option, including connecting uploads to a different systems.

SIMPLE AND EASY UPLOADING

If you are not interested in all the details and finer controls of uploading files, you can just use upload_file.

my $data = $gd->upload_file( $filename, {%params} );

The parameters are optional and you can read more about them in the appropriate API page.

The disadvantages are that you cannot control how much is uploaded at a time, it's not resumable, nor coudl you connect it with an event loop.

However, this has no size limitations other than 5120 GB.

UPLOADING FILES 5 MB OR SMALLER

When uploading 5 MB and under, you can either use create_file() for metadata or upload_media_file() for both metadata and content.

Despite the name, you may upload any form of file, not just media files. (This is the name Google provides this form of upload.)

# Create only the metadata
my $data = $gd->create_file({
    'name'      => 'foo.txt',
    'mediaType' => 'text/plain',
})

Once you call create_file(), you can use the ID of the response in subsequent calls to upload_media_file() or upload_multipart_file(). (This might work for resumable uploads too, but it's not tested.)

# Upload just the file
$data = $gd->upload_media_file('foo.txt');
$data = $gd->upload_media_file( 'foo.txt', { 'name' => 'bar.txt' } );

The only supported parameters are the query parameters.

# Upload the file and all the metadata
$data = $gd->upload_multipart_file( 'foo.txt', {...} );

The difference between upload_media_file() and upload_multipart_file() is that the former method allows the query parameters, but the latter method allows all options.

You can read more about the available options for either of these file uploads here.

UPLOADING FILES ABOVE 5 MB

When uploading files above 5 MB, you must first create a URI for the file upload and then upload to that URI with another method.

There are two ways to create it, depending on whether you have a file available on disk or not.

# Creating the URI using a file
my $upload_uri = $gd->create_resumable_upload_for( $file, {...} );

# Creating the URI without a file
my $upload_uri = $gd->create_resumable_upload({
    'name'     => 'foo.txt',
    'mimeType' => 'text/plain',
});

The benefit of using create_resumable_upload_for() is that it allows you to use an existing file's mime type and filename. Otherwise, if you use the low-level create_resumable_upload(), you will need to provide the name and mediaType parameters yourself.

There are three different methods for uploading - choose the one that suits you best.

# Just upload the entire file
my $data = upload_file_content_single( $upload_uri, $file );

This upload will still try to chunk it by 4K so it doesn't load the entire file into memory. The biggest downside of this method is that if the file fails, it fully fails and you have to start from scratch.

# Upload the file in resumable chunks
my $data = upload_file_content_multiple(
    $upload_uri, $file, $optional_chunk_size,
);

This method will attempt to upload the file in chunks of 10 MB (or a whatever chunk size you ask for - in bytes) until it successfully finishes. If it fails, you might be able to resume. However, resuming is not yet supported within the API, sorry.

UPLOADING FILES WITH EVENT LOOPS

If you want to connect file uploading to an event loop, you can use upload_file_content_iterator() to receive an iterator which will generate a proper HTTP::Request object you can then use in the event loop request.

my $iterator = upload_file_content_iterator(
    $upload_uir, $file, $optional_chunk_size,
);

while ( my $request = $iter->() ) {
    my $response = do_something_with_request($request);

    # $response->code() == 200 - Done
    # $response->code() == 308 - Keep going
    # anything else            - Probably some form of error
}

There is currently no sample code for any particular event loop.

LEGALESE

AUTHOR

Sawyer X <xsawyerx@cpan.org>

To install Net::Google::Drive::Simple, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::Google::Drive::Simple

CPAN shell

perl -MCPAN -e shell
install Net::Google::Drive::Simple

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

SYNOPSIS

DESCRIPTION

METHODS

new

about

getStartPageToken

changes

watch_changes

stop_channels

create_comment

delete_comment( $fileId, $commentId )

get_comment( $fileId, $commentId, $params )

comments

update_comment

copy_file

create_folder

create_file

upload_file

upload_media_file

upload_multipart_file

create_resumable_upload_for

create_resumable_upload

upload_file_content_single

upload_file_content_multiple

upload_file_content_iterator

delete_file

export_file

generateIds

get_file

files

update_file

update_file_metadata

watch_file

empty_trash

create_permission

delete_permission

get_permission

permissions

update_permission

create_reply

delete_reply( $fileId, $commentId, $replyId )

get_reply

replies

update_reply

delete_revision

get_revision( $fileId, $revisionId, $params )

revisions

update_revision

create_drive

delete_drive

get_drive

hide_drive

drives

unhide_drive

update_drive

children

children_by_folder_id

UPLOADING

SIMPLE AND EASY UPLOADING

UPLOADING FILES 5 MB OR SMALLER

UPLOADING FILES ABOVE 5 MB

UPLOADING FILES WITH EVENT LOOPS

LEGALESE

AUTHOR

Module Install Instructions

`new`

`about`

`getStartPageToken`

`changes`

`watch_changes`

`stop_channels`

`create_comment`

`delete_comment( $fileId, $commentId )`

`get_comment( $fileId, $commentId, $params )`

`comments`

`update_comment`

`copy_file`

`create_folder`

`create_file`

`upload_file`

`upload_media_file`

`upload_multipart_file`

`create_resumable_upload_for`

`create_resumable_upload`

`upload_file_content_single`

`upload_file_content_multiple`

`upload_file_content_iterator`

`delete_file`

`export_file`

`generateIds`

`get_file`

`files`

`update_file`

`update_file_metadata`

`watch_file`

`empty_trash`

`create_permission`

`delete_permission`

`get_permission`

`permissions`

`update_permission`

`create_reply`

`delete_reply( $fileId, $commentId, $replyId )`

`get_reply`

`replies`

`update_reply`

`delete_revision`

`get_revision( $fileId, $revisionId, $params )`

`revisions`

`update_revision`

`create_drive`

`delete_drive`

`get_drive`

`hide_drive`

`drives`

`unhide_drive`

`update_drive`

`children`

`children_by_folder_id`