bf4 / downloadgooglecontacts.rb Goto Github PK

   #[1]Ruby Script to Download Google Account Contacts [2]1. Overview

Ruby Script to Download Google Account Contacts

Chad Albers

   August 8, 2008
     __________________________________________________________________

1. Overview

   downloadGoogleContacts.rb is a fairly robust [3]Ruby script that uses
   Google's [4]Contacts Data API to download your Contacts from either a
   Gmail account or a "hosted" Google account. I wrote the script to
   download and backup all my Contacts on a regular basis using cron. The
   script uses Google's [5]ClientLogin interface to access the account. It
   then downloads the contacts as an Atom XML feed.

   The script "works for me" and should be considered an early beta
   version.

2. Script Options and Parameters

   The script requires three mandatory options:
     * -e or --email EMAIL_ADDRESS
       The e-mail address of the Google account, including both the
       username and either Google's domain (@gmail.com), or the hosted
       account's domain (@neomantic.com).
     * -p or --password PASSWORD
       The password of the Google account or hosted Google account.
     * -t or --tokenfile FULL_PATH_TO_FILE
       The file name and path to the file where the script has or will
       save the ClientLogin token.
     * -o or --output FULL_PATH_TO_FILE
       The file name and path to the file where the script has or will
       save the Atom Feed of the Contacts.

   The script accepts one optional option that modifies the output:
     * -m --maximum MAXIMUM_NUMBER_OF_CONTACTS
       The maximum number of contacts to retrieve. (Without supplying this
       parameter, the number of Contacts returned is relatively small.)

   The script also accepts two more optional options:
     * -v or --verbose
       Provides messages on the script's progress.
     * -h or --help
       Provides a message describing these options.

3. Usage Example

   To download all your Contacts to a file called "contacts.xml" using a
   key stored in a file called "token_file," run the following command:

   $> ruby downloadGoogleContacts.rb -e [email protected] -p
   sekritpassword -m 10000 -t /home/my_home/token_file -o
   /home/my_home/contacts.xml

4. Script Requirements

   The script does not depend on any third-party Ruby code outside of
   Ruby's Core and Standard Libraries. It has been tested successfully on
   Ruby 1.8.7 (on Debian GNU/Linux and FreeBSD).

5. Limitations

     * Ruby: The script is not compatible with Ruby 1.9.
     * OpenSSL: The script makes no attempt to verify the certificate used
       to encrypt the transmission between sending login information and
       Google's website. Ruby's https class can perform this verification,
       but the script intentionally disables it - using
       OpenSSL::SSL::VERIFY_NONE. To perform the verification, the script
       would need to include the certificate from Googles' CA. This
       feature can be enabled by following the instructions posted on
       [6]this web page.
     * CAPTCHA: The script can handle a number of user, system, and
       network errors. It can also handle errors noticed by Google.
       However, it cannot handle the case when Google notifies the user
       that they must re-verify their login information by viewing a
       CAPTCHA image.

6. License

   The source code is released under the [7]GNU General Public License
   Version 2 (GPL). The full text of this license can be found in a file
   called "gpl-2.0" released with the source code.

   This documentation is released under the [8]GNU Free Documentation
   License Version 1.2.

   Copyright (c) Chad Albers. Permission is granted to copy, distribute
   and/or modify this document under the terms of the GNU Free
   Documentation License, Version 1.2 or any later version published by
   the Free Software Foundation; with no Invariant Sections, no
   Front-Cover Texts, and no Back-Cover Texts. A copy of the license is
   included in the section entitled "GNU Free Documentation License".

   The full text of this license is found in the file called "fdl.txt"
   released with the source code.

7. Download Location

   The source code and documentation can be downloaded from [9]here. The
   GPG signature of this file can be found [10]here. Updates to the script
   will be posted to [11]http://www.neomantic.com

8. Contact

   Please direct questions or requests for more information to
   <[12][email protected]>. Corrections, suggestions, bug reports, and
   patches are welcome as well.

References

   1. file://localhost/home/calbers/works/src/git-managed/downloadGoogleContacts/README.html#id2428169
   2. file://localhost/home/calbers/works/src/git-managed/downloadGoogleContacts/README.html#id2537532
   3. http://www.ruby-lang.org/
   4. http://code.google.com/apis/contacts/
   5. http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html
   6. http://redcorundum.blogspot.com/2008/03/ssl-certificates-and-nethttps.html
   7. http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
   8. http://www.gnu.org/licenses/fdl.html
   9. http://www.neomantic.com/downloads/downloadGoogleContacts-0.1.tgz
  10. http://www.neomantic.com/downloads/downloadGoogleContacts-0.1.tgz.sign
  11. http://www.neomantic.com/
  12. mailto:[email protected]