NAME¶
VUser::Google::Provisioning::V2_0 - Support for version 2.0 of the Google
Provisioning API
SYNOPSIS¶
use VUser::Google::ApiProtocol::V2_0;
use VUser::Google::Provisioning::V2_0;
my $google = VUser::Google::ApiProtocol::V2_0->new(
domain => 'example.com',
admin => 'admin_user',
password => 'secret',
);
my $api = VUser::Google::Provisioning::V2_0->new(
google => $google,
);
## Create user
my $new_user = $api->CreateUser(
userName => 'fflintstone',
givenName => 'Fred',
familyName => 'Flintstone',
password => 'I<3Wilma',
);
## Retrieve a user
my $user = $api->RetrieveUser('fflintstone');
## Retrieve all userr
my @users = $api->RetrieveAllUsers();
## Update a user
my $updated = $api->UpdateUser(
userName => 'fflintstone',
givenName => 'Fredrock',
familyName => 'FlintStone',
suspended => 1,
quota => 2048,
);
## Change password
$updated = $api->ChangePassword('fflintstone', 'new-pass');
$updated = $api->ChangePassword(
'fflintstone',
'51eea05d46317fadd5cad6787a8f562be90b4446',
'SHA-1',
);
$updated = $api->ChangePassword(
'fflintstone',
'd27117a019717502efe307d110f5eb3d',
'MD5',
);
## Delete a user
my $rc = $api->DeleteUser('fflintstone');
DESCRIPTION¶
VUser::Google::Provisioning::V2_0 provides support for managing users using
version 2.0 of the Google Provisioning API.
In order to use the Google Provisioning API, you must turn on API support from
the Google Apps for Your Domain control panel. The user that is used to create
the VUser::Google::ApiProtocol object must have administrative privileges on
the domain.
Note: It's a good idea to log into the web control panel at least once as
the API user in order to accept the the terms of service and admin terms. If
you don't, you'll get intermittent authentication errors when trying to use
the API.
METHODS¶
Unless stated otherwise, these methods will
die() if there is an API
error.
CreateUser
CreateUser() takes a hash of create options and returns a
VUser::Google::Provisioning::UserEntry object if the account was created.
CreateUser() will
die() if there is an error.
The keys of the hash are:
- userName (required)
- The user name of the account to create
- givenName (required)
- The user's given name
- familyName (required)
- The user's family name
- password (required)
- The user's password. If hashFunctionName is also set, this is the
base16-encoded hash of the password. Otherwise, this is the user's
plaintext password.
Google required that passwords be, at least, six characters.
- hashFunctionName
- hashFunctionName must be SHA-1 or MD5. If this is set,
password is the base16-encoded password hash.
- quota
- The user's quota in MB.
Not all domains will be allowed to set users' quotas. If that's the case,
creation will still succeed but the quota will be set to the default for
your domain.
- changePasswordAtNextLogin
- If set to a true value, e.g. 1, the user will be required to change their
password the next time they login in. This is the default. You may turn
this off by setting changePasswordAtNextLogin to 0.
- admin
- If set to a true value, e.g. 1, the user will be granted administrative
privileges. A false value, e.g. 0, admin rights will be revoked. By
default, users will not be granted admin rights.
RetrieveUser
my $user = $api->RetrieveUser('fflintstone');
Retrieves a specified user by the user name. RetieveUser will return a
VUser::Google::Provisioning::UserEntry if the user exists and undef if it
doesn't.
RetrieveUsers
my @users = ();
my %results = $api->RetrieveUsers();
@users = @{ $results{entries} };
while ($results{next}) {
%results = $api->RetrieveUsers($results{next});
push @users, @{ $results{entries} };
}
Fetches one page of users starting at a given user name. Currently, a page is
defined as 100 users. This is useful if you plan on paginating the results
yourself or if you have a very large number of users.
The returned result is a hash with the following keys:
- entries
- A list reference containing the user accounts. Each entry is a
VUser::Google::Provisioning::UserEntry object.
- next
- The user name for the start of the next page. This will be undefined
("undef") if there are no more pages.
See
RetrieveAllUsers() if you want to fetch all of the accounts at once.
RetrievePageOfUsers
This is a synonym for
RetrieveUsers()
RetrieveAllUsers
my @users = $api->RetrieveAllUsers();
Get a list of all the users for the domain. The entries in the list are
VUser::Google::Provisioning::UserEntry objects.
UpdateUser
my $updated = $api->UpdateUser(
userName => 'fflintstone',
givenName => 'Fred',
# ... other options
);
Updates an account. UpdateUser takes the same options as
CreateUser() but
only userName is required.
UpdateUser() cannot be used to rename an account. See
RenameUser().
RenameUser
my $user_user = $api->RenameUser($oldname, $newname);
Rename an account. The first parameter is the old user name; the second is the
new user name.
RenameUser() will die if the old name does not exist.
DeleteUser
my $rc = $api->DeleteUser('fflintstone');
Deletes a given user. Returns true if the delete succeded and dies if there was
an error.
ChangePassword
$updated = $api->ChangePassword('fflintstone', 'new-pass');
$updated = $api->ChangePassword(
'fflintstone',
'51eea05d46317fadd5cad6787a8f562be90b4446',
'SHA-1',
);
$updated = $api->ChangePassword(
'fflintstone',
'd27117a019717502efe307d110f5eb3d',
'MD5',
);
Change a users password.
ChangePassword takes the user name, password and, optionally, a hash function
name. If the hash function name is set, the password, is the base16-encoded
password, otherwise it is the clear text password.
Accepted values for the has function name are
MD5 and
SHA-1.
There is no difference between using this and using UpdateUser to change the
user's password.
SEE ALSO¶
- •
- VUser::Google::Provisioning
- •
- VUser::Google::ApiProtocol::V2_0
- •
- VUser::Google::EmailSettings::V2_0
- •
- http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_developers_protocol.html
item *
http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html
BUGS¶
Bugs may be reported at
http://code.google.com/p/vuser/issues/list.
AUTHOR¶
Randy Smith <perlstalker@vuser.org>
COPYRIGHT AND LICENSE¶
Copyright (C) 2009 Randall Smith
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
Street, Fifth Floor, Boston, MA 02110-1301, USA.