NAME
Net::OpenSocial::Client - OpenSocial REST/RPC Client
SYNOPSIS
use Net::OpenSocial::Client;
use Net::OpenSocial::Client::Container::OrkutSandbox;
use Net::OpenSocial::Client::Type::Protocol qw(REST RPC);
use Data::Dump qw(dump);
my $client = Net::OpenSocial::Client->new(
container => Net::OpenSocial::Client::Container::OrkutSandbox->new,
consumer_key => q{orkut.com:623061448914},
consumer_secret => q{uynAeXiWTisflWX99KU1D2q5},
requestor => q{03067092798963641994},
protocol_type => RPC,
);
my $friends = $client->get_friends('@me')
or die $client->errstr;
for my $person ( @{ $friends->items } ) {
say $person->get_field('id');
...
say dump($person->fields);
}DESCRIPTION
OpenSocial provides API endpoints which called 'RESTful API' and 'RPC'. This module allows you to handle it easily. This provides you a same interface for both REST-API and RPC, so you don't need to mind about the big differences between them.
SIMPLE USAGE
If you don't need to handle multiple requests at once for more effective performance (batch request), this module provides you some simple methods that can handle resources easily.
my $client = Net::OpenSocial::Client->new(...);
my $user_id = '@me';
my $person = $client->get_person( $user_id )
or die $client->errstr;
say $person->get_field('id');
my $friends = $client->get_friends( $user_id )
or die $client->errstr;
foreach my $friend ( @{ $friends->items } ) {
say $friend->get_field('id');
}For more details, look at each methods' document.
RAW APIs AND BATCH REQUEST
BUILD REQUEST
You can build a request object by yourself or choose from preset. See Net::OpenSocial::Client::Request.
my $request = Net::OpenSocial::Client::Request->new(
service => PEOPLE,
operation => GET,
user_id => '@me',
group_id => '@friends',
params => {
itemsPerPage => 10,
startIndex => 10,
},
);or
my $request = Net::OpenSocial::Client::Request::FetchFriends->new( '@me',
{ itemsPerPage => 10, startIndex => 10 } );EXECUTE REQUEST
You should add request to client with request-id.
$client->add_request( req1 => $request1 );
$client->add_request( req2 => $request2 );Only execute 'add_request', you can't obtain a result corresponding to the requests. To get them, you have to call 'send'.
my $result_set = $client->send()Internally, it works apropriately according to the protocol type you choose. If RPC is selected, multiple requests are send as one single http-request. Or with REST, it send multiple http-request for each opensocial-request. And it returns Net::OpenSocial::Client::ResultSet object.
PICK UP RESULT
Pick up Net::OpenSocial::Client::Result object with request-id you passed when invoking 'add_request'.
my $result1 = $result_set->get_result('req1');
my $result2 = $result_set->get_result('req2');HANDLE DATA
if ( $result1->is_error ) {
die sprintf q{%d: %s.},
$result->code, $result->message;
} else {
my $data = $result1->data;
...
}the data may be Net::OpenSocial::Client::Collection or Net::OpenSocial::Client::Resource subclass's object. such like Net::OpenSocial::Client::Resource::Person ,Net::OpenSocial::Client::Resource::Activity ,Net::OpenSocial::Client::Resource::AppData , or Net::OpenSocial::Client::Resource::Group.
METHODS
new
use Net::OpenSocial::Client::Type::Auth qw(OAUTH ST);
use Net::OpenSocial::Client::Type::Format qw(JSON XML);
use Net::OpenSocial::Client::Type::Protocol qw(REST RPC);
my $client = Net::OpenSocial::Client->new(
container => $container,
auty_type => OAUTH,
format_type => JSON,
protocol_type => REST,
);container
First, you have to prepare Net::OpenSocial::Client::Container object. You can build it with container-information you want to access as of now, or choose from preset. There exists container objects which support major provider.
Net::OpenSocial::Client::Container::Orkut Net::OpenSocial::Client::Container::MySpace Net::OpenSocial::Client::Container::Google and etc.
my $container = Net::OpenSocial::Client::Container->new(...);or
my $container = Net::OpenSocial::Client::Container::MySpace->new;auth_type
Authorization type. You can choose from OAUTH and ST. OAUTH means 2-legged or 3-legged OAuth. When you choose OAUTH type, you have to pass both 'consumer_key' and 'consumer_secret' parameter which you got on provider beforehand.
my $client = Net::OpenSocial::Client->new(
auth_type => OAUTH, # you can omit this. OAUTH is set by default.
consumer_key => q{foobarbuz},
consumer_secret => q{foobarbuz},
...
);And if you want to use 3-legged OAuth, you need to pass authorized access-token. You should already have completed OAuth authorization process. See OAuth::Lite::Consumer.
my $access_token = OAuth::Lite::Token->new( token => q{aaa}, secret => {bbb} );
my $client = Net::OpenSocial::Client->new(
auth_type => OAUTH, # you can omit this. OAUTH is set by default.
consumer_key => q{foobarbuz},
consumer_secret => q{foobarbuz},
token => $access_token,
...
);Or in case you try 2-legged OAuth. pass user-id of xoauth_request_id as 'requestor' parameter.
my $client = Net::OpenSocial::Client->new(
auth_type => OAUTH, # you can omit this. OAUTH is set by default.
consumer_key => q{foobarbuz},
consumer_secret => q{foobarbuz},
requestor => q{myid},
...
);ST means security-token. You have pass to security-token as 'st' parameter.
my $client = Net::OpenSocial::Client->new(
auth_type => ST,
st => q{foobarbuz},
...
);format_type
Now it only supports JSON format, so, it sets JSON by default.
protocol_type
REST or RPC. REST is set by default. Make sure that the container which you want to access supports the protocol.
If container supports RPC, and you choose it, you can execute batch request.
BUILDARGS
See Moose, Mouse. You don't need to call this method directly.
add_request( $request )
Pass Net::OpenSocial::Client::Request or its subclass's object. At this time, noghing happens. When you execute 'send' method, You will get the result of this request.
You should make ID string for the request arbitrarily, and set it with the request. Remember this ID to pick up a result you want from result-set that you get after executing 'send' method.
$client->add_request( $request_id => $request );send()
This method send all requests that you added by 'add_request' before you call this. If it's done successfuly, it returns a Net::OpenSocial::Client::ResultSet object.
To obtain a result you want, you need to invoke 'get_result' method of result-set object with request-id you set when you do 'add_request'. Then it returns a Net::OpenSocial::Client::Result object.
my $result_set = $client->send()
or die $client->errstr;
my $result = $result_set->get_result($request_id);get_people( $user_id, $group_id, $option )
my $people = $client->get_people( '@me', '@friends', { itemsPerPage => 10 } );
say $people->count;
for my $person ( @{ $people->items } ) {
say $person->get_field('id');
}get_person( $user_id )
my $person = $client->get_person('@me');
say $person->get_field('id');get_friends( $user_id, $option )
my $people = $client->get_people( '@me', { itemsPerPage => 10 } );
say $people->count;
for my $person ( @{ $people->items } ) {
say $person->get_field('id');
}get_person_appdata( $user_id, $option )
returns Net::OpenSocial::Client::Resource::AppData.
my $appdata = $client->get_person_appdata('@me')
or die $client->errstr;
say $appdata->get_data($user_id, $key);get_friends_appdata( $user_id, $option )
my $collection = $client->get_friends_appdata('@me')
or die $client->errstr;
for my $appdata ( @{ $collection->items } ) {
...
}DEVELOPMENT
I'm woking on github. http://github.com/lyokato/p5-net-opensocial-client/tree/master
SEE ALSO
http://code.google.com/apis/opensocial/docs/, http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-protocol, http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/rpc-protocol, http://code.google.com/apis/friendconnect/opensocial_rest_rpc.html http://blog.opensocial.org/2008/12/opensocial-now-friends-with-php-java.html
AUTHOR
Lyo Kato, <lyo.kato@gmail.com>
COPYRIGHT AND LICENSE
Copyright (C) 2009 by Lyo Kato
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.