NAME

WWW::Google::Drive - Used to modify Google Drive data for service account (server-to-server)

SYNOPSIS

use WWW::Google::Drive;

my $gd = WWW::Google::Drive->new( 
    secret_json => 'YourProject.json',

     # Set the Google user to impersonate. 
     # Your Google Business Administrator must have already set up 
     # your Client ID as a trusted app in order to use this successfully.
    user_as => 'name@domain.com' #(optional)
);
my $children = $gd->children('/MyDocs');

foreach my $item (@{$children}){
    print "File name: $item->{name}\n";
}

DESCRIPTION

WWW::Google::Drive authenticates with a Google Drive service account (server-to-server) and offers several convenient methods to list, retrieve and modify the data stored in the google drive.

Refer: https://developers.google.com/identity/protocols/OAuth2ServiceAccount for creating a service account and the client_secret json file.

Refer: https://developers.google.com/drive/v3/reference/ for list of file properties, response values, query_params and body_params.

METHODS

new

my $gd = WWW::Google::Drive->new(
        secret_json => "./YourProject.json"
    );

Parameters can be

user_as (optional)
    - email id of the account, if set, then all operations will be done in that respective user's space. Respective account should be authenticated using OAuth2.0 mechanism. See Net::Google::Drive::Simple eg/ directory for an example script to do authentication using OAuth2.0

http_retry_no (default 0)
    - number of time each http requests should be retried if the request is failed

http_retry_interval (default 5)
    - time interval in seconds after which another attempt will be made for the previously failed http request, this setting is useless when http_retry_no is set to 0

show_trash_items (default 0)
    - when this value is set, trash files filter will be disabled

lwp_opts (default {})
    - This will be passed to LWP::UserAgent constructor
    - additionally you can pass an array ref with key as proxy_conf in lwp_opts 
        which will be passed to $user_agent->proxy(@{$proxy_conf});

files

Params : $query_params (optional) For list of query_params refer https://developers.google.com/drive/v3/reference/files/list

Returns : List of files

Desc : Get all files from your drive

Usage :

my $files_at_drive = $gd->files();

children

Params : $path, $query_params (optional), $body_params (optional)

Returns : All items under the given path as an array ref

Desc : Get children of given directory. Since the directory path is iteratively found for optimization $parent_id is returned as second argument when calling in array context.

Usage :

my $children = $gd->children('/my_docs' $query_params, $body_params);

or 

my ($children, $parent_id) = $gd->children('/my_docs', $query_params, $body_params);

children_by_folder_id

Params : $folder_id, $query_params (optional), $body_params (optional)

Returns : Arrayref of items (files)

Desc : Get all the items which has $folder_id as parent

Usage :

my $items = $gd->children_by_folder_id($parent_id, { orderBy => 'modifiedTime' });

new_file

Params : $local_file_path, $folder_id, $options (optional key value pairs), $query_params (optional)

Returns : new file id, ( and second argument as response data hashref when called in array context )

Desc : Uploads a new file ( file at $local_file_path ) to the drive in the given folder ( given folder_id )

Usage :

my $file_id = $gd->new_file('./testfile', $parent_id, { description => "This is a test file upload" });

update_file

Params : $old_file_id, $updated_local_file_path, $body_params (optional), $query_params (optional)

Returns : $file_id on Successful upload

Desc : This will replace the existing file in the drive with new file.

Usage :

my $file_id = $gd->update_file($old_file_id, "./updated_file");

NOTE : If you only want to update file metadata, then send file_path as undef and $body_params should have properties.

delete

Params : $item_id (It can be a file_id or folder_id), $no_trash (optional)

Returns : deleted file id on successful deletion

Desc : Deletes an item from google drive.

Usage :

my $deleted_file_id = $gd->delete($file_id);

NOTE : If $no_trash option is set, file will be deleted from google drive permanently.

create_folder

Params : $folder_name, $parent_folder_id

Returns : $folder_id (newly created folder Id) If called in an array context then second argument will be the http response data

Desc : Used to create a new directory in your drive

Usage :

my $new_folder_id = $gd->create_folder("Test",$parent_id);

search

Params : $query string, $query_params (optional)

Returns : Result items (files) for the given query

Desc : Do search on the google drive using the syntax mentioned in google drive, refer https://developers.google.com/drive/v3/web/search-parameters for list of search parameters and examples

Usage :

my $items = $gd->search("mimeType contains 'image/'",{ corpus => 'user' });

download

Params : $file_id, $local_file_path, $acknowledgeAbuse

Returns : 0/1 when $file_path is given, otherwise returns the file content

Desc : Download file from the drive, when you pass file_id as a ref this method will try to find the $file_id->{id} and tries to download that file. When local file name with path is not given, this method will return the content of the file on success download.

Usage :

$gd->download($file_id, $local_file);

or

my $file_content = $gd->download($file_id);

export_options

Params : $mimeType or { mimeType => $mime_type }

Return : hashref with key as mimeType name and value as mimeType

Desc : Return available export options with its mimeType for the given google docs mimeType

export

Params : $file_id, $mime_type, $local_file_path

Returns : 0/1 when $local_file_path is given, otherwise returns the file content

Desc : Download exported file from the drive, when you pass file_id as a ref, this method will try to find the $file_id->{id} and tries to download that file. When local file name with path is not given, this method will return the content of the file on success download.

Usage :

$gd->export($file_id, 'application/pdf', $local_file_path);

or

my $file_content = $gd->export($file_id, 'application/pdf');

metadata

Params : $file_id, $query_params

Returns : hashref of properties on success

Desc : Used to get the file metadata. (files.get)

Usage :

my $properties = $gd->metadata($file_id);

file_mime_type

Params : $local_file_path

Returns : mime type of the given file

Desc : Find the MimeType of a file using File::MimeInfo

Usage :

my $mime_type = $gd->file_mime_type("./testfile");

remove_trashed

Params : $items_arrayref ( return value of files() or children() )

Returns : $items arrayref

Desc : This method will filter out all the files marked as trashed

Usage :

my $items = $gd->children('./MyDocs');

# do something with the data

my $live_items = $gd->remove_trashed($items);

show_trash_items

Params : 0/1

Returns : NONE

Desc : Disable/Enable listing deleted data from your drive

Usage : $gd->show_trash_items(1); my $all_files = $gd->children('/'); # will return all the files including files in trash

NOTE : This module will consider an item as trashed if the file's metadata 'trashed' is set to true.

add_req_file_fields

Params : file_properties as list Refer: https://developers.google.com/drive/v3/reference/files#resource for list of properties Refer: https://developers.google.com/drive/v3/web/performance for fields syntax

Returns : NONE

Desc : Add file fields parameter that will be used in $query_params 'fields'.

Usage :

$gd->add_req_file_fields('appProperties','spaces','owners/kind');
$gd->children('/');

Note : By Default fields such as 'kind','trashed','id','name' are added.

Error handling

In case of an error while retrieving information from the Google Drive API, the methods above will return undef and a more detailed error message can be obtained by calling the error() method:

print "An error occurred: ", $gd->error();
   

LOGGING/DEBUGGING

WWW::Google::Drive is Log4perl-enabled. To find out what's going on under the hood, turn on Log4perl:

use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($DEBUG);

REPOSITORY

https://github.com/dinesh-it/www-google-drive

SEE ALSO

Net::Google::Drive::Simple Net::GoogleDrive

LICENSE

Copyright 2016 by Dinesh Dharmalingam, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Dinesh D, <dinesh@exceleron.com>