# NAME

Google::RestApi - API to Google Drive API V3, Sheets API V4, Calendar API V3, Gmail API V1, Tasks API V1, and Docs API V1.

# SYNOPSIS

>     # create a new RestApi object to be used by Drive and Sheets
>     use Google::RestApi;
>     $rest_api = Google::RestApi->new(
>       config_file   => <path_to_config_file>,
>       auth          => <object|hashref>,
>       timeout       => <int>,
>       throttle      => <int>,
>       api_callback  => <coderef>,
>     );
>
>     # you can call the raw api directly, but usually Drive and Sheets will
      # take care of forming the correct API calls for you.
>     $response = $rest_api->api(
>       uri     => <google_api_url>,
>       method  => get|head|put|patch|post|delete,
>       headers => [],
>       params  => <query_params>,
>       content => <data_for_body>,
>     );
>
>     use Google::RestApi::DriveApi3;
>     $drive = Google::RestApi::DriveApi3->new(api => $rest_api);
>
>     # file operations
>     $file = $drive->file(id => 'xxxx');
>     $copy = $file->copy(name => 'my-copy-of-xxx');
>     $file->update(name => 'new-name', description => 'new desc');
>     $file->export(mime_type => 'application/pdf');
>
>     # permissions
>     $file->permission()->create(role => 'reader', type => 'anyone');
>     @perms = $file->permissions();
>
>     # comments and replies
>     $comment = $file->comment()->create(content => 'Looks good!');
>     $reply = $comment->reply()->create(content => 'Thanks!');
>     @comments = $file->comments();
>
>     # revisions
>     @revs = $file->revisions();
>
>     # drive-level operations
>     $about = $drive->about();
>     $changes = $drive->changes();
>     @shared = $drive->shared_drives();
>
>     use Google::RestApi::SheetsApi4;
>     $sheets_api = Google::RestApi::SheetsApi4->new(api => $rest_api);
>     $sheet = $sheets_api->open_spreadsheet(title => "payroll");
>     $ws0 = $sheet->open_worksheet(id => 0);
>
>     # sub Worksheet::cell/col/cols/row/rows immediately get/set
>     # values. this is less efficient but the simplest way to
>     # interface with the api. you don't deal with any intermediate
>     # api objects.
>
>     # add some data to the worksheet:
>     @values = (
>       [ 1001, "Herb Ellis", "100", "10000" ],
>       [ 1002, "Bela Fleck", "200", "20000" ],
>       [ 1003, "Freddie Mercury", "999", "99999" ],
>     );
>     $ws0->rows([1, 2, 3], \@values);
>     $values = $ws0->rows([1, 2, 3]);
>
>     # use and manipulate 'range' objects to do more complex work.
>     # ranges can be specified in many ways, use whatever way is most convenient.
>     $range = $ws0->range("A1:B2");
>     $range = $ws0->range([[1,1],[2,2]]);
>     $range = $ws0->range([{col => 1, row => 1}, {col => 2, row => 2}]);
>
>     $cell = $ws0->range_cell("A1");
>     $cell = $ws0->range_cell([1,1]);
>     $cell = $ws0->range_cell({col => 1, row => 1});
>
>     $col = $ws0->range_col(1);
>     $col = $ws0->range_col("A3:A");
>     $col = $ws0->range_col([1]);
>     $col = $ws0->range_col([[1, 3], [1]]);
>     $col = $ws0->range_col({col => 1});
>
>     $row = $ws0->range_row(1);
>     $row = $ws0->range_row("C1:1");
>     $row = $ws0->range_row([<falsey>, 1]);
>     $row = $ws0->range_row({row => 1});
>     $row = $ws0->range_row([col => 3, row => 1 }, {row => 1}]);
>
>     # add a header:
>     $row = $ws0->range_row(1);
>     $row->insert_d()->freeze()->bold()->italic()->center()->middle()->submit_requests();
>     # sub 'values' sends the values to the api directly, not using batch (less efficient):
>     $row->values(values => [qw(Id Name Tax Salary)]);
>
>     # bold the names:
>     $col = $ws0->range_col("B2:B");
>     $col->bold()->submit_requests();
>
>     # add some tax info:
>     $tax = $ws0->range_cell([ 3, 5 ]);   # or 'C5' or [ 'C', 5 ] or { col => 3, row => 5 }...
>     $salary = $ws0->range_cell({ col => "D", row => 5 }); # same as "D5"
>     # set up batch update with staged values:
>     $tax->batch_values(values => "=SUM(C2:C4)");
>     $salary->batch_values(values => "=SUM(D2:D4)");
>     # now collect the ranges into a group and send the values via batch:
>     $rg = $sheet->range_group($tax, $salary);
>     # now actually send the values to the spreadsheet:
>     $rg->submit_values();
> 
>     # bold and italicize both cells, and put a solid border around each one,
      # and send the formats to the spreadsheet:
>     $rg->bold()->italic()->bd_solid()->submit_requests();
>

# DESCRIPTION

Google::RestApi is a framework for interfacing with Google products, currently Drive, Sheets, Calendar, Gmail, Tasks, and Docs.

The biggest hurdle to using this library is actually setting up the authorization to access your Drive and Sheets account via a script.
The Google development web space is huge and complex. All that's required here is an OAuth2 token to authorize your script that uses this
library to access your Drive and Sheets. See bin/google_restapi_oauth_token_creator for instructions on how to do so. Once you've done it
a couple of times it's straight forward.

The synopsis above is a quick reference. For more detailed information, most of the good stuff is in the following pods:

    Google::RestApi
    Google::RestApi::DriveApi3
    Google::RestApi::DriveApi3::File
    Google::RestApi::DriveApi3::About
    Google::RestApi::DriveApi3::Changes
    Google::RestApi::DriveApi3::Drive
    Google::RestApi::DriveApi3::Permission
    Google::RestApi::DriveApi3::Comment
    Google::RestApi::DriveApi3::Reply
    Google::RestApi::DriveApi3::Revision
    Google::RestApi::CalendarApi3
    Google::RestApi::CalendarApi3::Calendar
    Google::RestApi::CalendarApi3::Event
    Google::RestApi::CalendarApi3::Acl
    Google::RestApi::CalendarApi3::CalendarList
    Google::RestApi::CalendarApi3::Colors
    Google::RestApi::CalendarApi3::Settings
    Google::RestApi::GmailApi1
    Google::RestApi::GmailApi1::Message
    Google::RestApi::GmailApi1::Attachment
    Google::RestApi::GmailApi1::Thread
    Google::RestApi::GmailApi1::Draft
    Google::RestApi::GmailApi1::Label
    Google::RestApi::TasksApi1
    Google::RestApi::TasksApi1::TaskList
    Google::RestApi::TasksApi1::Task
    Google::RestApi::DocsApi1
    Google::RestApi::DocsApi1::Document
    Google::RestApi::SheetsApi4
    Google::RestApi::SheetsApi4::Spreadsheet
    Google::RestApi::SheetsApi4::Worksheet
    Google::RestApi::SheetsApi4::Range

Once you have successfully created your OAuth2 token, you can run the tutorials to ensure everything is working correctly.
Set the environment variable GOOGLE_RESTAPI_CONFIG to the path to your auth config file.
See the tutorial/ directory for step-by-step tutorials covering Sheets, Drive, Calendar, Documents, Gmail, and Tasks.
These will help you understand how the API interacts with Google.

# STATUS

Partial sheets and drive apis were hand-written by the author. Claude was used
to generate the missing api calls for these, and the rest of the google apis
were added using Claude, based on the existing patterns. If all works for you,
it will be due to my stunning intellect. If it doesn't, or you see strange and
wild code, it's all Claude's fault, nothing to do with the author.

All mock exchanges were generated by running the unit tests and opening the
live api to save the requests/responses for later playback. Because all the
tests pass using this, it's a pretty good indicator that the calls work.

# 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.
