Google 数据 Java 客户端库使用入门

Stephanie Liu，Google 数据 API 团队
2007 年 9 月
  1. 简介
  2. 安装依赖项
    1. 在 Windows 上
    2. 在 Mac OS X 上
    3. 在 Linux 设备上
  3. 安装 Google Data 客户端库
  4. 运行示例
  5. 构建自己的应用
  6. 总结
  7. 附录：设置环境变量

简介

开始利用陌生的 API 进行开发从来都不容易，因此本文提供了有关如何下载并安装 Google Data API（“GData”）Java 客户端库的分步说明。接下来，我将获取所有依赖项，并设置您需要的环境变量。您很快就能混搭不同的 GData 服务！

使用 Eclipse？

参阅在代码编码中：使用 Eclipse 与 Google 数据 API 一文。

安装依赖项

GData Java 客户端库具有以下外部依赖项。下面几部分将介绍如何在您喜爱的操作系统（或您在使用时卡住的操作系统）上安装这些依赖项。

  • JDK（Java 开发套件）版本 1.5+
  • Apache Ant 1.7 及更高版本
  • Sun 的 JavaMail API 1.4+ 中的 mail.jar
  • Sun 的 JavaBeansActivationFramework 中的 activate.jar。只有媒体列表 API（包括 Document List Data API、Picasa Web Album API 和 YouTube Data API）需要执行此操作。
  • Sun 的 servlet API 2.3+ 中的 servlet.jar 仅在执行“sample.authsub”或“sample.gbase.recipe”软件包中的代码示例时才需要。

只有少数示例才需要使用几个 .jar 依赖项，但为了避免出现构建错误，最好只获取所有内容。选择所需操作系统，然后继续：Windows、Mac OS X 或 Linux。

安装 Google Data 客户端库

  1. 访问 http://code.google.com/p/VAST-java-client/downloads/list
  2. 下载最新版本的客户端库 (gdata-src.java-1.x.x.java.zip) 和示例 (gdata-samples.java-1.x.x.java.zip)。
  3. 将客户端库源代码提取到计算机上。
  4. 转到 gdata/java/build-src/build.properties 并打开文件。
  5. 修改外部依赖项，使其指向本地机器上 .jar 文件的位置。

    6. 注意：在 Windows 上，请务必转义反斜杠。例如，

    servlet.jar=C:\\Program Files\\Apache Software Foundation\\Tomcat 6.0\\lib\\servlet-api.jar

运行示例

所有可用样本都位于 gdata-samples.java-1.x.x.java.zip 归档中的 gdata/java/sample 下。gdata/java/build-samples/build.properties 文件包含库中包含的样本的所有输入值。将 sample.credentials.username 和 sample.credentials.password 设置为有效的用户名和密码。我们可以使用 Ant 来构建和执行示例。

打开命令提示符，切换到 gdata/java 目录，然后输入以下代码，测试是否已正确安装所有内容：

ant -f build-samples.xml sample.calendar.run

您可能会收到一些信息或警告消息，但只需在末尾找到 BUILD SUCCESSFUL 消息即可！如果您没有看到成功消息，请参阅“问题排查”部分。

输入以下内容，试用更具互动性的示例：

ant -f build-samples.xml sample.spreadsheet.guidemo.run

如需了解如何运行特定示例，请转到 gdata/java/build-samples 并查看该示例的 build 文件。找到 samples run 部分。

问题排查

如果您的 build 失败，并显示如下错误消息：

BUILD FAILED
Target 'core.sample.core.util.build' does not exist in this project. It is used from target 'sample.calendar.build'.

Total time: 0 seconds

或者有关项目中缺少必要文件的类似错误消息，您可能运行的是旧版 Ant。输入 ant -version 以确保您使用的是 1.7 或更高版本。请参阅上文的依赖项说明，获取最新版本的 Ant。

构建自己的应用

下一个问题是如何构建您自己的应用。我将使用 Google 日历服务执行等效的“Hello, World!”计划，以展示基本功能。如需了解详情，请参阅 Java 客户端库的开发者指南以及各个产品的开发者指南。

创建一个名为 CalendarTest.java 的文件。首先添加以下 import 语句。

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.acl.*;
import com.google.gdata.data.calendar.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;

import java.net.*;
import java.io.*;

import sample.util.*;

以下是整个程序（不含任何异常处理）。

public class CalendarTest {

    public static void main(String[] args) {
        CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0");
        myService.setUserCredentials("root@gmail.com", "pa$$word");

        URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");
        CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);

        System.out.println("Your calendars:");
        System.out.println();

        for (int i = 0; i < resultFeed.getEntries().size(); i++) {
          CalendarEntry entry = resultFeed.getEntries().get(i);
          System.out.println("\t" + entry.getTitle().getPlainText());
        }

    }
}

This little program will request all the calendars you own and display all the titles. It's a little longer than the canonical "Hello, World!" example, but it's very simple once we break it down. The first couple of lines creates a service object and sets the user credentials.

CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0");
myService.setUserCredentials("root@gmail.com", "pa$$word");

然后，设置资源的网址。在这种情况下，您可以在此处向经过身份验证的用户请求所有日历的列表。

URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");

下面这行代码会对网址执行实际的 GET 命令，并将生成的 Feed 放入一个整洁的对象中。

CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);

下面的 for 循环将遍历每个条目并输出标题。请注意，标题会存储为 TextConstruct，因此需要执行额外的函数调用以获取纯文本。

for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    CalendarEntry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
}

这是非常基本的操作 - 我们来介绍一些其他的常用操作。以下代码段展示了如何创建对象并插入该对象。在我们的示例中，将会是新的日历活动条目。

URL postURL = new URL("http://www.google.com/calendar/feeds/root@gmail.com/private/full");
CalendarEventEntry myEvent = new CalendarEventEntry();

//Set the title and description
myEvent.setTitle(new PlainTextConstruct("Pi Day Party"));
myEvent.setContent(new PlainTextConstruct("I am throwing a Pi Day Party!"));

//Create DateTime events and create a When object to hold them, then add
//the When event to the event
DateTime startTime = DateTime.parseDateTime("2007-03-14T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2007-03-14T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEvent.addTime(eventTimes);

// POST the request and receive the response:
CalendarEventEntry insertedEntry = myService.insert(postURL, myEvent);

另一种常见操作是构建查询。

//Create a new query object and set the parameters
Query myQuery = new Query(feedURL);
myQuery.setFullTextQuery("Pi");

//Send the request with the built query URL
CalendarEventFeed myResultsFeed = myService.query(myQuery, CalendarEventFeed.class);

//Take the first match and print the title
if (myResultsFeed.getEntries().size() > 0) {
    CalendarEventEntry firstMatchEntry = new CalendarEventEntry();
    myResultsFeed.getEntries().get(0);
    System.out.println(firstMatchEntry.getTitle().getPlainText());
}

在调试时，另一项有用的操作是转储原始 XML。您可以使用以下实用的库在库中执行此操作。确保已导入 samples.util.*。然后，转储该 Feed 或条目。

CommonUtils.dump(resultFeed, System.out);

如需了解更深入的调试工具，请参阅调试 Google 数据 API 客户端：探索程序内的流量一文，了解如何在客户端库内启用日志记录功能。

这应该会让您了解使用客户端库构建应用的体验。如需了解详情，请参阅“总结”部分，查看每个 Google Data API 的可用开发者指南列表。

总结

希望您现在能够使用 GData Java 客户端库构建和运行应用！我没有介绍过您可以使用的任何热门 IDE，但您可以了解一下 Eclipse 或 NetBeans 等热门工具。以下是一些可能对您有用的其他链接：

如果您对将 Java 客户端库用于任何 API 有任何疑问，请在相应的 API 论坛中发帖告知我们。