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

FreeBSD Manual Pages

  
 
  

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

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

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

	$google->CreateUser($userName, $givenName, $familyName,	$password, $quotaMB);
	my $user = $google->RetrieveUser($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
       Adding a	user:

	use VUser::Google::ProvisioningAPI;
	my $google = VUser::Google::ProvisioningAPI->new('yourdomain.com',
						 'admin',
						 'your password',
						 '2.0');

	my $entry = $google->CreateUser('joeb',	'Joe', 'Blow', 'joespassword');
	if (defined $entry) {
	  print	$entry->User, "	created\n";
	} else {
	  die "Add failed: ".$google->{result}{reason};
	}

       Updating	a user:

	my $new_entry =	VUser::Google::ProvisioningAPI::V2_0::UserEntry->new();
	$new_entry->Password('heresmynewpassword');
	$new_entry->GivenName('Joseph');
	my $entry = $google->UpdateUser('joeb',	$new_entry);

       Delete a	user:

	my $rc = $google->DeleteUser('joeb');
	if (not	$rc) {
	  die "Can't delete user: ".$google->{result}{reason};
	}

CONSTRUCTOR
       new ($comain, $admin, $adminpasswd)

       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 handed by Google's API engine, the results
       of the action are returned as the content of the	request.

       If the request fails (as	determined by the "HTTP::Request" method
       is_success()), it could mean a couple of	things.	If it's	a failure
       within the Google API, the content will contain an XML encoded error
       message.	All other HTTP errors are still	possible.

   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.)

       Relogin()

	   Performs a login if required. Relogin() will	be called but the API
	   methods and IsAuthenticated(). You should not need to call this
	   directly.

   User	Methods
       These are the acutual API calls.	These calls match up with the client
       library methods described for the .Net and Java libraries.

       CreateUser($userName, $givenName, $familyName, $password, $quota)

	   Creates a user in your Google Apps domain. The first	four arguments
	   are required. The $quota argument is	optional and may not do
	   anything unless your	agreement with Google allows you to change
	   quotas.

	   CreateUser()	returns	a
	   "VUser::Google::ProvisioningAPI::V2_0::UserEntry" object if the
	   request was successful and "undef" otherwise.

       RetrieveUser($userName)

	   Get the passed user from Google. Returns a
	   "VUser::Google::ProvisioningAPI::V2_0::UserEntry" object.

       RetrieveAllUsers()

	   Returns a list of all users in your domain. The entries are
	   "VUser::Google::ProvisioningAPI::V2_0::UserEntry" objects.

       RetrievePageOfUsers($startUser)

	   Google Provisioning API 2.0 supports	returning lists	of users 100
	   at a	time.  $startUser is optional. When used, it will be the list
	   will	start at that user. Otherwise, it will return the first	100
	   users.

	   RetrievePageOfUsers() returns a list	of
	   "VUser::Google::ProvisioningAPI::V2_0::UserEntry" objects.

       UpdateUser($userName, $newUserEntry)

	   $userName is	the mandatory name of the user account.	$newUserEntry
	   is a	"VUser::Google::ProvisioningAPI::V2_0::UserEntry" object with
	   the changes to the account. You only	need to	set the	elements of
	   $newUserEntry that are being	changed. Note: According to the	Google
	   API docs, you should	not set	the password unless you	are actually
	   changing the	password.

       SuspendUser($userName)

	   $userName is	the name of the	user that you want to suspend.

	   Returns a "VUser::Google::ProvisioningAPI::V2_0::UserEntry" object
	   if successful.

       RestoreUser($userName)

	   Unsuspend the user's	account. $userName is required.

	   Returns a "VUser::Google::ProvisioningAPI::V2_0::UserEntry" object
	   if successful.

       DeleteUser($userName)

	   $userName is	the required user name to delete.

	   Returns '1' on success.

       Nickname	methods

       CreateNickname($userName, $nickName)

	   Creates a nickname (or alias) for a user. $userName is the existing
	   user	and $nickName is the user's new	nickname.

	   Returns a "VUser::Google::ProvisioningAPI::V2_0::NicknameEntry"
	   object on success.

       RetrieveNickname($nickName)

	   Returns a "VUser::Google::ProvisioningAPI::V2_0::NicknameEntry" if
	   the $nickName exists.

       RetrieveNicknames($userName)

	   Get all nicknames for $userName.

	   Returns a list of
	   "VUser::Google::ProvisioningAPI::V2_0::NicknameEntry" objects.

       RetrieveAllNicknames()

	   Get all of the nick names for your domain.

	   Returns a list of
	   "VUser::Google::ProvisioningAPI::V2_0::NicknameEntry" objects.

       RetrievePageOfNicknames($startNick)

	   Get 100 of the nick names for your domain. If $startNick is
	   defined, the	list will start	with that nick name, otherwise,	the
	   first 100 nicks will	be returned.

	   Returns a list of
	   "VUser::Google::ProvisioningAPI::V2_0::NicknameEntry" objects.

       DeleteNickname($nickName)

	   Delete $nickName from your domain. Returns 1	if the request
	   succeeds.

       Email list methods

       CreateEmailList($listName)

	   Create an email list	named $listName.

	   Returns a "VUser::Google::ProvisioningAPI::V2_0::EmailListEntry" on
	   success.

       RetrieveEmailLists($recipient)

	   Get a list of all local email lists that $recipient is subscribed
	   to.	$recipient is limited to users at your domain.

	   Returns a list of
	   "VUser::Google::ProvisioningAPI::V2_0::EmailListEntry" objects.

       RetrieveAllEmailLists()

	   Get a list of all email lists for your domain.

	   Returns a list of
	   "VUser::Google::ProvisioningAPI::V2_0::EmailListEntry" objects.

       RetrievePageOfEmailLists($startList)

	   Get a single	page (100 lists) of email lists.

       DeleteEmailList($emailList)

	   Delete $emailList from your domain.

	   Returns 1 on	success.

       AddRecipientToEmailList($recipient, $emailList)

	   Adds	a recipient to a mail list. $recipient is the address you want
	   to add and $emailList is the	list to	add to.

	   Returns a
	   "VUser::Google::ProvisioningAPI::V2_0::EmailListRecipientEntry"
	   object on success.

       RetrieveAllRecipients($emailList)

	   Get a list of the recipients	of the specified email list.

	   Returns a list of
	   "VUser::Google::ProvisioningAPI::V2_0::EmailListRecipientEntry"
	   objects.

       RetrievePageOfRecipients($emailList, $startRecpt)

	   Get a page of recipients for	that given list	("$emailList)"
	   starting with $startRecpt or	the beginning if $startRecpt is	not
	   defined.

	   Returns a list of
	   "VUser::Google::ProvisioningAPI::V2_0::EmailListRecipientEntry"
	   objects.

       RemoveRecipientFromEmailList($recipient,	$emailList)

	   Remove $recipient from the given email list ($emailList).

	   Returns 1 in	success.

ACCESSING RESULTING DATA
       Most API	calls return an	object so that you don't have to screw around
       with the	XML data. The parsed XML (by XML::Simple) is available in
       "$google-"{result}>.

EXPORT
       None by default.

SEE ALSO
       The perldocs for	VUser::Google::ProvisioningAPI::V2_0::UserEntry;
       VUser::Google::ProvisioningAPI::V2_0::NicknameEntry;
       VUser::Google::ProvisioningAPI::V2_0::EmailListEntry; and
       VUser::Google::ProvisioningAPI::V2_0::EmailListRecipientEntry.

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

       http://code.google.com/apis/apps/gdata_provisioning_api_v2.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 Randy Smith, perlstalker at
       vuser dot org

COPYRIGHT AND LICENSE
       Copyright (C) 2006 by Johan Reinalda, johan at reinalda dot net
       Copyright (C) 2007 by Randy Smith, perlstalker at vuser dot org

       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			  2009-VUser::Google::ProvisioningAPI::V2_0(3)

NAME | SYNOPSIS | REQUIREMENTS | DESCRIPTION | CONSTRUCTOR | METHODS | ACCESSING RESULTING 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::V2_0&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help