Google Apps Security and Compliance Services Google Web Services Application Programming Interface Guide, Early Access Version 1.
Google, Inc. 1600 Ampitheatre Parkway Mountain View, CA 94043 www.google.com Part number: EEAPI_R6.19_00 28 May 2009 © Copyright 2009 Postini, Inc. All rights reserved. Google, the Google logo, Google Message Filtering, Google Message Security, Google Message Discovery, Postini, the Postini logo, Postini Perimeter Manager, Postini Threat Identification Network (PTIN), Postini Industry Heuristics, and PREEMPT are trademarks, registered trademarks, or service marks of Google, Inc.
Although their code does not appear in gd 1.8.4, the authors wish to thank David Koblas, David Rowley, and Hutchison Avenue Software Corporation for their prior contributions.
Google Compliance Policies Notice: Google assumes no responsibility in connection with the Compliance Policies lexicon-filtering feature, including any failure to recognize credit card or social security numbers that do not follow an applicable pattern as established in Postini’s systems or any failure to encrypt a credit card or social security number.
Contents Chapter 1: What’s New in This Book 3 What’s New in Google Apps Security and Compliance Google Web Services API (EA v.1.
Chapter 5: Service Management API 35 About the Service Management API 35 Understanding the Service Management API AutomatedBatch Reference Basics 36 36 Chapter 6: User Sync API 39 About the User Sync API 39 Understanding the User Sync API 39 User Sync API Reference 41 User Sync API test Operation 45 User Sync API checkauth Operation 46 User Sync API GetUsers Operation 47 User Sync API AddUsers Operation 52 User Sync API ModifyUsers Operation 57 User Sync API DeleteUsers Operation 65 2 Message Securit
Chapter 1 What’s New in This Book Chapter 1 What’s New in Google Apps Security and Compliance Google Web Services API (EA v.1.5) The Google Web Services API introduces: User Sync API -- Provides bulk user management for your Message Securityservice account. The API is optimized to efficiently retrieve, add, modify, and delete a large number of users.
The Message Securityservice Customer Care does not provide technical support for configuring mail servers or third-party products. In the event of an issue with these products, you should consult with your administrator. Postini accepts no responsibility with third-party products. Please contact Postini Professional Services (professionalservices@postini.com) for consulting services. Please send your comments, feedback, and suggestions to doc_comments@google.com.
Document Description Message Archiving User’s Guide Instructions for retrieving and exporting email messages, IM conversations, and IM file transfers from your corporate message archive. Early Access Program It is important to remember this guide supports the Google Web Services API Early Access Program. Google is not liable for any errors in this manual or any harm to your systems resulting from reliance on this manual. We can not provide support for this document.
Chapter 2 Introduction to Google Web Services API Chapter 2 Welcome to the Google Web Services API The Google Web Services API leverages your account’s organizational hierarchy information with standard web service protocols. This collaboration lets you securely automate everyday administration tasks for hundreds of users. In addition, this service-oriented architecture provides flexible and functional extensions letting you integrate the Google Web Services API into additional business applications.
API Infrastructure -- Common features across the web services • API Infrastructure-- A unique license key identifier required for each of your web service applications. It is used during the authentication of a web service call. This is a required feature. To get your API license key, send mail to the Early Access Program’s support, postinicustomercare@google.com to open a case via email. For technical information, see “API License Key” on page 19.
When your application makes a web service request for data to the Google Web Services API, the server authenticates your request and prepares the resulting data. The server then sends a response, meaning the data is serialized and sent across the Internet as a secure transaction to your application. The data is then deserialized making it available to your web service application.
The Extensible Markup Language (XML) is a markup or tagging language used to describe data. This allows your application’s data to be persistently recreated on both the server-side and the client-side of a web service’s request and response transaction. • SOAP -- Provides a dependable envelope to pass your web service transaction across the Internet. SOAP is a generic messaging framework for XML-based web service messages.
System Information The Google Web Services API, Early Access version uses these protocols and languages: • Web Service Description Language (WSDL) 1.1 • Extensible Markup Language (XML) 1.0 • SOAP 1.1 The web service snippets, found in TThe Batch and Service Management API Reference Guide, were developed using: • Microsoft Visual Studio 2005 C# • NetBeans 5.5, JAX.WS 2.0 • Apache Axis 1.4 (Java), XMLBeans 2.
Examples of systems are: • For System 5, https://api-s5.postini.com/dl/api/automatedbatch.wsdl • For System 6, https://api-s6.postini.com/dl/api/automatedbatch.wsdl • For System 7, https://api-s7.postini.com/dl/api/automatedbatch.wsdl • For System 8, https://api-s8.postini.com/dl/api/automatedbatch.wsdl • For System 9, https://api-s9.postini.com/dl/api/automatedbatch.wsdl • For System 200, https://api-s200.postini.com/dl/api/automatedbatch.wsdl • For System 201, https://api-s201.postini.
These are introductory classes showing how to create a web service and client, modify an attribute, deploy the web service, and how to debug and handle exceptions. Axis and XMLBeans Resources • Apache Axis Web Service project (http://ws.apache.org/axis/) • Axis Web Services Recommended Reading (http://ws.apache.org/axis/java/ reading.html) • XMLBeans home page (http://xmlbeans.apache.org) • XMLBeans resources (http://xmlbeans.apache.org/resources/index.
The development steps are: • 14 Reference the WSDLs -- Connecting to all of the web service WSDLs required for your application is the first step. • For information of WSDL URLs and how to find your system, see “WSDL URL” on page 11. • For a Visual Studio example, see “Getting Started with a C# Example” on page 65. • Test your connectivity -- For an application using the Service Management web service, a round trip connectivity test utility is available.
special attention to organization, user, domain, alias concepts and functionality. For more information, see The Email Security Administration Guide. • • The Service Management API requires experience with the email security service batch commandline interface. For more information, see “Service Management API” chapter in The Batch and Service Management API Reference Guide.
This example uses the WindowsFormsApplicationExample project. . 8. In the Solutions explorer, right select References. A Context menau opens with Add Reference... and Add Service Reference... options. 9. Select Add Service Reference on the Context menu. The Add Service Reference window will be displayed. 10. Enter the path of the WSDL. For more information about your WSDL URLs, see “WSDL URL” on page 11. By expanding the service, all available methods in the web service are listed. 11.
This example uses the AutomatedBatchService as the Web reference. automatedbatch.swdl 12. The web reference is displayed in the solutions explorer along with other .cs files created by the Visual Studio environment.
13. Select the web reference and click Show All Files in the upper left header of this frame. Expand the folder structure below the web reference and select Reference.cs which is the proxy class created for interacting with the web service. The Reference.cs proxy class will be displayed in the left code window. 14. At this point, the web service client code can be written. To call the web service from the windows application, use the Proxy class as you would any other local component.
Chapter 3 API Infrastructure Chapter 3 About the API Infrastructure This chapter presents the common web service infrastructure features used by the web services. API License Key The API license key is a unique identifier used during authentication. The key is a string composed of 48 alpha numeric characters. This key is required for each of your applications using the Service Management and Endpoint Resolver web services, except for the test utility which does not use an API license key.
MalformedKeyException -- This exception is thrown if the key was not constructed properly. For more information for the MalformedKeyException, see “Exceptions” on page 21. NoSuchKeyException -- This exception is thrown if the key is constructed properly but is not valid. For more information for the NoSuchKeyException, see “Exceptions” on page 21. Exception Management Exceptions signal an error condition that has changed the expected flow of your application.
Note: Operation-level exceptions are the most common exceptions. Handle these exceptions when the operation is called, and not at the top of the application. • Mixed levels of exceptions -- Occasionally a condition occurs causing different types of exceptions to be thrown at the same time. The application’s behavior is subject to the most severe exception.
Recommended Solution -- Stop the application. This is an extremely rare exception. If this occurs during the Early Access program, send the error in email to the Early Access Program’s support, postinicustomercare@google.com to open a case via email. InvalidValueException -- The application was sent a value for a well-known field type, and the value was bogus. It was not valid. This is a rare exception for strongly typed languages such as C# and Java.
Endpoint Resolver Exception UnknownEmailException -- Specified email cannot be located in our system. Service Management API’s AutomatedBatch Exception BatchException -- This exception is specific to the batch interface layer of the Service Management API. These are any errors reported by a particular batch command, field, or batch interface condition. Some of these errors are requests failures and some are serious conditions.
Chapter 4 Endpoint Resolver Chapter 4 About the Endpoint Resolver The Endpoint Resolver dynamically returns the location of a web service on a user’s system, allowing API developers to implement cross-cluster applications. In addition, this web service is also useful for validating a user’s domain. To appreciate the Endpoint Resolver’s purpose, it important to understand the data center is organized into several system clusters.
For example, when updating the support contact for msmith@jumboinc.com and jim@hugeISP.com, the Endpoint Resolver is first called to find the right web service for each customer: • For msmith@jumboinc.com, the Endpoint Resolver returns the web service URL on System 8 since this is where the jumboinc.com domain is managed. Your application then calls the Service Management API on System 8 to update your company’s support contact for the msmith@jumboinc.com.
Understanding the Endpoint Resolver Service The Endpoint Resolver web service has one operation, and responds either with an endpoint URL or an exception: • Your application sends a GetServiceEndpoint request which contains your API license key, the email address of your user, and the service your application is using to manage this user. For more information about an API license key, see “API License Key” on page 19.
See Also “AutomatedBatch Reference Basics” on page 36, “About the User Sync API” on page 39. Operation GetServiceEndpoint Request: GetServiceEndpoint Response: Description Performs a lookup using the specified email address. The operation maps the cluster returned into the appropriate endpoint URI. apiKey -- A global unique 48 character string identifying the customer and the client application. For more information, see “API License Key” on page 19.
C# Example This v.1.5 C# example is using the PMP password (pword) for authentication. The snippet example was created using Microsoft Visual Studio 2005. try { //Create an instance of AutomatedBatch Reference AutomatedBatchAPI.AutomatedBatchService wsAddUser = new AutomatedBatchAPI.AutomatedBatchService(); //Create an Instance of the authElement AutomatedBatchAPI.authElem authCredentials = new AutomatedBatchAPI.
//Display the web service output MessageBox.Show("Successfully added new user."); } catch (System.Web.Services.Protocols.SoapException ex) { String realSoapExceptionName = ex.Detail.FirstChild.LocalName; String realSoapExceptionMessage = ex.Detail.FirstChild.InnerText; MessageBox.Show("Unable to add new user - unexpected exception '" + realSoapExceptionName + "' - " + realSoapExceptionMessage); return; } 30 Message Security and Compliance Application Programming Interface Guide RELEASE EA version 1.
Axis Example This v.1.5 Java example is using Apache Axis 1.4. This example shows how to create a communication endpoint before creating the port. Once the dynamically created endpoint is assigned to the port, it can not be changed for that endpoint instance. try { // Load and instantiate an instance of our endpoint resolver. EndpointResolverAPI.EndpointResolverServiceLocator endpointResolverLocator = new EndpointResolverAPI.EndpointResolverServiceLocator(); EndpointResolverAPI.
//Get the child records. qpOrgArgs.setChildorgs("Yes"); // Make our call and retrieve a list of orgRecords. AutomatedBatchAPI.OrgRecord[] orgs = automatedBatchPort.listorgs(authCredentials,"ALL",qpOrgArgs); // Display information for each org. for (int orgCount = 0; orgCount < orgs.length; orgCount++) { String orgName = orgs[orgCount].getOrgname();System.out.println("Found org " + orgName); } } catch ( EndpointResolverAPI.UnknownEmailException ex ) { System.err.
JAX WS Example This v.1.5 Java example was created using JAX.WS 2.0. try { // Load and instantiate an instance of our endpoint resolver. EndpointResolverAPI.EndpointResolverService endpointResolverService = new EndpointResolverAPI.EndpointResolverService(); EndpointResolverAPI.EndpointResolverPort endpointResolverPort = endpointResolverService.getEndpointResolverPort(); // Create an instance of our Automated Batch auth element AutomatedBatchAPI.AuthElem authCredentials = new AutomatedBatchAPI.
automatedBatchPort = service.getAutomatedBatchPort(); //Create an Instance of the extra argument structure for orgs AutomatedBatchAPI.ListorgsqueryParams qpOrgArgs = new AutomatedBatchAPI.ListorgsqueryParams(); //Get the child records. qpOrgArgs.setChildorgs("Yes"); // Make our call and retrieve a list of orgRecords. List orgs = automatedBatchPort.listorgs(authCredentials,"ALL",qpOrgArgs); // Display information for each org. for (int orgCount = 0; orgCount < orgs.
Chapter 5 Service Management API Chapter 5 About the Service Management API The Service Management API expands the automated capabilities of a key set of standard batch commands while maintaining fine grain control over organizations, users, and domains. In addition, the Service Management commands issue reports, perform transaction authentication, and test the connectivity between the client application and the server.
Understanding the Service Management API The Service Management API service is called AutomatedBatch. The service has 25 operations ranging from managing organizations, domains, users, reports, authorizations, and aliases to running a connection test: • When your application makes an operation request, the AutomatedBatch service authenticates the request, validates the API license key, runs the command, and prepares the resulting data.
WSDL • WSDL: https://api-s.postini.com/dl/api/ automatedbatch.wsdl • PSTN_URI: http://postini.com/PSTN/SOAPAPI/v2/automatedbatch • PSTN_PROXY: https://api-s.postini.com/api2/ automatedbatch Note: For product-level code, use the Endpoint Resolver service to locate a user’s AutomatedBatch web service. See “About the Endpoint Resolver” on page 25.
Exceptions Service Management API AutomatedBatch Exceptions • Batch Exception -- This exception is specific to the batch interface layer of the Service Management API. These are any errors reported by a particular batch command, field, or batch interface condition. Some of these errors are requests failures and some are serious conditions. Recommended Solution -- If this exception is thrown during the development cycle, stop the application.
Chapter 6 User Sync API Chapter 6 About the User Sync API The User Sync API provides bulk user management for your Message Securityservice account. The API is optimized to efficiently retrieve, add, modify, and delete a large number of users. In comparison, the Service Management API, while having similar functionality, primarily provides detailed user management functions for a single user record. For more information about the Service Management API, see “About the Service Management API” on page 35.
Compare user information -- After your application has determined which users you need to synchronize, use the GetUsers operation to retrieve those user’s records from the Message Securityservice. Compare this information with your user data: • GetUsers -- Requests a list of user records with specific information. This operation always returns status, and, if successful, it returns the list of users and your requested information.
User Sync API Reference Service Name User Sync API User Sync API 41
Summary The User Sync API provides the ability to retrieve, add, modify, and delete an unlimited number of users. The User Sync API operations are: • User Sync API test Operation -- The test operation runs a connection level test between the User Sync API web service and the web service client.
This chapter has several code examples showing how to use the User Sync API service. It is important to remember these are simple examples. Google is not liable for any errors in this manual or any harm to your systems resulting from reliance on this manual. But we would appreciate your feedback. Please send your comments, feedback, and suggestions to doc_comments@google.com. Authorization • AuthElem -- The AuthElem struct sets the authorization credentials for each request.
Exceptions When handling exceptions, use the exception name (example: AdminBlockException). Some exceptions also have text strings. Any exception string should not be used to identify an exception. These strings are subject to change across releases. test Operation Exception StatusException -- This exception is used to trigger an exception without a real problem in the system. This exception is used by the User Sync API’s test utility.
Enumerated Types for AddStatus, ModifyStatus, and DeleteStatus With an operation’s response, a status is given for each component’s request. These enumerated string values are used by the AddUsers, ModifyUsers, DeleteUsers operations. The enumerated strings are: • Success -- The operation was successful. • AlreadyExists -- The element already exists. This could be a user or alias address, an attribute’s name value, or a sender list address.
Description The test operation determines if connections to the web service and the web service client are blocked. In addition, it tests exception handling. It is a simple round trip test and does not require an API license key. • true -- ‘should_work’. The connection is successful. If it fails, the development tool will throw either an error, or warning depending upon the type of failure.
Response If successful, no data is returned except for an empty SOAP response (void). Otherwise see “Exceptions” on page 44. Exceptions User Sync API API Infrastructure Exceptions -- See “Exceptions” on page 44, and for exception handling recommendations, see “Exception Management” on page 20. C# Example This v. 1.5 C# example is using the PMP password (pword) for authentication. The example was developed using Microsoft Visual Studio 2005. ... UserSyncAPI.UserSyncService wsCheckAuth = new UserSyncAPI.
Description Returns a list of users, with their specified information, within the list of organizations matched by the criteria requested by the your application. For more information on the GetUsers responses, see “Responses” on page 50. The GetUsers request contains: • AuthElem -- Sets the authorization credentials for a web service request. For specific information, see “Authorization” on page 43. This is required.
• Control -- Determines the amount of detailed information returned for each user. This is required. Type: GetUsersControl. A GetUsersControl element has these sub-elements: • ReturnAliases -- If true, the response returns all aliases for each user. This is required. Type: boolean ReturnAttributes -- If true, the response returns all User API Attributes for each user. This is required. For more information about attributes, see “Summary” on page 42.
Responses Returns GetUsersResponse composed of an unlimited list of User elements. User Element Type: UserRecord If a requested user does not exist, the response to this requested user is an empty UserRecord. Responses are returned in the same order as the requests. A UserRecord element is composed of: • Address -- Primary user address and is required. See AddressList below.
Exceptions GetUsers Exception InvalidCriteriaException - The search criteria could not possibly return any results, or conflicting search criteria where specified. Recommended Solution -- If this exception is thrown during the development cycle, stop the application. To determine the specific error, either: • Confirm your application is not calling more than one organization matching criteria at the same time, such as using InOrgHierarchy and InAccountHierarchy.
User Sync API AddUsers Operation Operation AddUsers Request: AddUsers (AuthElem, NewUserRecord) Response: AddUsersResponse holding UserAddStatus for each new user 52 Message Security and Compliance Application Programming Interface Guide RELEASE EA version 1.
Description The AddUsers operation adds one or more users with specific information for each user held in a NewUserRecord. For more information on the AddUsers detailed response status for each user, see “Responses” on page 54. An AddUser request contains: • AuthElem -- This sets the authorization credentials for each request. See “Authorization” on page 43. This is required. Type: struct • NewUsers -- An unlimited list of records with each record holding information for a new user. This is required.
• BlockedSenderAddresses -- An unlimited list of blocked sender addresses to add to the user. This is optional. Type: AddressList. An AddressList has an unlimited number of blocked sender Address elements. Responses For each NewUserRecord request, the service responds with a AddUsersResponse which holds a UserAddStatus struct for each new user. The number of UserAddStatus structs contained in an AddUserResponse is unlimited.
• Status -- The success or failure value representing the status of adding the alias. This is required. Type: AddStatus. For more information about the AddStatus enumerated types, see “Enumerated Types for AddStatus, ModifyStatus, and DeleteStatus” on page 45. If the UserAddStatus’s Status element is not successful, the alias is not added and this element is empty. • • Message -- The User Sync API may return human readable messages to help when debugging your application.
In the response, each blocked sender address has information in an ‘item’ element. A blocked sender address item holds these sub-elements: • Address -- One of the blocked sender addresses requested in the NewUserRecord BlockedSenderAddresses field. This is required. Type: string • Status -- The success or failure value representing the status of the entry addition. This is required. Type: AddStatus.
JAX WS 2.0 Example JAX-WS 2.0 Example // AuthElem AuthElem authElem = new AuthElem(); authElem.setApiKey("*your api key here*"); authElem.setEmail("*your admin user email here*"); authElem.setPword("*your admin password here"); List apiNewUserList = new ArrayList(0); NewUserRecord apiNewUser = new NewUserRecord(); apiNewUser.setAddress("test@example.com"); apiNewUser.setOrg("Postini Org"); apiNewUser.
Description The ModifyUsers operation modifies a block of users and their associated information, returning detailed status and information for each user. Failures are reported as part of the response data structure, rather than as exceptions. Input is a list of UserRecordPatches called Modifications. The ModifyUser request contains: • AuthElem -- This required struct sets the authorization credentials for each request. See “Authorization” on page 43. This is required.
• DeleteApprovedSenderAddresses -- An unlimited list of approved sender addresses to be deleted. This is optional. Type: AddressList. This AddressList has an unlimited number of approved sender Address elements. • AddBlockedSenderAddresses -- An unlimited list of blocked sender addresses to be added. This is optional. Type: AddressList. This AddressList has an unlimited number of blocked sender Address elements. • DeleteBlockedSenderAddresses -- An unlimited list of blocked addresses to be deleted.
Responses For each ModifyUsers request, the service responds with a ModifyUsersResponse which holds an unlimited list of UserModifyStatus elements, one for each user. UserModifyStatus for each user has these struct elements: • Address -- The primary user address that is or is not modified. This is required. Type: string • UserAvailable -- If false, requested modifications are not attempted, and no other status is given. This is true if: • The primary user address exists and is not suspended.
• NewAddressMessage -- The User Sync API may return human readable messages to help when debugging your application. These messages do not happen in every case and, since they are subject to change, your application should not be dependent upon or use these strings. • AddAliasStatus -- The status for each alias requested to be added for a user. This is an unlimited list. Type: UserModifyStatusAddAliasStatus. UserModifyStatusAddAliasStatus has a struct element named ‘item’.
• AddApprovedSenderAddressStatus -- An unlimited list of structures to represent the status for requests to modify approve sender addresses. Type: UserModifyStatusAddApprovedSenderAddressStatus. UserModifyStatusAddApprovedSenderAddressStatus has a struct element named ‘item’. An ‘item’ is of type UserModifyStatusAddApprovedSenderAddressStatusItem. In the response, each approved sender address has status information in the ‘item’ sub-element: • Address -- Sender address to be approved. This is required.
• AddBlockedSenderAddressStatus -- An unlimited list of structures to represent the status for requests to block sender addresses. Type: UserModifyStatusAddBlockedSenderAddressStatus. UserModifyStatusAddBlockedSenderAddressStatus has a struct element named ‘item’. An ‘item’ is of type UserModifyStatusAddBlockedSenderAddressStatusItem. In the response, each blocked sender address has status information in the ‘item’ sub-element: • Address -- Sender address to be blocked. This is required.
• DeleteAttributeStatus -- An unlimited list of structures to represent the status for requests to delete User API attributes. Type: UserModifyStatusDeleteAttributeStatus. UserModifyStatusDeleteAttributeStatus has a struct element named ‘item’. An ‘item’ is of type UserModifyStatusDeleteAttributeStatusItem. In the response, each attribute has status information in the ‘item’ subelement: • Name -- Name of the attribute. This is required.
ModifyUsers v.15, JAX WS 2.0 Example This v.1.5 JAX-WS 2.0 example is using the PMP password (pword) for authentication. // AuthElem AuthElem authElem = new AuthElem(); authElem.setApiKey("*your api key here*"); authElem.setEmail("foo@jumboinc.com"); authElem.setPword("password"); List apiPatchList = new ArrayList(1); UserRecordPatch apiPatch = new UserRecordPatch(); apiPatch.setAddress("bar@jumboinc.com"); AddressList addAliasList = new AddressList(); addAliasList.
Responses Response is a DeleteUsersResponse which holds a list of UserDeleteStatus records, one for each address specified as input. This is an unlimited list. UserDeleteStatus struct elements are: • Address -- User address specified for deletion. This is required. Type: string • Status -- A DeleteStatus value representing the status of the requested delete. This is required. Type: DeleteStatus.
Index A AddUsers operation (User Sync) 52 API Guide Audience 7 API Infrastructure API license key 19 Exception management 20 API license key 19 exceptions 19 AutomatedBatch Reference Basics 36 service details 36 C C# setup example, getting started 15 checkauth operation Service Management API 37 User Sync API 46 checkauth operation (User Sync) 46 Code examples Endpoint Resolver, Axis 31 Endpoint Resolver, C# example 29 Endpoint Resolver, JAX WS 33 User Sync AddUsers, JAX WS example 57 User Sync DeleteUsers
P Protocols HTTPS 8 IDNA (International Domain Names) 10 SOAP 8 WSDL 8 XML 8 S Service Management API AutomatedBatch 36 BatchException 23 operations list 37 SOAP 8 Support resources 5 System information 11 T test operation Service Management API 37 User Sync API 45 test operation (User Sync) 45 U User Sync API InvalidCriteriaException 23 UserSync AddUsers operation 52 API User Attributes 40 checkauth operation 46 DeleteUsers operation 65 GetUsers operation 47 ModifyUsers operation 57 Overview 39 Reference 4
