Contacts API
Contents |
Audience
This document is intended for Apex Developers who want to write Force.com Apps that can interact with Google's contact lists.
This document assumes that you understand the general ideas behind the Google Data APIs protocol.
For additional Google Contacts Data API reference information, see the Google Contacts Data API Reference Guide.
Getting started
Set up your Force.com Development environment.
The Force.com platform is the most scalable, secure and popular on-demand platform in the world today. You can develop and instantaneously deploy applications without any infrastructure - 100% on-demand
Install the latest version of the Force.com IDE
The Force.com IDE allows developers a full-featured, Eclipse-based coding environment, with capabilities like code completion, version control,collaborative development, and project sharing.
Create a Google Account
Google Contacts are associated with Google Accounts, so a Google Account will be required in order to proceed. To view your contacts without using the Contacts Data API, you can log in to Gmail and click the Contacts link.
Check out the source code
Check out the Force.com Toolkit for Google Data APIs from the Google repository.
Apex Code Examples
The following examples show how to send Google Contacts Data API requests from Apex Code.
Authenticating
ContactService object
Create the Apex object to handle the connection to Google Data Contacts API, this object is then updated to hold the token that is previously authorized to perform API transactions. This object (service ) is used in each of the following code samples.
ContactService service = new ContactService(); service.setAuthSubToken(tmpAuthToken);
Creating contacts
To insert a contact, you first build a Force.com Contact record, through a constructor or by querying the force.com system, then you can insert this into Google Contacts.
Contact newContact = new Contact( firstname='B', lastname='Spears', description='Sings for money', email='go@for.broke' ); GoogleData feed = service.getFeed( ContactService.defaultFeed ); service.insertContact( feed, newContact );
Retrieving contacts
Retrieving all contacts
To retrieve the Google user's contacts, call the getFeed method:
service.setAuthSubToken(tmpAuthToken); GoogleData feed = service.getFeed( ContactService.defaultFeed );
Retrieving contacts using query parameters
The Contacts Data API lets you request a set of contacts that match specified criteria, such as requesting contacts updated after a given date.
The Contacts Data API supports query parameters described in the Google Contacts Data API Reference Guide (see also: Google Data APIs Reference Guide).
Hint: To track incremental changes to a contact list, do the following: When you send a request for a feed, keep track of the value of the feed's <updated> element. Then you can later retrieve only the contacts that have changed since the previous request by setting the query parameter updated-min to that <updated> value, and setting showdeleted to true.
Note: By default, the entries in a feed are not ordered.
Retrieving a single contact
The link used to fetch a single contact must itself be fetched from the API service, however you can store this to allow for random access to this record later.
To retrieve a specific contact, use Apex code as follows:
// to get a single contact you must have stored the self // link for that contact GoogleData oneCon = service.getFeed( 'http://www.google.com/m8/feeds/contacts/sforcedemos%40gmail.com/full/7656a03108ee72bc'); oneCon.dump();
Retrieving a photo for a contact
The following code loops over all contacts until it finds one with a photo, then it fetches that photo into a variable.
GoogleData feed = service.getFeed( ContactService.defaultFeed );
for( xmldom.element e: feed.entries) {
string photoUrl = GoogleData.getRelLink( e,
'http://schemas.google.com/contacts/2008/rel#photo');
if ( photoUrl != null ) {
system.debug( GoogleData.getTitle(e) + 'has a photo ');
string photo = service.getPhotoBody(photoUrl );
system.debug(photo); // binary data for photo
return;
}
}
The server returns bytes of the photo.
Updating contacts
To update an existing contact, first you retrieve the entry you want to update, then you modify it, and then use service.updatecontact to send your changes back to Google:
GoogleData brits = service.getContactsByTitle( 'Spears' );
for (xmldom.element con : brits.entries) {
con.dumpAll();
con.getElementByTagName('title').nodeValue = 'New Spears';
con.getElementByTagName('content').nodeValue = 'Writes Songs';
service.updatecontact( con);
return;
}
Note that the contact's name is stored in the title element.
Deleting contacts
Find contacts matching the title of "Spears", then delete the first one found
GoogleData brits = service.getContactsByTitle( 'Spears' ); service.removeContact( brits.entries[0] );