Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VUser::Google::ProvisiUsergContributed)VUser::Google::ProvisioningAPI::V1_0(3)

NAME
       VUser::Google::ProvisioningAPI::V1_0 - Perl module that implements
       version 1.0 of the Google Apps for Your Domain Provisioning API

SYNOPSIS
	 use VUser::Google::ProvisioningAPI;
	 my $google = new VUser::Google::ProvisioningAPI($domain,$admin,$password);

	 $google->CreateAccount($userName, $firstName, $lastName, $password);
	 $google->RetrieveAccount($userName);

REQUIREMENTS
       VUser::Google::ProvisioningAPI requires the following modules to	be
       installed:

       o   "LWP::UserAgent"

       o   "HTTP::Request"

       o   "Encode"

       o   "XML::Simple"

DESCRIPTION
       VUser::Google::ProvisioningAPI provides a simple	interface to the
       Google Apps for Your Domain Provisioning	API.  It uses the
       "LWP::UserAgent"	module for the HTTP transport, and the "HTTP::Request"
       module for the HTTP request and response.

   Examples
       For a complete description of the meaning of the	following methods, see
       the Google API documentation referenced in the SEE ALSO section.

	       #create the object
	       $google = new Google:ProvisioningAPI($domain,$admin,$password) || die "Cannot create google object";

	       print 'Module version: '	. $google->VERSION . "\nAPI Version: " . $google->version() . "\n";

	       #create a hosted	account
	       if( $google->CreateAccount( $userName, $firstName, $lastName, $password ) )
	       {
		       print "Account created!\N";
	       }

	       #add email services to the account
	       $google->UpdateAccountEmail($userName);

	       #retrieving account data
	       if($google->RetrieveAccount($userName))
	       {
		       print 'Username:	' . $google->{result}->{RetrievalSection}->{userName} .	"\n";
		       print 'firstName: ' . $google->{result}->{RetrievalSection}->{firstName}	. "\n";
		       print 'lastName:	' . $google->{result}->{RetrievalSection}->{lastName} .	"\n";
		       print 'accountStatus: ' . $google->{result}->{RetrievalSection}->{accountStatus}	. "\n";

	       }

	       #see what the result hash after a request looks like
	       use Data::Dumper;
	       print Dumper($google->{result});

	       #delete an account
	       $ret = DeleteAccount($userName);

	       #accessing the HTML data	as it was received from	the Google servers:
	       print $google->replyheaders();
	       print $google->replycontent();

CONSTRUCTOR
       new ( $domain, $admin, $adminpassword )

       This is the constructor for a new VUser::Google::ProvisioningAPI
       object.	$domain	is the domain name registered with Google Apps For
       Your Domain, $admin is an account in the	above domain that has the
       right to	manage that domain, and	$adminpassword is the password for
       that account.

       Note that the constructor will NOT attempt to perform the 'ClientLogin'
       call to the Google Provisioning API (see	below).	 Authentication
       happens automatically when the first API	call is	performed. The token
       will be remembered for the duration of the object, and will be
       automatically refreshed as needed.  If you want to verify that you can
       get a valid token before	performing any operations, follow the
       constructor with	a call to IsAuthenticated() as such:

	       print "Authentication OK\n" unless not $google->IsAuthenticated();

METHODS
       Below are all the methods available on the object. For the Google API
       specific	methods, see the Google	API documentation for more details.
       When a request is properly handled by Google's API engine, the webpost
       to the API succeeds. This results in a valid page being returned. The
       content of this page then defines whether the request succeeded or not.
       All pages returing the 'Success(2000)' status code will result in the
       API method succeeding, and returning a 1. All failures return 0.
       Please see the section below on how to access the result	data, and how
       to determine the	reasons	for errors.

       If the web post fails (as determined by the "HTTP::Request" method
       IsSuccess() ), the method returns 0, and	the {reason} hash is set to a
       descriptive error.  You can then	examine	the raw	data to	get an idea of
       what went wrong.

   Checking Authentication
       IsAuthenticated()

	   will	check if the object has	been able to authenticate with
	   Google's api	engine,	and get	an authentication ticket.  Returns 1
	   if successful, 0 on failure.	To see why it may fail,	see the	$@
	   variable, and the $google->{results}->{reason} hash,	and parse the
	   returned page (see the 'content' and	'header' variables.)

   Methods to Create/Retrieve/Delete
       'Hosted account'	methods

       CreateAccountEmail(  $userName, $firstName, $lastName, $password,
       $quota )

	   Creates a hosted account with email services	in your	domains	name
	   space.  The first 4 arguments are required. The $quota argument is
	   optional. If	$quota is given, the <quota> tag will be sent with the
	   request, otherwize is will be omitted.  See the Google API docs for
	   the API call	for more details.

       CreateAccount(  $userName, $firstName, $lastName, $password )

	   Creates a hosted account in your domains name space.	This account
	   does	NOT have email services	by default.  You need to call
	   UpdateAccountEmail()	to add email services.	NOTE: this API call
	   may be discontinued!	See CreateAccountEmail() for a replacement.

       UpdateAccount( $username, $firstName, $lastName,	$password )

	   $username is	the mandatory name of the hosted account. The
	   remaining paramaters	are optional, and can be set to	'undef'	if you
	   do not wish to change them Eg. to change the	password on an
	   account, call this as;

	       UpdateAccount( $username, undef,	undef, 'newpassword' );

	   to change names only, you would call	it as such:

	       UpdateAccount( $username, 'newfirstname', 'newlastname',	undef );

       UpdateAccountEmail( $userName )

	   Adds	email services to a hosted account created with
	   CreateAccount().  NOTE: this	API call may be	discontinued! See
	   CreateAccountEmail()	for a replacement.

       UpdateAccountStatus( $userName, $status )

	   $status is either 'locked' or 'unlocked'

       RetrieveAccount(	$userName )

       DeleteAccount( $userName	)

       RenameAccount( $oldName,	$newName, $alias )

	   $alias is either '1'	or '0'

	   WARNING: this method	is derived from	the Python sample code
	   provided by Google: (Ie. this may not work yet) "Username change.
	   Note	that this feature must be explicitly enabled by	the domain
	   administrator, and is not enabled by	default.  Args:

	       oldname:	user to	rename newname:	new username to	set for	the
	       user alias: if 1, create	an alias of oldname for	newname"

       'Alias' methods

       CreateAlias( $userName, $alias )

       RetrieveAlias( $userName	);

       DeleteAlias( $alias );

       'Mailing	List' methods

       CreateMailingList( $mailingListName )

       UpdateMailingList( $mailingListName, $userName, $listOperation )

	   $listOperation is either 'add' or 'remove'

       RetrieveMailingList( $mailingListName )

       DeleteMailingList( $mailingListName )

   Methods to set/get variables
       After creating the object you can get/set the administrator account and
       set the password	with these methods.  Note this will cause a re-
       authentication next time	a Google API method is called.

       admin( $admin )

	   set the administrative user,	and will return	administator username.

       password( $string )

	   set the password, returns an	empty string

   Miscelleaneous statistics methods
       There are a few methods to access some statistics data that is
       collected while the object performing Google API	calls.

       authtime()

	   returns the time of last authentication, as generated by the	time()
	   function

       ctime()

	   returns the create time of the object, as generated by the time()
	   function

       rtime()

	   returns the time of the most	recent request,	as generated by	the
	   time() function

       logins()

	   returns the number of API logins that have been performed

       requests()

	   returns the numbers of API requests that have been submitted	to
	   Google

       success()

	   returns the numbers of successful api request performed

       And finally,

       version()

	   returns a string with the api version implemented. This is
	   currently '1.0'

ACCESSING RESULTING DATA
       Valid return data from Google is	parsed into a hash named 'result',
       available through the object. In	this hash you can find all elements as
       returned	by Google.  This hash is produced by XML::Simple. See the
       Google API documentation	in the SEE ALSO	section	for complete details.
       Some of the more	useful elements	you may	need to	look at	are:

	       $google->{result}->{reason}	       #this typically has the textual reason for a failure
	       $google->{result}->{extendedMessage}    #a more extensive description of	the failure reason may be here
	       $google->{result}->{result}	       #typically empty!
	       $google->{result}->{type}	       #should be same of query	type, eg 'Account', 'Alias', 'MailingList'

       The retrieval section contains data when	you are	querying. Here is what
       this section looks like when you	call the RetrieveAccount method:

	       $google->{result}->{RetrievalSection}->{firstName}
	       $google->{result}->{RetrievalSection}->{lastName}
	       $google->{result}->{RetrievalSection}->{accountStatus}
	       $google->{result}->{RetrievalSection}->{aliases}->{alias}
	       $google->{result}->{RetrievalSection}->{emailLists}->{emailList}

       To see the structure of the result hash,	use the	Data::Dumper module as
       such:

	       use Data::Dumper;
	       print Dumper($google->{result});

ACCESSING RAW GOOGLE POST AND RESULT DATA
       The data	from the most recent post to the Google	servers	is available.
       You can access it as:

	       print $google->requestcontent();

       The most	recent received	HTML data is stored in two parts, the headers
       and the content.	Both are strings. They can be accessed as such:

	       print $google->replyheaders();
	       print $google->replycontent();

       Note the	headers	are new-line separated and can easily be parsed:

	       foreach my $headerline (	split/\n/, $g->replyheaders() )
	       {
		       my ($header, $value) = split/:/,	$headerline;
	       }

EXPORT
       None by default.

SEE ALSO
       The official Google documentation can be	found at
       http://code.google.com/apis/apps-for-your-domain/google_apps_provisioning_api_v1.0_reference.html

       For support, see	the Google Group at
       http://groups.google.com/group/apps-for-your-domain-apis

       For additional support specific to this modules,	email me at johan at
       reinalda	dot net.

AUTHOR
       Johan Reinalda, johan at	reinalda dot net

COPYRIGHT AND LICENSE
       Copyright (C) 2006 by Johan Reinalda, johan at reinalda dot net

       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.5 or, at
       your option, any	later version of Perl 5	you may	have available.

       If you make useful modification,	kindly consider	emailing then to me
       for inclusion in	a future version of this module.

perl v5.24.1			  2007-VUser::Google::ProvisioningAPI::V1_0(3)

NAME | SYNOPSIS | REQUIREMENTS | DESCRIPTION | CONSTRUCTOR | METHODS | ACCESSING RESULTING DATA | ACCESSING RAW GOOGLE POST AND RESULT DATA | EXPORT | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=VUser::Google::ProvisioningAPI::V1_0&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help