Google Base Data API

Getting Started

Developer's Guide

Reference Guide

Related Links

Java Client Library - CustomerTool

CustomerTool is a command-line tool that lets you perform the following actions: insert, update, delete, display an item, execute a batch command, and query. It goes against the customer-specific items feed, not the public snippets feed, so the results of a query may differ from the results of QueryExample because CustomerTool is only searching for matching items in your own data.

Note that CustomerTool handles 'raw' Atom XML, unlike QueryExample where the code uses the GData client library to parse the XML and access its content. The tool takes a raw XML stream as input, validates it and sends it to the server. When it's done, it outputs a raw XML stream to standard output.

All of the source files are available to you in the java/src/com/google/api/gbase/examples/cmdline directory of the distribution.

The remainder of this page explains how to use the CustomerTool application. If you're not interested in using it and just want to look at the source code, feel free to skip the rest of this page.

To run CustomerTool, you will need to add gbase-data-api-dev/java/lib/gdata-base-cmdline.jar to your classpath. Alternately, you can run CustomerTool from the gbase-data-api-dev/java/lib directory.

Using CustomerTool
1. Command-line parameters
  1. Standard command-line options
Tutorial: Using CustomerTool to insert a new data item

Using CustomerTool

Command-line parameters

Whenever you access the items feed, you must be authenticated and provide a valid developer key for "Installed applications". When using CustomerTool, this is done by passing the parameters --user, --password and --key.

java ...CustomerTool insert|update|delete|batch|get|query [--url base_url] [--auth auth_url] --user username --password password <command-specific options...>

Standard command-line options

[--url base_url] [--auth auth_url] --user username --password password

Parameter	Meaning	Notes
`key`	Google API Key	You can obtain an API key here.
`base_url`	Google Base server URL	The default is http://www.google.com/base/, but you can specify another server.
`auth_url`	Authentication server URL	The default is https://www.google.com/accounts, but you can specify another server.
`user`	Customer's Google e-mail address.	Required. CustomerTool uses the customer items feed.
`password`	Customer's Google password.	Required. CustomerTool uses the customer items feed.
`output_file`	The file where the XML is to be written.	You must use standard output.

Tutorial: Using CustomerTool to insert a new data item

To insert an item, follow these steps:

Create an XML file using attribute tags to describe the item.
Run CustomerTool with the file as input.

First, create a small XML file containing the data item you wish to insert. For example, acme-laptop.xml contains this:

<?xml version='1.0'?>
<entry xmlns='http://www.w3.org/2005/Atom'
      xmlns:g='http://base.google.com/ns/1.0'
   <category scheme="http://base.google.com/categories/itemtypes" term="products"/>
   <title type='text'>Acme 2000 series laptop</title>

   <content type='xhtml'>
         <div xmlns='http://www.w3.org/1999/xhtml'>The fastest Acme Laptop yet...</div>
         </content>
   <link rel='alternate' type='text/html' href='http://www.provider-host.com/123456789'/>
   <g:label>Computer</g:label>

   <g:label>Laptop</g:label>
   <g:label>fastest laptop</g:label>
   <g:item_type>products</g:item_type>
</entry>

To insert this item, execute CustomerTool with these parameters:

username: your Google account username
password: your Google account password
base-url: defaults to http://www.google.com/base . You can use the default.
auth-url: defaults to https://www.google.com . You can use the default.
dry_run: Optional. Specifies that you want to test this operation without actually submitting it.

CustomerTool insert --user <username>  --password <password> [--url <base-url>] [--auth <auth-url>] <input-file>

For example, you can enter this command:

java -cp lib/gdata-base-cmdline.jar com.google.api.gbase.examples.cmdline.CustomerTool insert --user janedoe@google.com --password xyz < acme-laptop.xml

This results in the response:

<?xml version='1.0'?>
<entry xmlns='http://www.w3.org/2005/Atom'
      xmlns:g='http://base.google.com/ns/1.0'>
      <id>http://www.google.com/base/feeds/items/11292306253607009080</id>

      <published>2006-03-27T23:20:41.428Z</published>
      <updated>2006-03-27T23:20:41.428Z</updated>
      <category scheme="http://base.google.com/categories/itemtypes" term="products"/>   
      <title>Acme 2000 series laptop </title>

      <content xmlns='http://www.w3.org/1999/xhtml'type='xhtml'>
          <div xmlns='http://www.w3.org/1999/xhtml'>The fastest Acme Laptop yet...</div></content>
      <link rel='alternate' type="text/html"
          href="http://provider-website.com/item-info-page.html"/></link>

      <link rel="self" type="application/atom+xml"
          href="http://www.google.com/base/feeds/items/11292306253607009080"/></link>
      <link rel="edit" type="application/atom+xml"

          href="http://www.google.com/base/feeds/items/11292306253607009080"/></link><g:item_type>products</g:item_type>
      <g:label>Computer</g:label>
      <g:label>Laptop</g:label>

      <g:label>fastest laptop</g:label>
</entry>

This data item is inserted into Google Base with the customer-specific feed ( /feeds/items) and is available for viewing through Google Base at http://www.google.com/base/dashboard.

Querying customer data

You can search for items that you own using the Customer Feed

To search for items in the customer items feed, run the following command from the gbase-data-api-dev/java/lib directory.

java ...CustomerTool [query] [standard_options] [<your-query>]

You can use the standard Google Base query parameters.

Sample query

Here's how it would look as a full command line.

java -cp gdata-base-cmdline.jar com.google.api.gbase.examples.cmdline.CustomerTool query --user janedoe@google.com 
	--password xyzxyz --key 837738399  "digital camera"

If you want to see all your items, even those that are not searchable yet, omit the query and run:

java -cp gdata-base-cmdline.jar com.google.api.gbase.examples.cmdline.CustomerTool query --user janedoe@google.com 
	--password xyzxyz --key 837738399

Displaying an item

You can display a single item if you know that item's item ID. As with updates and deletes, if you don't know the ID, you need to issue a query or insert and then use the information you get from that. The response is a feed containing the item.

To display an entry identified by its ID, run the following command from the gbase-data-api-dev/java/lib directory.

java ...CustomerTool get [standard_options] item_id

Parameter	Meaning	Notes
`item_id`	The ID of the item to edit.	This is the item's full URL. For example, `http://www.google.com/base/feeds/items/11292306253607009080`

Sample display

This example displays the item with the URL 11292306253607001000:

java -cp gdata-base-cmdline.jar com.google.api.gbase.examples.cmdline.CustomerTool get --user janedoe@google.com 
	--password xyzxyz --key 837738399  http://www.google.com/base/feeds/items/11292306253607001000

Inserting a new item

To insert a new data item, go to the gbase-data-api-dev/java/lib directory and run the following command:

java ...CustomerTool insert [standard_options] < input_file

Parameter	Meaning	Notes
`input_file`	The file to read the entry from, in Atom format.	You must use standard input.

Sample insert

CustomerTool uses a command line structured like this:

java -cp gdata-base-cmdline.jar com.google.api.gbase.examples.cmdline.CustomerTool insert --user janedoe@google.com 
     --password xyzxyz --key 837738399 < acme-laptop.xml

The response returns as an XML feed, complete with the customer and item IDs. Here's the result:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
     xmlns:g='http://base.google.com/ns/1.0'> 
 <id>http://www.google.com/base/feeds/items/3623814801431172907</id> 
 <published>2006-06-09T19:34:29.038Z</published> 
 <updated>2006-06-09T19:34:29.038Z</updated> 
 <category scheme='http://base.google.com/categories/itemtypes' term='products'></category>

 <title type='text'>Acme 2000 series laptop</title> 
 <content xmlns='http://www.w3.org/1999/xhtml' type='xhtml'> 
 <div xmlns='http://www.w3.org/1999/xhtml'>The fastest Acme Laptop yet...</div> 
 </content>  
 <link rel='alternate' type='text/html'
    href='http://provider-website.com/item-info-page.html'></link> 
 <link rel='self' type='application/atom+xml'
      href='http://www.google.com/base/feeds/items/3623814801431172907'></link>

 <link rel='edit' type='application/atom+xml'
      href='http://www.google.com/base/feeds/items/3623814801431172907'></link> 
 <author>
    <name>Jane Doe</name>
    <email>jd@provider-host.com</email>

 </author>
 <g:item_type type='text'>products</g:item_type>
 <g:label>Computer</g:label>   
 <g:label>Laptop</g:label>   
 <g:label>fastest laptop</g:label>   

</entry>

Updating an existing item

If an item already exists, you can update the data by changing one or more values in the XML input file and performing an update operation. An update uses the HTTP PUT method. The response is a feed containing the new item.

To identify the correct item, you need to provide the item's complete URL. That is, you need to provide the base URL and the item ID. If you don't know them, you can query for the item and then use the information in the <id> tag:

 <id>http://www.google.com/base/feeds/items/11292306253607009080</id>

This URL uniquely identifies this piece of data so that you can accurately update the item:

the Google Base data server's URL: http://www.google.com/base/
the item ID:11292306253607009080

To update an existing entry, run the following command from the gbase-data-api-dev/java/lib directory. Note that the baseURL parameter must include the entire item ID:

java ...CustomerTool update [standard_options] item_id < input_file

Parameter	Meaning	Notes
`input_file`	The file to read the entry from, in Atom format.	You must use standard input.

Sample update

For example, use a URL like this:

java com.google.api.gbase.examples.cmdline.CustomerTool update --user janedoe@google.com --password xyzxyz --key 837738399
	http://www.google.com/base/feeds/items/11292306253607009080 <  updated-item.xml

Deleting an item

If an item already exists, you can delete the item. To identify the correct item, you need to provide the item's complete URL. That is, you need to provide the base URL and the item ID. The response is an empty feed indicating that the item is no longer available.

If you don't know them, you can query for the item and then use the information in the <id> tag:

<id>http://www.google.com/base/feeds/items/11292306253607009080</id>

This URL uniquely identifies this piece of data so that you can accurately delete the item:

the Google Base data server's URL: http://www.google.com/base/
the item ID:11292306253607009080

To delete an entry identified by its ID, run the following command from the gbase-data-api-dev/java/lib directory:

java ...CustomerTool delete [standard_options] item_id

Parameter	Meaning	Notes
`item_id`	The ID of the item to edit.	This is the item's full URL. For example, `http://www.google.com/base/feeds/items/11292306253607009080`

Sample delete

This example deletes the item with the URL 11292306253607001000:

java -cp gdata-base-cmdline.jar com.google.api.gbase.examples.cmdline.CustomerTool delete --user janedoe@google.com 
	--password xyzxyz --key 837738399 http://www.google.com/base/feeds/items/11292306253607001000

Issuing a batch request

You can execute multiple operations in a single HTTP request by posting a feed to the Google Base Batch URL: http://www.google.com/base/feeds/items/batch.

A feed posted to this URL should contain a list of entries to insert, update and/or delete, as described in Batch Processing with Google Data APIs.

Issuing a batch command

Run the following command from the gbase-data-api-dev/java/lib directory to execute a batch command.

java ...CustomerTool batch [standard_options] <input_file >output_file

Parameter	Meaning	Notes
`input_file`	The file to read the entry from, in Atom format.	You must use standard input.
`output_file`	The file where the XML response file is to be written.	You must use standard output.

All the information CustomerTool needs to execute these operations must be present in the input_file feed. Refer to the GData documentation on batch operations for a description of the format of the input_file and the output_file.

Sample batch command