WebService::Dropbox(3pm)

1WebService::Dropbox(3pmU)ser Contributed Perl DocumentatiWoenbService::Dropbox(3pm)
2
3
4

NAME

6       WebService::Dropbox - Perl interface to Dropbox API
7

SYNOPSIS

9           use WebService::Dropbox;
10
11           my $dropbox = WebService::Dropbox->new({
12               key => '...', # App Key
13               secret => '...' # App Secret
14           });
15
16           # Authorization
17           if ($access_token) {
18               $box->access_token($access_token);
19           } else {
20               my $url = $box->authorize;
21
22               print "Please Access URL and press Enter: $url\n";
23               print "Please Input Code: ";
24
25               chomp( my $code = <STDIN> );
26
27               unless ($box->token($code)) {
28                   die $box->error;
29               }
30
31               print "Successfully authorized.\nYour AccessToken: ", $box->access_token, "\n";
32           }
33
34           my $info = $dropbox->get_current_account or die $dropbox->error;
35
36           # download
37           # https://www.dropbox.com/developers/documentation/http/documentation#files-download
38           my $fh_download = IO::File->new('some file', '>');
39           $dropbox->download('/make_test_folder/test.txt', $fh_download) or die $dropbox->error;
40           $fh_get->close;
41
42           # upload
43           # https://www.dropbox.com/developers/documentation/http/documentation#files-upload
44           my $fh_upload = IO::File->new('some file');
45           $dropbox->upload('/make_test_folder/test.txt', $fh_upload) or die $dropbox->error;
46           $fh_upload->close;
47
48           # get_metadata
49           # https://www.dropbox.com/developers/documentation/http/documentation#files-get_metadata
50           my $data = $dropbox->get_metadata('/folder_a');
51

DESCRIPTION

53       WebService::Dropbox is Perl interface to Dropbox API
54
55       - Support Dropbox v2 REST API
56
57       - Support Furl (Fast!!!)
58
59       - Streaming IO (Low Memory)
60

API v1 => v2 Migration guide

62   Migration API
63       files => download, files_put => upload ...etc
64
65       <https://www.dropbox.com/developers/reference/migration-guide>
66
67   Migration OAuth1 Token => OAuth2 Token
68           use WebService::Dropbox::TokenFromOAuth1;
69
70           my $oauth2_access_token = WebService::Dropbox::TokenFromOAuth1->token_from_oauth1({
71               consumer_key    => $dropbox->key,
72               consumer_secret => $dropbox->secret,
73               access_token    => $access_token,  # OAuth1 access_token
74               access_secret   => $access_secret, # OAuth1 access_secret
75           });
76
77           warn $oauth2_access_token;
78

Use API v1

80       Dropbox will be turning off API v1 on 6/28/2017.
81
82       <https://blogs.dropbox.com/developers/2016/06/api-v1-deprecated/>
83
84   cpanfile
85           requires 'WebService::Dropbox', '== 1.22';
86
87   cpanm
88           cpanm -L local ASKADNA/WebService-Dropbox-1.22.tar.gz
89
90   curl
91           mkdir lib/WebService
92           curl -o lib/WebService/Dropbox.pm https://raw.githubusercontent.com/s-aska/p5-WebService-Dropbox/1.22/lib/WebService/Dropbox.pm
93

API

95   Auth
96       <https://www.dropbox.com/developers/documentation/http/documentation#oauth2-authorize>
97
98       for CLI Sample
99
100           my $url = $dropbox->authorize;
101
102           print "Please Access URL: $url\n";
103           print "Please Input Code: ";
104
105           chomp( my $code = <STDIN> );
106
107           unless ($dropbox->token($code)) {
108               die $dropbox->error;
109           }
110
111           print "Successfully authorized.\nYour AccessToken: ", $dropbox->access_token, "\n";
112
113       for Web Sample
114
115           use Amon2::Lite;
116           use WebService::Dropbox;
117
118           __PACKAGE__->load_plugins('Web::JSON');
119
120           my $key = $ENV{DROPBOX_APP_KEY};
121           my $secret = $ENV{DROPBOX_APP_SECRET};
122           my $dropbox = WebService::Dropbox->new({ key => $key, secret => $secret });
123
124           my $redirect_uri = 'http://localhost:5000/callback';
125
126           get '/' => sub {
127               my ($c) = @_;
128
129               my $url = $dropbox->authorize({ redirect_uri => $redirect_uri });
130
131               return $c->redirect($url);
132           };
133
134           get '/callback' => sub {
135               my ($c) = @_;
136
137               my $code = $c->req->param('code');
138
139               my $token = $dropbox->token($code, $redirect_uri);
140
141               my $account = $dropbox->get_current_account || { error => $dropbox->error };
142
143               return $c->render_json({ token => $token, account => $account });
144           };
145
146           __PACKAGE__->to_app();
147
148       authorize(\%optional_params)
149
150           # for Simple CLI
151           my $url = $dropbox->authorize();
152
153           # for Other
154           my $url = $dropbox->authorize({
155               response_type => 'code', # code or token
156               redirect_uri => '',
157               state => '',
158               require_role => '',
159               force_reapprove => JSON::false,
160               disable_signup => JSON::false,
161           });
162
163       <https://www.dropbox.com/developers/documentation/http/documentation#oauth2-authorize>
164
165       token($code [, $redirect_uri])
166
167       This endpoint only applies to apps using the authorization code flow.
168       An app calls this endpoint to acquire a bearer token once the user has
169       authorized the app.
170
171       Calls to /oauth2/token need to be authenticated using the apps's key
172       and secret. These can either be passed as POST parameters (see
173       parameters below) or via HTTP basic authentication. If basic
174       authentication is used, the app key should be provided as the username,
175       and the app secret should be provided as the password.
176
177           # for CLI
178           my $token = $dropbox->token($code);
179
180           # for Web
181           my $token = $dropbox->token($code, $redirect_uri);
182
183       <https://www.dropbox.com/developers/documentation/http/documentation#oauth2-token>
184
185       revoke
186
187       Disables the access token used to authenticate the call.
188
189           my $result = $dropbox->revoke;
190
191       <https://www.dropbox.com/developers/documentation/http/documentation#auth-token-revoke>
192
193   Files
194       copy($from_path, $to_path)
195
196       Copy a file or folder to a different location in the user's Dropbox.
197       If the source path is a folder all its contents will be copied.
198
199           my $result = $dropbox->copy($from_path, $to_path);
200
201       <https://www.dropbox.com/developers/documentation/http/documentation#files-copy>
202
203       copy_reference_get($path)
204
205       Get a copy reference to a file or folder. This reference string can be
206       used to save that file or folder to another user's Dropbox by passing
207       it to copy_reference/save.
208
209           my $result = $dropbox->copy_reference_get($path);
210
211       <https://www.dropbox.com/developers/documentation/http/documentation#files-copy_reference-get>
212
213       copy_reference_save($copy_reference, $path)
214
215       Save a copy reference returned by copy_reference/get to the user's
216       Dropbox.
217
218           my $result = $dropbox->copy_reference_save($copy_reference, $path);
219
220       <https://www.dropbox.com/developers/documentation/http/documentation#files-copy_reference-save>
221
222       create_folder($path)
223
224       Create a folder at a given path.
225
226           my $result = $dropbox->create_folder($path);
227
228       <https://www.dropbox.com/developers/documentation/http/documentation#files-create_folder>
229
230       delete($path)
231
232       Delete the file or folder at a given path.
233
234       If the path is a folder, all its contents will be deleted too.
235
236       A successful response indicates that the file or folder was deleted.
237       The returned metadata will be the corresponding FileMetadata or
238       FolderMetadata for the item at time of deletion, and not a
239       DeletedMetadata object.
240
241           my $result = $dropbox->delete($path);
242
243       <https://www.dropbox.com/developers/documentation/http/documentation#files-delete>
244
245       download($path, $output [, \%opts])
246
247       Download a file from a user's Dropbox.
248
249           # File handle
250           my $fh = IO::File->new('some file', '>');
251           $dropbox->download($path, $fh);
252
253           # Code reference
254           my $write_code = sub {
255               # compatible with LWP::UserAgent and Furl::HTTP
256               my $chunk = @_ == 4 ? @_[3] : $_[0];
257               print $chunk;
258           };
259           $dropbox->download($path, $write_code);
260
261           # Range
262           my $fh = IO::File->new('some file', '>');
263           $dropbox->download($path, $fh, { headers => ['Range' => 'bytes=5-6'] });
264
265           # If-None-Match / ETag
266           my $fh = IO::File->new('some file', '>');
267           $dropbox->download($path, $fh);
268
269           # $dropbox->res->code => 200
270
271           my $etag = $dropbox->res->header('ETag');
272
273           $dropbox->download($path, $fh, { headers => ['If-None-Match', $etag] });
274
275           # $dropbox->res->code => 304
276
277       <https://www.dropbox.com/developers/documentation/http/documentation#files-download>
278
279       get_metadata($path [, \%optional_params])
280
281       Returns the metadata for a file or folder.
282
283       Note: Metadata for the root folder is unsupported.
284
285           my $result = $dropbox->get_metadata($path);
286
287           my $result = $dropbox->get_metadata($path, {
288               include_media_info => JSON::true,
289               include_deleted => JSON::true,
290               include_has_explicit_shared_members => JSON::false,
291           });
292
293       <https://www.dropbox.com/developers/documentation/http/documentation#files-get_metadata>
294
295       get_preview($path, $outout [, \%opts])
296
297       Get a preview for a file. Currently previews are only generated for the
298       files with the following extensions: .doc, .docx, .docm, .ppt, .pps,
299       .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf
300
301           # File handle
302           my $fh = IO::File->new('some file', '>');
303           $dropbox->get_preview($path, $fh);
304
305           # Code reference
306           my $write_code = sub {
307               # compatible with LWP::UserAgent and Furl::HTTP
308               my $chunk = @_ == 4 ? @_[3] : $_[0];
309               print $chunk;
310           };
311           $dropbox->get_preview($path, $write_code);
312
313           # Range
314           my $fh = IO::File->new('some file', '>');
315           $dropbox->get_preview($path, $fh, { headers => ['Range' => 'bytes=5-6'] });
316
317           # If-None-Match / ETag
318           my $fh = IO::File->new('some file', '>');
319           $dropbox->get_preview($path, $fh);
320
321           # $dropbox->res->code => 200
322
323           my $etag = $dropbox->res->header('ETag');
324
325           $dropbox->get_preview($path, $fh, { headers => ['If-None-Match', $etag] });
326
327           # $dropbox->res->code => 304
328
329       <https://www.dropbox.com/developers/documentation/http/documentation#files-get_preview>
330
331       get_temporary_link($path)
332
333       Get a temporary link to stream content of a file. This link will expire
334       in four hours and afterwards you will get 410 Gone. Content-Type of the
335       link is determined automatically by the file's mime type.
336
337           my $result = $dropbox->get_temporary_link($path);
338
339           my $content_type = $dropbox->res->header('Content-Type');
340
341       <https://www.dropbox.com/developers/documentation/http/documentation#files-get_temporary_link>
342
343       get_thumbnail($path, $output [, \%optional_params, $opts])
344
345       Get a thumbnail for an image.
346
347       This method currently supports files with the following file
348       extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are
349       larger than 20MB in size won't be converted to a thumbnail.
350
351           # File handle
352           my $fh = IO::File->new('some file', '>');
353           $dropbox->get_thumbnail($path, $fh);
354
355           my $optional_params = {
356               format => 'jpeg',
357               size => 'w64h64'
358           };
359
360           $dropbox->get_thumbnail($path, $fh, $optional_params);
361
362           # Code reference
363           my $write_code = sub {
364               # compatible with LWP::UserAgent and Furl::HTTP
365               my $chunk = @_ == 4 ? @_[3] : $_[0];
366               print $chunk;
367           };
368           $dropbox->get_thumbnail($path, $write_code);
369
370           # Range
371           my $fh = IO::File->new('some file', '>');
372           $dropbox->get_thumbnail($path, $fh, $optional_params, { headers => ['Range' => 'bytes=5-6'] });
373
374           # If-None-Match / ETag
375           my $fh = IO::File->new('some file', '>');
376           $dropbox->get_thumbnail($path, $fh);
377
378           # $dropbox->res->code => 200
379
380           my $etag = $dropbox->res->header('ETag');
381
382           $dropbox->get_thumbnail($path, $fh, $optional_params, { headers => ['If-None-Match', $etag] });
383
384           # $dropbox->res->code => 304
385
386       <https://www.dropbox.com/developers/documentation/http/documentation#files-get_thumbnail>
387
388       list_folder($path [, \%optional_params])
389
390       Returns the contents of a folder.
391
392           my $result = $dropbox->list_folder($path);
393
394           my $result = $dropbox->list_folder($path, {
395               recursive => JSON::false,
396               include_media_info => JSON::false,
397               include_deleted => JSON::false,
398               include_has_explicit_shared_members => JSON::false
399           });
400
401       <https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder>
402
403       list_folder_continue($cursor)
404
405       Once a cursor has been retrieved from list_folder, use this to paginate
406       through all files and retrieve updates to the folder.
407
408           my $result = $dropbox->list_folder_continue($cursor);
409
410       <https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder-continue>
411
412       list_folder_get_latest_cursor($path [, \%optional_params])
413
414       A way to quickly get a cursor for the folder's state. Unlike
415       list_folder, list_folder/get_latest_cursor doesn't return any entries.
416       This endpoint is for app which only needs to know about new files and
417       modifications and doesn't need to know about files that already exist
418       in Dropbox.
419
420           my $result = $dropbox->list_folder_get_latest_cursor($path);
421
422           my $result = $dropbox->list_folder_get_latest_cursor($path, {
423               recursive => JSON::false,
424               include_media_info => JSON::false,
425               include_deleted => JSON::false,
426               include_has_explicit_shared_members => JSON::false
427           });
428
429       <https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder-get_latest_cursor>
430
431       list_folder_longpoll($cursor [, \%optional_params])
432
433       A longpoll endpoint to wait for changes on an account. In conjunction
434       with list_folder/continue, this call gives you a low-latency way to
435       monitor an account for file changes. The connection will block until
436       there are changes available or a timeout occurs. This endpoint is
437       useful mostly for client-side apps. If you're looking for server-side
438       notifications, check out our webhooks documentation.
439
440           my $result = $dropbox->list_folder_longpoll($cursor);
441
442           my $result = $dropbox->list_folder_longpoll($cursor, {
443               timeout => 30
444           });
445
446       <https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder-longpoll>
447
448       list_revisions($path [, \%optional_params])
449
450       Return revisions of a file.
451
452           my $result = $dropbox->list_revisions($path);
453
454           my $result = $dropbox->list_revisions($path, {
455               limit => 10
456           });
457
458       <https://www.dropbox.com/developers/documentation/http/documentation#files-list_revisions>
459
460       move($from_path, $to_path)
461
462       Return revisions of a file.
463
464           my $result = $dropbox->move($from_path, $to_path);
465
466       <https://www.dropbox.com/developers/documentation/http/documentation#files-move>
467
468       permanently_delete($path)
469
470       Permanently delete the file or folder at a given path (see
471       https://www.dropbox.com/en/help/40).
472
473       Note: This endpoint is only available for Dropbox Business apps.
474
475           my $result = $dropbox->permanently_delete($path);
476
477       <https://www.dropbox.com/developers/documentation/http/documentation#files-permanently_delete>
478
479       restore($path, $rev)
480
481       Restore a file to a specific revision.
482
483           my $result = $dropbox->restore($path, $rev);
484
485       <https://www.dropbox.com/developers/documentation/http/documentation#files-restore>
486
487       save_url($path, $url)
488
489       Save a specified URL into a file in user's Dropbox. If the given path
490       already exists, the file will be renamed to avoid the conflict (e.g.
491       myfile (1).txt).
492
493           my $result = $dropbox->save_url($path, $url);
494
495       <https://www.dropbox.com/developers/documentation/http/documentation#files-save_url>
496
497       save_url_check_job_status($async_job_id)
498
499       Check the status of a save_url job.
500
501           my $result = $dropbox->save_url_check_job_status($async_job_id);
502
503       <https://www.dropbox.com/developers/documentation/http/documentation#files-save_url-check_job_status>
504
505       search($path, $query, [, \%optional_params])
506
507       Searches for files and folders.
508
509       Note: Recent changes may not immediately be reflected in search results
510       due to a short delay in indexing.
511
512           my $result = $dropbox->search($path);
513
514           my $result = $dropbox->search($path, 'prime numbers', {
515               start => 0,
516               max_results => 100,
517               mode => 'filename'
518           });
519
520       <https://www.dropbox.com/developers/documentation/http/documentation#files-search>
521
522       upload($path, $content [, \%optional_params])
523
524       Create a new file with the contents provided in the request.
525
526       Do not use this to upload a file larger than 150 MB. Instead, create an
527       upload session with upload_session/start.
528
529           # File Handle
530           my $content = IO::File->new('./my.cnf', '<');
531
532           my $result = $dropbox->upload($path, $content);
533
534           my $result = $dropbox->upload($path, $content, {
535               mode => 'add',
536               autorename => JSON::true,
537               mute => JSON::false
538           });
539
540       <https://www.dropbox.com/developers/documentation/http/documentation#files-upload>
541
542       upload_session($path, $content [, \%optional_params, $limit])
543
544       Uploads large files by upload_session API
545
546           # File Handle
547           my $content = IO::File->new('./mysql.dump', '<');
548
549           my $result = $dropbox->upload_session($path, $content);
550
551           my $result = $dropbox->upload_session($path, $content, {
552               mode => 'add',
553               autorename => JSON::true,
554               mute => JSON::false
555           });
556
557       <https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-start>
558       <https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-append_v2>
559       <https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-finish>
560
561       upload_session_start($content [, \%optional_params])
562
563       Upload sessions allow you to upload a single file using multiple
564       requests. This call starts a new upload session with the given data.
565       You can then use upload_session/append_v2 to add more data and
566       upload_session/finish to save all the data to a file in Dropbox.
567
568       A single request should not upload more than 150 MB of file contents.
569
570           # File Handle
571           my $content = IO::File->new('./access.log', '<');
572
573           $dropbox->upload_session_start($content);
574
575           $dropbox->upload_session_start($content, {
576               close => JSON::true
577           });
578
579       <https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-start>
580
581       upload_session_append_v2($content, $params)
582
583       Append more data to an upload session.
584
585       When the parameter close is set, this call will close the session.
586
587       A single request should not upload more than 150 MB of file contents.
588
589           # File Handle
590           my $content = IO::File->new('./access.log.1', '<');
591
592           my $result = $dropbox->upload_session_append_v2($content, {
593               cursor => {
594                   session_id => $session_id,
595                   offset => $offset
596               },
597               close => JSON::true
598           });
599
600       <https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-append_v2>
601
602       upload_session_finish($content, $params)
603
604       Finish an upload session and save the uploaded data to the given file
605       path.
606
607       A single request should not upload more than 150 MB of file contents.
608
609           # File Handle
610           my $content = IO::File->new('./access.log.last', '<');
611
612           my $result = $dropbox->upload_session_finish($content, {
613               cursor => {
614                   session_id => $session_id,
615                   offset => $offset
616               },
617               commit => {
618                   path => '/Homework/math/Matrices.txt',
619                   mode => 'add',
620                   autorename => JSON::true,
621                   mute => JSON::false
622               }
623           });
624
625       <https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-finish>
626
627   Users
628       get_account($account_id)
629
630       Get information about a user's account.
631
632           my $result = $dropbox->get_account($account_id);
633
634       <https://www.dropbox.com/developers/documentation/http/documentation#users-get_account>
635
636       get_account_batch(\@account_ids)
637
638       Get information about multiple user accounts. At most 300 accounts may
639       be queried per request.
640
641           my $result = $dropbox->get_account_batch($account_ids);
642
643       <https://www.dropbox.com/developers/documentation/http/documentation#users-get_account_batch>
644
645       get_current_account()
646
647       Get information about the current user's account.
648
649           my $result = $dropbox->get_current_account;
650
651       <https://www.dropbox.com/developers/documentation/http/documentation#users-get_current_account>
652
653       get_space_usage()
654
655       Get the space usage information for the current user's account.
656
657           my $result = $dropbox->get_space_usage;
658
659       <https://www.dropbox.com/developers/documentation/http/documentation#users-get_space_usage>
660
661   Error Handling and Debug
662       error : str
663
664           my $result = $dropbox->$some_api;
665           unless ($result) {
666               die $dropbox->error;
667           }
668
669       req : HTTP::Request or Furl::Request
670
671           my $result = $dropbox->$some_api;
672
673           warn $dropbox->req->as_string;
674
675       res : HTTP::Response or Furl::Response
676
677           my $result = $dropbox->$some_api;
678
679           warn $dropbox->res->code;
680           warn $dropbox->res->header('ETag');
681           warn $dropbox->res->header('Content-Type');
682           warn $dropbox->res->header('Content-Length');
683           warn $dropbox->res->header('X-Dropbox-Request-Id');
684           warn $dropbox->res->as_string;
685
686       env_proxy
687
688       enable HTTP_PROXY, NO_PROXY
689
690           my $dropbox = WebService::Dropbox->new();
691
692           $dropbox->env_proxy;
693
694       debug
695
696       enable or disable debug mode
697
698           my $dropbox = WebService::Dropbox->new();
699
700           $dropbox->debug; # disabled
701           $dropbox->debug(0); # disabled
702           $dropbox->debug(1); # enabled
703
704       verbose
705
706       more warnings.
707
708           my $dropbox = WebService::Dropbox->new();
709
710           $dropbox->verbose; # disabled
711           $dropbox->verbose(0); # disabled
712           $dropbox->verbose(1); # enabled
713

AUTHOR

715       Shinichiro Aska
716

LICENSE

722       This library is free software; you can redistribute it and/or modify it
723       under the same terms as Perl itself.
724
725
726
727perl v5.32.0                      2020-07-28          WebService::Dropbox(3pm)