Google Apps Platform

Google Documents List API v1 Developer's Guide: Protocol

Important: Versions 1 and 2 of the Google Documents List API have been officially deprecated as of April 20, 2012. They will continue to work as per our deprecation policy, but we encourage you to move to the Google Drive API.

In addition to providing some background on the capabilities of the Documents List Data API, this guide provides examples for interacting with the API using the .NET Google Data Client Library. For help setting up the client library, see the Getting Started with the .NET Client Library. If you're interested in understanding more about the underlying protocol used by the .NET client library to interact with the Documents List Data API, please see the protocol guide.

Contents

Audience

This document is intended for developers who want to write client applications using the Google Data .NET client library that can interact with Google Documents.

Getting started

Google Documents uses Google Accounts for authentication, so if you have a Google account you are all set. Otherwise, you can create a new account.

For help setting up the client library, see the Getting Started Guide. To use the .NET client library, you'll need the .NET 1.1 runtime, and you should also be current on all patches. After downloading the client library, you'll find the DLLs you need to get started in the lib/Release subdirectory of the distribution.

To compile the examples in this document into your own code, you'll need the following using statements:

using Google.GData.Documents;
using Google.GData.Client;
using Google.GData.Extensions;

The DocumentsService class represents a client connection (with authentication) to the Google Docs web service. The general procedure for sending a query to a service using the client library consists of the following steps:

  1. Obtain or construct the appropriate URL.
  2. If you're sending data to a service (for example, if you're inserting a new entry), then transform the raw data into objects using the client library classes. (This step doesn't apply if you are merely retrieving data or uploading from a file.)
  3. Create a new DocumentsService instance, setting your application's name (in the form companyName-applicationName-versionID).
  4. Set the appropriate credentials.
  5. Call a method to send the request and receive any results.

Authenticating to the Documents service

The .NET client library can be used to work with either public or private feeds. The Documents List Data API provides access to private feeds only, which require authentication with the documents servers. This can be done via ClientLogin username/password authentication or AuthSub proxy authentication. Currently, there are no public feeds in the Documents List API.

Please see the Google Data APIs authentication documentation for more information on AuthSub and ClientLogin.

ClientLogin for "installed" applications

To use ClientLogin (also called "Authentication for Installed Applications"), invoke the setUserCredentials method of DocumentsService, specifying the ID and password of the user on whose behalf your client is sending the query. For example:

DocumentsService myService = new DocumentsService("exampleCo-exampleApp-1");
myService.setUserCredentials("jo@gmail.com", "mypassword");

Once the credentials have been set, they will be used to authenticate each request made using this service object.

For more information about Google's authentication systems, see the Google Account Authentication documentation.

AuthSub for web applications

The AuthSub login protocol allows your web-based application to have a user authenticate through Google's servers. To familiarize yourself with how this works in .NET, see the code samples in Using AuthSub with the Google Data API Client Libraries.

Having reviewed that documentation, you can now make a few substitutions and use it to access the Documents List API:

authSubUrl = AuthSubUtil.getRequestUrl("http://www.example.com/Hello.asp", "https://docs.google.com/feeds/", false, true);

Here we request a token with the proper scope to retrieve and create private documents.

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("writely", "exampleCo-exampleApp-1");
authFactory.Token = (String) Session["token"];
DocumentsService service = new DocumentsService(authFactory.ApplicationName);
service.RequestFactory = authFactory;

Note that the service name for the Documents List API is "writely".

Retrieving a list of documents

You can get a feed containing a list of the currently authenticated user's documents by sending an authenticated GET request to the following URL:

https://docs.google.com/feeds/documents/private/full

The result is a feed that lists all of that user's documents. Each entry in the feed represents a document (spreadsheet, word processor document, or presentation) associated with the user. This feed is accessible only using an authentication token.

You can print out a list of the user's documents as follows:

DocumentsListQuery query = new DocumentsListQuery();
DocumentsFeed feed = service.Query(query);

foreach (DocumentEntry entry in feed.Entries)
{
    Console.WriteLine(entry.Title.Text);
}

The resulting DocumentsFeed object feed represents a response from the server. Among other things, this feed contains a list of DocumentEntry objects (feed.Entries), each of which represents a single document. DocumentEntry encapsulates the information about a document, as shown in the protocol guide.

Uploading documents

Files may be uploaded using the UploadDocument method of the service object. In the examples below, the complete file name with its path, along with an optional name of the file to be used in Google Docs is provided to the UploadDocument function. If null is passed as the file name, then the original file name on the disk will be used in Google Docs.

Uploading a word processor document

This example uploads a document, assuming the file to upload is named test.txt and located on the root of the C drive. The new document is given the title passed in as the second parameter. The newEntry variable is a DocumentEntry object containing information about the document that was uploaded, including a direct link to the document.

DocumentEntry newEntry = service.UploadDocument("C:\\test.txt", "New Document Title.txt");
Console.WriteLine("Now accessible at: " + newEntry.AlternateUri.ToString());

Uploading a spreadsheet

This example uploads a document, assuming the file to upload is named test.xls and located on the root of the C drive. The new document is given the title passed in as the second parameter. The newEntry variable is a DocumentEntry object containing information about the document that was uploaded, including a direct link to the document.

DocumentEntry newEntry = service.UploadDocument("C:\\test.xls", "New Document Title");
Console.WriteLine("Now accessible at: " + newEntry.AlternateUri.ToString());

Uploading a presentation

This example uploads a document, assuming the file to upload is named test.ppt and located on the root of the C drive. The new document is given the title passed in as the second parameter. The newEntry variable is a DocumentEntry object containing information about the document that was uploaded, including a direct link to the document.

DocumentEntry newEntry = service.UploadDocument("C:\\test.ppt", "New Document Title");
Console.WriteLine("Now accessible at: " + newEntry.AlternateUri.ToString());

Trashing a document

To put a document in the trash, perform a Delete on the Atom entry representing the document. To trash the new document from the upload examples above, you would execute the following.

newEntry.Delete();

Searching the documents feed

You can search the Document List using some of the standard Google Data API query parameters. Categories are used to restrict the type of document (word processor document, spreadsheet, or presentation) returned. Categories can also be used to select if a document is starred or in a particular folder. The full-text query string is used to search the content of all the documents. More detailed information on parameters specific to the Documents List can be found in the Documents List Data API Reference Guide.

In the .NET client library, a DocumentsListQuery object can be used to construct queries for the Documents List feed.

Retrieving all word processor documents

A list of only word processor documents can be retrieved by using the document category as follows:

TextDocumentQuery query = new TextDocumentQuery();
DocumentsFeed feed = service.Query(query);

foreach (DocumentEntry entry in feed.Entries)
{
    Console.WriteLine(entry.Title.Text);
}

Retrieving all spreadsheets

A list of only spreadsheets can be retrieved by using the spreadsheet category as follows:

SpreadsheetQuery query = new SpreadsheetQuery();
DocumentsFeed feed = service.Query(query);

foreach (DocumentEntry entry in feed.Entries)
{
    Console.WriteLine(entry.Title.Text);
}

Retrieving all starred presentations

A list of only starred presentations can be retrieved by using the presentation and starred categories as follows:

PresentationsQuery query = new PresentationsQuery();
query.Starred = true;
DocumentsFeed feed = service.Query(query);

foreach (DocumentEntry entry in feed.Entries)
{
    Console.WriteLine(entry.Title.Text);
}

Note that this can work for other document types as well, as all of the Query objects (including DocumentsListQuery) have the Starred property that can be set.

Retrieving a document by an exact title match

It is possible to retrieve documents by matching on their title instead of their entire contents. To do this, set the Title property of the DocumentsListQuery object. To match a title exactly, set the TitleExact property to indicate this is the full, explicit title (including capitalization) of the document you want returned. Of course, there could be multiple documents with the same name, so a feed is returned.

DocumentsListQuery query = new DocumentsListQuery();
query.Title = "Test";
query.TitleExact = true;
DocumentsFeed feed = service.Query(query);

foreach (DocumentEntry entry in feed.Entries)
{
    Console.WriteLine(entry.Title.Text);
}

This sample prints out only documents that have exactly the title "Test".

Retrieving all documents in a named folder

In most cases, a category query which includes the folder name will find the documents in that folder. However, you can also explicitly request documents in a named folder by using a schema qualified query. The function below lets you retrieve all documents in a specified folder belonging to a user with the specified email address:

public DocumentsFeed RetrieveDocsInFolder(DocumentsService service, string folder, string email)
{
  AtomCategory folderCategory = new AtomCategory(folder,
    new AtomUri("http://schemas.google.com/docs/2007/folders/" + email));
  QueryCategory folderQueryCategory = new QueryCategory(folderCategory);
  DocumentsListQuery query = new DocumentsListQuery();
  query.Categories.Add(folderQueryCategory);

  return service.Query(query);
}

Note: There is a problem with the System.Uri class provided by Microsoft. This means the System.Net.HttpWebRequest object will unescape the forward slash characters in the schema causing the service.Query method to fail. This is a known issue and will be corrected soon.

This style of query is useful when a folder name conflicts with a category that has a different meaning, such as "starred". For example, to query for all the documents in the "starred" folder belonging to user "jo@gmail.com", you could use the function as follows:

DocumentsFeed feed = RetrieveDocsInFolder(service, "starred", "jo@gmail.com");

The important distinction here is if you had simply appended the category of "starred" you would get back a list of all starred documents, not the documents in the folder named "starred".

Performing a text query

You can search the contents of documents by using the Query property of a DocumentsListQuery object.

DocumentsListQuery query = new DocumentsListQuery();
query.Query = "test";

This searches the entire contents of every document for the string "test" and returns all documents where this string is found. This is different than searching just the title of every document, which can be done as described in the section Retrieving a document by an exact title match.

Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.