WebService::GData::Base - core read/write methods over HTTP for google data API v2.
use WebService::GData::Base; #read only my $base = new WebService::GData::Base(); my $ret = $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'); my $feed = $ret->{feed}; #give write access $base->auth($auth); #now you can #get hidden/private contents my $ret = $base->get('http://gdata.youtube.com/feeds/api/users/default/playlists'); #new entry with application/x-www-form-urlencoded content-type my $ret = $base->post('http://gdata.youtube.com/feeds/api/users/default/playlists',$content); my $ret = $base->delete('http://gdata.youtube.com/feeds/api/users/playlist/'.$someid); #the content type is application/atom+xml; charset=UTF-8 my $ret = $base->insert($uri,$content,$callback); #the content type is application/atom+xml; charset=UTF-8 my $ret = $base->update($uri,$content,$callback); #modify the query string query string: ?alt=jsonc&v=2&prettyprint=false&strict=true $base->query->alt('jsonc')->prettyprint('false'); #overwrite WebService::GData::Query with youtube query parameters $base->query(new WebService::GData::YouTube::Query); #now the query will have the following query string: #?alt=json&v=2&prettyprint=false&strict=true&safeSearch=none $base->query->safe_search('none');
inherits from WebService::GData
This package allows you to manipulate the data stored on Google servers. It grants you access to the main read/write (get,post,insert,update,delete) methods available for the google data APIs by wrapping LWP methods. Some actions require to be authenticated (ClientLogin,OAuth,SubAuth). If an authentication object is set at construction time, it will be called to add any extra headers the authentication mechanism requires. This package should be inherited by services (youtube,analytics,calendar) to offer higher level of abstraction.
Every request (get,post,insert,update,delete) will throw a WebService::GData::Error in case of failure. It is therefore recommanded to enclose your code in eval blocks to catch and handle the error as you see fit.
The google data based APIs offer different format for the core protocol: atom based, rss based,json based, jsonc based. In order to offer good parsing performance, we use the json based response as a default to get() the feeds. Unfortunately, if we can read the feeds in json,the write methods require atom based data. The server also sends back an atom response too. We have therefore a hugly mixed of atom/json logic for now.
Create an instance.
Parameters
auth:AuthObject
Returns
Example:
use WebService::GData::Base; my $base = new WebService::GData::Base(auth=>$auth);
Set/get an auth object that handles access to protected contents. The auth object will be used by post/insert/update/delete methods by calling two methods:
set_authorization_headers(base:WebService::GData::Base,req:HTTP::Request)
- Headers required by the authentication protocol.
set_service_headers(base:WebService::GData::Base,req:HTTP::Request)
- Extra headers required by a particular service.
source()
- The name of the application. Will be used for the user agent string.
These methods will receive the instance calling them and the request instance. They shall add any extra headers required to implement their own authentication protocol (ie,ClientLogin,OAuth,SubAuth). If the object can not handle the above methods it will not be set.
none
auth:Object
use WebService::GData::Base; #should be in a eval {... }; block to catch an error... my $auth = new WebService::GData::ClientLogin(email=>...); my $base = new WebService::GData::Base(auth=>$auth); #or my $base = new WebService::GData::Base(); $base -> auth($auth);
Set/get a query object that handles the creation of the query string. The query object will be used to add extra query parameters when calling WebService::GData::Base::get().
The query object should only implement the following methods (do not need to inherit from WebService::GData::Query):
get('value-name') - Gives access to a parameter value
get('value-name')
to_query_string() - return the query string.
to_query_string()
get('v') - should return a version number >=WebService::GData::Constants::GDATA_MINIMUM_VERSION
get('v')
query:Object
The WebService::GData::Query returns by default:
'?alt=json&prettyprint=false&strict=true&v=2'
when to_query_string() is called.
When you call WebService::GData::Base::get(), you should only set an url with no query string:
use WebService::GData::Constants qw(:all); use WebService::GData::Base; #should be in a eval { ... }; block... my $auth = new WebService::GData::ClientLogin(email=>...); my $base = new WebService::GData::Base(auth=>$auth); $base->query->alt(JSONC); $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'); #is in fact calling: #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=jsonc&prettyprint=false&strict=true&v=2 #or set a new query object: $base->query(new WebService::GData::YouTube::Query());
Set/get the override method.
Depending on your server configurations, you might not be able to set the method to PUT/DELETE/PATCH. This will forbid you to do any updates or deletes. In such a case, you should set override_method to TRUE so that it uses the POST method but override it by the proper value (ie,PUT/DELETE/PATCH) using X-HTTP-Method-Override.
true_or_false:Scalar
void
override_state:Scalar
use WebService::GData::Constants qw(:all); use WebService::GData::Base; #using override_method makes sense only if you are logged in #and want to do some write methods. my $auth = new WebService::GData::ClientLogin(email=>...); my $base = new WebService::GData::Base(auth=>$auth); $base->override_method(TRUE); $base->update($url,$content);
Get the last queried uri.
uri:Scalar
use WebService::GData::Base; my $base = new WebService::GData::Base(); $base->get('http://www.example.com?v=2'); $base->get_uri();#'http://www.example.com'
Get the user agent name setted.
use WebService::GData::Base; my $base = new WebService::GData::Base(); $base->get('http://www.example.com?v=2'); $base->get_user_agent_name();#WebService::GData::Base/2 $base->auth($auth);#where $auth->source eq 'MyApp-MyCompany-ID' $base->get_user_agent_name();#MyApp-MyCompany-ID WebService::GData::Base/2
Get the content of a feed in any format. If the format is json or jsonc, it will send back a perl object. If an auth object is specified, it will call the required methods to set the authentication headers. It will also set the 'GData-Version' header by calling $this->query->get('v'); You should put the code in a eval { ... }; block to catch any error.
url:Scalar
Query string will be removed before sending the request.
response:Object|Scalar
Throws
use WebService::GData::Base; my $base = new WebService::GData::Base(); $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'); #is in fact calling: #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=json&prettyprint=false&strict=true&v=2 #the query string will be erased and change to query->to_query_string() $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=atom'); #is in fact calling: #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=json&prettyprint=false&strict=true&v=2
All the following methods will set the 'GData-Version' header by calling $this->query->get('v'); You should put the code in a eval { ... }; block to catch any error these methods may throw.
Post data to an url with application/x-www-form-urlencoded content type. An auth object must be specified. it will call the required methods to set the authentication headers.
content:Scalar|Binary
response:Scalar
use WebService::GData::Base; #you must be authorized to do any write actions. my $base = new WebService::GData::Base(auth=>...); #create a new entry with application/x-www-form-urlencoded content-type my $ret = $base->post($url,$content);
Insert data to an url with application/atom+xml; charset=UTF-8 content type (POST). An auth object must be specified. it will call the required methods to set the authentication headers.
content:Scalar
use WebService::GData::Base; #you must be authorized to do any write actions. my $base = new WebService::GData::Base(auth=>...); #create a new entry with application/atom+xml; charset=UTF-8 content-type my $ret = $base->insert($url,$content);
Update data to an url with application/atom+xml; charset=UTF-8 content type (PUT). An auth object must be specified. it will call the required methods to set the authentication headers.
use WebService::GData::Base; #you must be authorized to do any write actions. my $base = new WebService::GData::Base(auth=>...); #create a new entry with application/atom+xml; charset=UTF-8 content-type my $ret = $base->upate($url,$content);
Delete data from an url with application/atom+xml; charset=UTF-8 content type (DELETE).
use WebService::GData::Base; #you must be authorized to do any write actions. my $base = new WebService::GData::Base(auth=>...); #create a new entry with application/atom+xml; charset=UTF-8 content-type my $ret = $base->delete($url);
Google data APIs relies on querying remote urls on particular services.
Some of these services limits the number of request with quotas and may return an error code in such a case.
All queries that fail will throw (die) a WebService::GData::Error object.
You should enclose all code that requires connecting to a service within eval blocks in order to handle it.
use WebService::GData::Base; my $base = new WebService::GData::Base(); #the server is dead or the url is not available anymore or you've reach your quota of the day. #boom the application dies and your program fails... $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'); #with error handling... #enclose your code in a eval block... eval { $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'); }; #if something went wrong, you will get a WebService::GData::Error object back: if(my $error = $@){ #do whatever you think is necessary to recover (or not) #print/log: $error->content,$error->code }
JSON
LWP
If you do me the favor to _use_ this module and find a bug, please email me i will try to do my best to fix it (patches welcome)!
shiriru <shirirulestheworld[arobas]gmail.com>
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install WebService::GData, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::GData
CPAN shell
perl -MCPAN -e shell install WebService::GData
For more information on module installation, please visit the detailed CPAN module installation guide.