File Coverage

blib/lib/Net/Google/Drive/Simple.pm
Criterion Covered Total %
statement 20 21 95.2
branch 3 4 75.0
condition 4 5 80.0
subroutine 6 6 100.0
pod 1 1 100.0
total 34 37 91.8


line stmt bran cond sub pod time code
1             ###########################################
2             ###########################################
3              
4             use strict;
5 3     3   174915 use warnings;
  3         23  
  3         75  
6 3     3   13  
  3         5  
  3         89  
7             use constant {
8             'DEFAULT_VERSION' => 2,
9 3         280 'RECOMMENDED_VERSION' => 3,
10             };
11 3     3   14  
  3         5  
12             use Net::Google::Drive::Simple::V2;
13 3     3   1355 use Net::Google::Drive::Simple::V3;
  3         11  
  3         97  
14 3     3   2015  
  3         9  
  3         364  
15             our $VERSION = '3.01';
16              
17             ###########################################
18             ###########################################
19             my ( $class, %options ) = @_;
20              
21 3     3 1 9603 my $version = $options{'version'} || DEFAULT_VERSION();
22             if ( $version != DEFAULT_VERSION() && $version != RECOMMENDED_VERSION() ) {
23 3   100     17 die "Incorrect version number ($version) - must be '2' or '3'";
24 3 50 66     18 }
25 0         0  
26             my $impl =
27             $version == DEFAULT_VERSION()
28 3 100       25 ? Net::Google::Drive::Simple::V2->new(%options)
29             : Net::Google::Drive::Simple::V3->new(%options);
30              
31             return $impl;
32             }
33 3         9  
34             1;
35              
36              
37             =head1 NAME
38              
39             Net::Google::Drive::Simple - Simple modification of Google Drive data
40              
41             =head1 SYNOPSIS
42              
43             use feature 'say';
44             use Net::Google::Drive::Simple;
45              
46             # requires a ~/.google-drive.yml file with an access token,
47             # see description below.
48             my $gd = Net::Google::Drive::Simple->new( 'version' => 3 ); # v3 interface (RECOMMENDED!)
49             my $gd = Net::Google::Drive::Simple->new(); # v2 interface (OUTDATE!)
50              
51             my $children = $gd->children( "/" ); # or any other folder /path/location
52              
53             foreach my $item ( @$children ) {
54              
55             # item is a Net::Google::Drive::Simple::Item object
56              
57             if ( $item->is_folder ) {
58             say "** ", $item->title, " is a folder";
59             } else {
60             say $item->title, " is a file ", $item->mimeType;
61             eval { # originalFilename not necessary available for all files
62             say $item->originalFilename(), " can be downloaded at ", $item->downloadUrl();
63             };
64             }
65             }
66              
67             =head1 DESCRIPTION
68              
69             Net::Google::Drive::Simple authenticates with a user's Google Drive and
70             offers several convenience methods to list, retrieve, and modify the data
71             stored in the 'cloud'. See C<eg/google-drive-upsync> as an example on how
72             to keep a local directory in sync with a remote directory on Google Drive.
73              
74             All methods are documented based on the version you use:
75              
76             =over 4
77              
78             =item * V3 (recommended)
79              
80             # Create default V3 API:
81             my $gd = Net::Google:Drive::Simple->new( 'version' => 3 );
82              
83             The methods available are documented in
84             L<Net::Google::Drive::Simple::V3>.
85              
86             =item * V2 (default, outdated)
87              
88             # Create default V2 API:
89             my $gd = Net::Google:Drive::Simple->new();
90              
91             # or:
92             my $gd = Net::Google:Drive::Simple->new( 'version' => 2 );
93              
94             The methods available are documented in
95             L<Net::Google::Drive::Simple::V2>.
96              
97             =back
98              
99             =head2 GETTING STARTED
100              
101             To get the access token required to access your Google Drive data via
102             this module, you need to run the script C<eg/google-drive-init> in this
103             distribution.
104              
105             Before you run it, you need to register your 'app' with Google Drive
106             and obtain a client_id and a client_secret from Google:
107              
108             https://developers.google.com/drive/web/enable-sdk
109              
110             Click on "Enable the Drive API and SDK", and find "Create an API project in
111             the Google APIs Console". On the API console, create a new project, click
112             "Services", and enable "Drive API" (leave "drive SDK" off). Then, under
113             "API Access" in the navigation bar, create a client ID, and make sure to
114             register a an "installed application" (not a "web application"). "Redirect
115             URIs" should contain "http://localhost". This will get you a "Client ID"
116             and a "Client Secret".
117              
118             Then, replace the following lines in C<eg/google-drive-init> with the
119             values received:
120              
121             # You need to obtain a client_id and a client_secret from
122             # https://developers.google.com/drive to use this.
123             my $client_id = "XXX";
124             my $client_secret = "YYY";
125              
126             Then run the script. It'll start a web server on port 8082 on your local
127             machine. When you point your browser at http://localhost:8082, you'll see a
128             link that will lead you to Google Drive's login page, where you authenticate
129             and then allow the app (specified by client_id and client_secret above) access
130             to your Google Drive data. The script will then receive an access token from
131             Google Drive and store it in ~/.google-drive.yml from where other scripts can
132             pick it up and work on the data stored on the user's Google Drive account. Make
133             sure to limit access to ~/.google-drive.yml, because it contains the access
134             token that allows everyone to manipulate your Google Drive data. It also
135             contains a refresh token that this library uses to get a new access token
136             transparently when the old one is about to expire.
137              
138             =head1 METHODS
139              
140             =over 4
141              
142             =item C<new()>
143              
144             Constructor, creates a helper object to retrieve Google Drive data
145             later.
146              
147             While v2 (the outdated version) is still supported by Google, we
148             recommend you use v3:
149              
150             # Returns object of Net::Google::Drive::Simple::V3
151             my $gd = Net::Google::Drive::Simple->new( 'version' => 3 );
152              
153             # Returns object of Net::Google::Drive::Simple::V2
154             my $gd = Net::Google::Drive::Simple->new( 'version' => 2 );
155             # or:
156             my $gd = Net::Google::Drive::Simple->new();
157              
158             Read up on the methods in each class: L<Net::Google::Drive::Simple::V3>
159             and L<Net::Google::Drive::Simple::V2>.
160              
161             =back
162              
163             =head1 Error handling
164              
165             In case of an error while retrieving information from the Google Drive
166             API, the methods above will return C<undef> and a more detailed error
167             message can be obtained by calling the C<error()> method:
168              
169             print "An error occurred: ", $gd->error();
170              
171             =head1 LOGGING/DEBUGGING
172              
173             Net::Google::Drive::Simple is Log4perl-enabled.
174             To find out what's going on under the hood, turn on Log4perl:
175              
176             use Log::Log4perl qw(:easy);
177             Log::Log4perl->easy_init($DEBUG);
178              
179             =head1 LEGALESE
180              
181             Copyright 2012-2019 by Mike Schilli, all rights reserved.
182             This program is free software, you can redistribute it and/or
183             modify it under the same terms as Perl itself.
184              
185             =head1 AUTHOR
186              
187             2019, Nicolas R. <cpan@atoomic.org>
188             2012-2019, Mike Schilli <cpan@perlmeister.com>