Note: The Provisioning API is only available to Google Apps Premier Edition and Google Apps Education Edition customers. To enable the API, log in to your admin account, and click the Users and groups tab. Then click the Settings subtab, select the checkbox to enable the Provisioning API and save your changes. (You will need to complete the steps for setting up Google Apps before you can log in to your admin account.)
The following subsections explain how to use the Google Apps Java client library to access Provisioning API functionality. Each subsection explains the Java client library methods for specific API functionality. These methods can be found in the sample.appsforyourdomain.AppsForYourDomainClient class.
|
Setup Methods for User Accounts
Creating a User Account
Retrieving a User Account Retrieving all Users in a Domain Retrieving List of 100 Users Updating a User Account Suspending a User Account Restoring a User Account Deleting a User Account Methods for Nicknames |
Methods for Groups New!
Creating a Group
Retrieving a Group Updating a Group Retrieving all Groups for a Member Retrieving all Groups in a Domain Deleting a Group Methods for Group Members New! Methods for Group Owners New!
Adding a Owner to a Group Methods for Handling Errors |
Before using the Provisioning API, you will need an administrator username and password for your Google Apps domain. You will also need to enable the Provisioning API for your Google Apps domain.
Follow the Getting Started article to install the necessary software for compiling and running Java programs which use Google Data APIs (including the Provisioning API).
Before making API calls with the Java client library, you must construct a new AppsForYourDomainClient object. In the constructor, set your authentication information as follows:
import sample.appsforyourdomain.AppsForYourDomainClient; ... AppsForYourDomainClient client = new AppsForYourDomainClient(adminEmail, adminPassword, domain);
Here, replace adminEmail with your domain administrator email, password with your domain administrator password, and domain with the domain to which you are authenticating.
To create a user account using the Java client library, call one of the following methods. These methods all return a UserEntry XML response, which the Java client library converts to a UserEntry object.
client.createUser(String username, String givenName, String familyName, String password) client.createUser(String username, String givenName, String familyName, String password, Integer quotaLimitInMb) client.createUser(String username, String givenName, String familyName, String password, String passwordHashFunction) client.createUser(String username, String givenName, String familyName, String password, String passwordHashFunction, Integer quotaLimitInMb)
Note: Not all partners have the ability to adjust the disk space quota allocated to users. This method takes the following arguments:
To retrieve information about a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.
client.retrieveUser(String username)
The only argument that you need to pass to the method is the username associated with the account that you wish to retrieve.
To retrieve all of the users in a domain, you can call the following method in the Java client library. This method returns a UserFeed XML response, which the Java client library converts to a UserFeed object.
client.retrieveAllUsers()
This method allows you to control the size of your result set when you request all of the users in your domain. As discussed in the Results Pagination section, the Java client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.
To retrieve a list of 100 users in your domain, you can call the following method in the Java client library. This method returns a UserFeed XML response, which the Java client library converts to a UserFeed object.
client.retrievePageOfUsers(String startUsername)
The only argument that you need to pass to the method is the first username that should appear in your result set. Usernames are ordered case-insensitively by ASCII value.
To update a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.
client.updateUser(String username, UserEntry userEntry)
This method takes two arguments:
The common use case for this method will be to retrieve a user account, modify the UserEntry object that contains information about that account, and then submit the modified object to the updateUser method.
To rename the user, update the UserEntry object with the new username and then invoke client.updateUser(String username, UserEntry userEntry) passing the old username as the first parameter. Before renaming a user, it is recommended that you logout the user from all browser sessions and services. For instance, you can get the user on your support desk telephone line during the rename process to ensure they have logged out. The process of renaming can take up to 10 minutes to propagate across all services.
Note: Google Talk will lose all remembered chat invitations after renaming. The user must request permission to chat with friends again. Also, when a user is renamed, the old username is retained as a nickname to ensure continuous mail delivery in the case of email forwarding settings and will not be available as a new username. To remove the nickname, you should call client.deleteUser(String username) after renaming.
To suspend a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.
client.suspendUser(String username)
The only argument that you need to pass to the method is the name of the user whose account you wish to suspend.
To restore a user account using the Java client library, call the following method. This method returns a UserEntry XML response, which the Java client library converts to a UserEntry object.
client.restoreUser(String username)
The only argument that you need to pass to the method is the name of the user whose account you wish to restore.
To delete a user account using the Java client library, call the following method:
client.deleteUser(String username)
The only argument that you need to pass to the method is the name of the user whose account you wish to delete.
To create a nickname using the Java client library, call the following method. This method returns a NicknameEntry XML response, which the Java client library converts to a NicknameEntry object.
client.createNickname(String username, String nickname)
This method takes two arguments:
To retrieve information about a nickname using the Java client library, call the following method. This method returns a NicknameEntry XML response, which the Java client library converts to a NicknameEntry object.
client.retrieveNickname(String nickname)
The only argument that you need to pass to the method is the nickname you wish to retrieve.
To retrieve all of the nicknames created for a user account, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.
client.retrieveNicknames(String username)
The only argument that you need to pass to the method is the username for which you wish to retrieve nicknames.
To retrieve all of the nicknames in a domain, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.
client.retrieveAllNicknames()
This method allows you to control the size of your result set when you request all of the nicknames in your domain. As discussed in the Results Pagination section, the Java client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.
To retrieve a list of 100 nicknames in your domain, you can call the following method in the Java client library. This method returns a NicknameFeed XML response, which the Java client library converts to a NicknameFeed object.
client.retrievePageOfNicknames(String startNickname)
The only argument that you need to pass to the method is the first nickname that should appear in your result set. Nicknames are ordered case-insensitively by ASCII value.
To delete a nickname using the Java client library, call the following method:
client.deleteNickname(String nickname)
The only argument that you need to pass to the method is the name of the nickname that you wish to delete.
The following methods are used to create, retrieve, and update groups. Note that all Group methods are called using the following:
AppsGroupsService groupsService = client.getGroupService(); and then, groupService.anygroupsmethod().
To create a group using the Java client library, call the following method. This method returns a GroupFeed XML response, which the Java client library converts to an Group object.
groupsService.createGroup(String groupId, String groupName, String groupDescription, String emailPermission)
This method takes four arguments:
Note: A newly created group does not have any subscribers. You must call the addMemberToGroup method to add members to a group.
This method, in turn, issues an HTTP POST request to the following URL:
https://apps-apis.google.com/a/feeds/group/2.0/(domain)
To retrieve information about a group using the Java client library, call the following method. This method returns a GroupFeed XML response, which the Java client library converts to a GroupFeed object.
groupsService.retrieveGroup(String groupId)
The only argument that you need to pass to the method is the name of the group that you wish to retrieve.
This method, in turn, issues an HTTP GET request to the following URL:
https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)
To update a group, you can call the following method in the Java client library.
This method returns a GroupFeed XML response, which the Java client library converts to a GroupFeed object.
groupsService.updateGroup(String groupId, String groupName, String description, String emailPermission)
This method takes four arguments:
To retrieve all of the groups that a user is a recipient of, you can call the following method in the Java client library.
This method returns a GroupFeed XML response, which the Java client library converts to a GroupFeed object.
groupsService.retrieveGroups(String memberId, Boolean directOnly)
This method takes two arguments:
This method, in turn, issues an HTTP GET request to the following URL:
https://apps-apis.google.com/a/feeds/group/2.0/(domain)?member=(memberId)[&[directOnly=(true|false)]]
To retrieve all of the groups in a domain, you can call the following method in the Java client library. This method returns a GroupFeed XML response, which the Java client library converts to a GroupFeed object.
groupsService.retrieveAllGroups()
This method, in turn, issues an HTTP GET request to the following URL:
https://apps-apis.google.com/a/feeds/group/2.0/(domain)[?[start=(startKey)]]
To delete a group using the Java client library, call the following method. We assume service is an authenticated AppsService object.
groupsService.deleteGroup(String groupId)
The only argument that you need to pass to the method is the name of the group that you wish to delete.
Note: When you delete a group, the Provisioning API will automatically delete all recipients from the group as well.
This method, in turn, issues an HTTP DELETE request to the following URL:https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)
To add a member (email address) to a group using the Java client library, call the following method. This method returns a MemberEntry XML response, which the Java client library converts to a MemberEntry object.
groupsService.addMemberToGroup(String groupId, String memberName)
This method takes two arguments:
This method, in turn, issues an HTTP POST request to the following URL:
https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/member
Note: If you add a group as a member of another group, there may be a delay of up to 10 minutes before the child group's members appear as members of the parent group.
To retrieve a list of all of the subscribers to a group, you can call the following method in the Java client library. This method returns a MemberFeed XML response, which the Java client library converts to a MemberFeed object.
groupsService.retrieveAllMembers(String groupId)
The only argument that you need to pass to the method is the name of the group for which you wish to retrieve a member list.
This method, in turn, issues an HTTP GET request to the following URL:https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/member
To delete a member (email address) from a group using the Java client library, call the following method.
groupsService.deleteMemberFromGroup(String groupId, String memberName)
This method takes two arguments:
https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/member/(memberId)
To assign an owner to a group using the Java client library, call the following method.
groupsService.addOwnerToGroup(String groupId, String ownerName)
This method takes two arguments:
https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/owner
To query a group to find out who owns the group using the Java client library, call the following method.
client.retrieveGroupOwners(String groupId)
The only argument that you need to pass to the method is the name of the group for which you want to retrieve an owner list.
This method, in turn, issues an HTTP GET request to the following URL:https://apps-apis.google.com/a/feeds/group/2.0/(domain)/(groupId)/owner
To query a group to find out if a user or group owns a group using the Java client library, call the following method.
groupsService.isOwner(String groupId, String email)
To delete an owner from a group using the Java client library, call the following method.
groupsService.removeOwnerFromGroup(String email, String groupId)
This method takes two arguments:
The Java client library will throw an AppsForYourDomainException when it receives an error response from the Provisioning API. Other types of exceptions may also be thrown for other types of errors. To process or log an AppsForYourDomainException, we recommend that you call the getErrorCode method on that object to determine the type of error that the Provisioning API returned. The sample code below demonstrates how you would catch an AppsForYourDomainException in the Provisioning API:
try {
// Some API actions
} catch (AppsForYourDomainException e) {
if (e.getErrorCode() == AppsForYourDomainErrorCode.EntityDoesNotExist ) {
// Do some post-error processing or logging.
}
}
A complete list of error codes is provided in Appendix D - GData Error Codes.