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 Python client library to access Provisioning API functionality. Each subsection explains the Python client library methods for specific API functionality.
|
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 Python programs which use Google Data APIs (including the Provisioning API).
Before making API calls with the Python client library, you must construct a new AppsService object. In the constructor, set your authentication information and then invoke ProgrammaticLogin() to authenticate yourself as follows:
import gdata.apps.service ... service = gdata.apps.service.AppsService(email=email, domain=domain, password=password)
service.ProgrammaticLogin()
Here, replace domain with the domain to which you are authenticating, email with your domain administrator email address, and password with your domain administrator password.
For groups management, you need to construct a more specific GroupsService object as follows:
import gdata.apps.groups.service ... service = gdata.apps.groups.service.GroupsService(email=email, domain=domain, password=password)
service.ProgrammaticLogin()
To create a user account using the Python client library, call one of the following methods. These methods all return a UserEntry XML response, which the Python client library converts to a UserEntry object.
service.CreateUser(user_name, family_name, given_name, password, suspended='false', quota_limit=DEFAULT_QUOTA_LIMIT, password_hash_function=None)
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 Python client library, call the following method. This method returns a UserEntry XML response, which the Python client library converts to a UserEntry object.
service.RetrieveUser(user_name)
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 Python client library. This method returns a UserFeed XML response, which the Python client library converts to a UserFeed object.
service.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 Python 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 Python client library. This method returns a UserFeed XML response, which the Python client library converts to a UserFeed object.
service.RetrievePageOfUsers(start_username=None)
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 Python client library, call the following method. This method returns a UserEntry XML response, which the Python client library converts to a UserEntry object.
service.UpdateUser(user_name, user_entry)
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 service.UpdateUser(user_name, user_entry) passing the existing 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 service.DeleteNickname(nickname) after renaming.
To suspend a user account using the Python client library, call the following method. This method returns a UserEntry XML response, which the Python client library converts to a UserEntry object.
service.SuspendUser(user_name)
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 Python client library, call the following method. This method returns a UserEntry XML response, which the Python client library converts to a UserEntry object.
service.RestoreUser(user_name)
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 Python client library, call the following method:
service.DeleteUser(user_name)
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 Python client library, call the following method. This method returns a NicknameEntry XML response, which the Python client library converts to a NicknameEntry object.
service.CreateNickname(user_name, nickname)
This method takes two arguments:
To retrieve information about a nickname using the Python client library, call the following method. This method returns a NicknameEntry XML response, which the Python client library converts to a NicknameEntry object.
service.RetrieveNickname(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 Python client library. This method returns a NicknameFeed XML response, which the Python client library converts to a NicknameFeed object.
service.RetrieveNicknames(user_name)
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 Python client library. This method returns a NicknameFeed XML response, which the Python client library converts to a NicknameFeed object.
service.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 Python 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 Python client library. This method returns a NicknameFeed XML response, which the Python client library converts to a NicknameFeed object.
service.RetrievePageOfNicknames(start_nickname=None)
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 Python client library, call the following method:
service.DeleteNickname(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.
To create a group using the Python client library, call the following method. This method returns a GroupFeed XML response, which the Python client library converts to an Group object.
groupsService.CreateGroup(group_id, group_name, description, email_permission)
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 Python client library, call the following method. This method returns a GroupFeed XML response, which the Python client library converts to a GroupFeed object.
groupsService.RetrieveGroup(group_id)
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 Python client library.
This method returns a GroupFeed XML response, which the Python client library converts to a GroupFeed object.
groupsService.UpdateGroup(group_id, group_name, description, email_permission)
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 Python client library.
This method returns a GroupFeed XML response, which the Python client library converts to a GroupFeed object.
groupsService.RetrieveGroups(member_id, direct_only)
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 Python client library. This method returns a GroupFeed XML response, which the Python 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 Python client library, call the following method. We assume service is an authenticated AppsService object.
groupsService.DeleteGroup(group_id)
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 Python client library, call the following method. This method returns a MemberEntry XML response, which the Python client library converts to a MemberEntry object.
groupsService.AddMemberToGroup(member_id, group_id)
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 Python client library. This method returns a MemberFeed XML response, which the Python client library converts to a MemberFeed object.
groupsService.RetrieveAllMembers(group_id)
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 Python client library, call the following method.
groupsService.RemoveMemberFromGroup(member_id, group_id)
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 Python client library, call the following method.
groupsService.AddOwnerToGroup(owner_email, group_id)
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 Python client library, call the following method.
groupsService.RetrieveAllOwners(group_id)
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 Python client library, call the following method.
groupsService.IsOwner(owner_email, group_id)
To delete an owner from a group using the Python client library, call the following method.
groupsService.RemoveOwnerFromGroup(owner_email, group_id)
This method takes two arguments:
The Python 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 e.error_code 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 """
except gdata.apps.service.AppsForYourDomainException , e:
print e # or process the exception in some other way
A complete list of error codes is provided in Appendix D - GData Error Codes.