view release on metacpan or  search on metacpan

lib/Google/RestApi.pm  view on Meta::CPAN

# 0 sets and returns default value.
sub max_attempts {
  my $self = shift;
  state $check = signature(positional => [PositiveOrZeroInt->where(sub { $_ < 10; }), { optional => 1 }]);
  my ($max_attempts) = $check->(@_);
  $self->{max_attempts} = $max_attempts if $max_attempts;
  $self->{max_attempts} = 4 if defined $max_attempts && $max_attempts == 0;
  return $self->{max_attempts};
}

1;

__END__

=head1 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.

=head1 SYNOPSIS

=over

  # create a new RestApi object to be used by the apis.
  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 the apis 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>,
  );

  # --- Drive API ---
  use Google::RestApi::DriveApi3;
  $drive = Google::RestApi::DriveApi3->new(api => $rest_api);
  $file = $drive->file(id => 'xxxx');
  $copy = $file->copy(name => 'my-copy-of-xxx');
  @files = $drive->list(filter => "name contains 'report'");

  # --- Sheets API ---
  use Google::RestApi::SheetsApi4;
  $sheets = Google::RestApi::SheetsApi4->new(api => $rest_api);
  $spreadsheet = $sheets->open_spreadsheet(name => 'My Sheet');
  $worksheet = $spreadsheet->open_worksheet(name => 'Sheet1');
  @values = $worksheet->col('A');
  $worksheet->row(1, ['Name', 'Email', 'Phone']);

  # --- Calendar API ---
  use Google::RestApi::CalendarApi3;
  $calendar_api = Google::RestApi::CalendarApi3->new(api => $rest_api);
  $calendar = $calendar_api->create_calendar(summary => 'Team Events');
  $event = $calendar->event();
  $event->create(
    summary => 'Meeting',
    start   => { dateTime => '2026-03-01T10:00:00-05:00' },
    end     => { dateTime => '2026-03-01T11:00:00-05:00' },
  );

  # --- Gmail API ---
  use Google::RestApi::GmailApi1;
  $gmail = Google::RestApi::GmailApi1->new(api => $rest_api);
  $gmail->send_message(
    to => 'user@example.com', subject => 'Hello', body => 'Hi there',
  );
  @messages = $gmail->messages();

  # --- Tasks API ---
  use Google::RestApi::TasksApi1;
  $tasks = Google::RestApi::TasksApi1->new(api => $rest_api);
  $task_list = $tasks->create_task_list(title => 'My Tasks');
  $task_list->create_task(title => 'Buy groceries', notes => 'Milk, eggs');

  # --- Docs API ---
  use Google::RestApi::DocsApi1;
  $docs = Google::RestApi::DocsApi1->new(api => $rest_api);
  $doc = $docs->create_document(title => 'My Document');
  $doc->insert_text(text => 'Hello, world!');
  $doc->submit_requests();

See the individual PODs for the different apis for details on how to use each
one.

=back

=head1 DESCRIPTION

Google::RestApi is a framework for interfacing with Google products, currently
Drive (L<Google::RestApi::DriveApi3>), Sheets (L<Google::RestApi::SheetsApi4>),
Calendar (L<Google::RestApi::CalendarApi3>), Gmail (L<Google::RestApi::GmailApi1>),
Tasks (L<Google::RestApi::TasksApi1>), and Docs (L<Google::RestApi::DocsApi1>).

The biggest hurdle to using this library is actually setting up the authorization
to access your Google 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. See C<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, see the
pods listed in the L</NAVIGATION> section below.

Once you have successfully created your OAuth2 token, you can run the tutorials
to ensure everything is working correctly. Set the environment variable
C<GOOGLE_RESTAPI_CONFIG> to the path to your auth config file. See the
C<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.

=head2 Chained API Calls

Every Google API module has an C<api()> method. Sub-resource objects
(see L<Google::RestApi::SubResource>) don't call the Google endpoint