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。

在 Windows 上

适用于 Windows 操作系统的说明。

安装 Java

Sun 以 JDK（Java 开发套件）的形式提供了 Java 开发软件包。JRE（Java 运行时环境）以及编写、编译、测试和调试 Java 应用所需的所有其他内容都包含在其中。如果您已安装 Java，请直接跳到安装 Ant。

注意：您需要拥有管理员权限才能安装 JDK。

1. 访问 http://java.sun.com/javase/downloads/index.jsp
2. 点击最新更新旁边的“下载”。
3. 阅读并接受本许可协议。
4. 下载一个 Windows 安装文件。
5. 运行安装程序。
6. 修改 Path 环境变量，以便轻松运行 JDK 可执行文件（例如 javac）。要添加的路径类似于 C:\jdk\bin\。请参阅附录，了解如何在 Windows 中修改 Path 变量。

如果您在安装 JDK 时遇到任何问题，请参阅 Sun 网站上的详细安装说明。

安装 Ant

Apache Ant 是适用于 Java 的构建工具，与 make 类似（但更好）。您将使用它来构建库和执行示例。如果您已安装 Ant，请检查它是否为 1.7 或更高版本。

1. 点击“开始”菜单，然后点击“运行”。
2. 在文本字段中输入 cmd。
3. 在提示符处输入 ant -version，查看您使用的版本。

如果您使用的是 1.7 及以上版本，请直接跳到获取 mail.jar。如果您的 Ant 版本低于 1.7 或者您没有安装该服务，请按以下步骤操作。

1. 访问 http://ant.Apache.org/bindownload.cgi
2. 点击 .zip 的下载链接。
3. 将所有文件提取到您选择的位置，例如 C:\ant
4. 将 Ant bin 目录（如 C:\ant\bin）添加到 Path 环境变量。
5. 添加或修改 ANT_HOME 环境变量以将其设置为新位置，例如 C:\ant。
6. 添加或修改 JAVA_HOME 环境变量 的 Java 安装位置，例如 C:\jdk。

如果您遇到任何问题，可在 Ant 网站上找到详细的安装说明。

获取 mail.jar

包含 JavaMail API 以实现媒体支持。

1. 访问 http://java.sun.com/products/javamail/downloads/index.html
2. 点击“下载”按钮。确保您下载的是版本 1.4 或更高版本。
3. 阅读并接受本许可协议。
4. 点击包含 JavaMail 的 .zip 文件的链接。
5. 将文件解压缩到您的计算机并记下位置。mail.jar 将位于根目录 javamail-(version) 下

获取 activate.jar

包含 JavaBeans 激活框架，用于提供媒体支持。

1. 访问 JAF 下载页面。
2. 点击“下载”按钮。
3. 阅读并接受本许可协议。
4. 点击包含激活框架的 .zip 文件的链接。
5. 将文件解压缩到您的计算机并记下位置。activation.jar 将位于根目录 jaf-(version) 下

获取 servlet.jar

servlet.jar（可能名为 servlet-api.jar）可在 servlet 容器（J2EE、Tomcat、WebLogic 等）中找到。它用于 AuthSub 和 Google Base 示例。以下说明介绍了如何获取 Tomcat 6.x。

1. 访问 http://tomcat.Apache.org/download-60.cgi
2. 点击 Core Binary Distribution 下的 Windows Service Installer 下载。
3. 运行安装程序。
4. 如果您一直使用默认值，servlet-api.jar 应位于 C:\Program Files\Apache Software Foundation\Tomcat 6.0\lib

如需查看更多 Tomcat 设置和安装文档，请点击此处。

好了，现在可以安装 GData Java 客户端库了。

在 Mac OS X 上

适用于 Mac OS X 操作系统的说明。

安装 Java

如果您运行的是 Mac OS X，那么的工作量会大大减少！Apple 为每个实例提供了全面配置、随时可用的 JDK（Java 开发套件）。如需了解详情，请访问 Apple 的 Java 网站。

安装 Ant

Apache Ant 是适用于 Java 的构建工具，与 make 类似（但更好）。您将使用它来构建库和执行示例。您可能也安装了 Ant，不过要检查您是否安装了 1.7+。

1. 打开一个终端窗口。（按 Command + 空格键，然后输入“Terminal”（终端）以查找应用）
2. 在命令提示符处，输入：

ant -version

如果您运行的蚂蚁版本低于 1.7，请按照以下步骤获取最新版本。

1. 访问 http://ant.Apache.org/bindownload.cgi
2. 点击 .zip 的下载链接。
3. 打开一个终端窗口。（按 Command + 空格键，然后输入“Terminal”（终端）以查找应用）
4. 在命令提示符处，输入以下内容：
   • cd ~/Desktop
   • sudo sh
   • mv apache-ant-(version)-bin.zip /usr/local/
   • cd /usr/local/
   • unzip apache-ant-(version)-bin.zip
   • chown (your account name):(your account name) apache-ant-(version)
   • ln -s apache-ant-(version) ant

如果您遇到任何问题，可在 Ant 网站上找到详细的安装说明。此博文还详细解释了上述 shell 命令的含义。

获取 mail.jar

包含 JavaMail API 以实现媒体支持。

1. 访问 http://java.sun.com/products/javamail/downloads/index.html
2. 点击“下载”按钮。确保您下载的是版本 1.4 或更高版本。
3. 阅读并接受本许可协议。
4. 点击包含 JavaMail 的 .zip 文件的链接。
5. 将文件解压缩到您的计算机并记下位置。mail.jar 将位于根目录 javamail-(version) 下

获取 activate.jar

包含 JavaBeans 激活框架，用于提供媒体支持。

1. 访问 JAF 下载页面。
2. 点击“下载”按钮。
3. 阅读并接受本许可协议。
4. 点击包含激活框架的 .zip 文件的链接。
5. 将文件解压缩到您的计算机并记下位置。activation.jar 将位于根目录 jaf-(version) 下

获取 servlet.jar

servlet.jar（可能名为 servlet-api.jar）可在 servlet 容器（J2EE、Tomcat、WebLogic 等）中找到。它用于 AuthSub 和 Google Base 示例。以下说明介绍了如何获取 Tomcat 6.x。

1. 访问 http://tomcat.Apache.org/download-60.cgi
2. 点击 Core Binary Distribution 下的 .zip 下载。
3. 将文件解压缩到您的计算机并记下位置。“servlet.jar”将位于“apache-tomcat-(version)/lib”下

如需查看更多 Tomcat 设置和安装文档，请点击此处。

好了，现在可以安装 GData Java 客户端库了。

在 Linux 上

适用于 Linux 操作系统的说明。

安装 Java

本教程将使用 Sun 的 JDK（Java 开发套件）。如果您拥有 root 访问权限，请按照以下说明操作。如果没有，您只需按照这些说明在主目录中安装 JDK 即可。如果您已安装 JDK 1.5+，请直接跳到安装 Ant。

如果您有 root 权限：

1. 访问 http://java.sun.com/javase/downloads/index.jsp
2. 点击最新版本旁边的“下载”。
3. 阅读并接受本许可协议。
4. 在“Linux 平台”下，点击并下载 RPM 文件自解压文件。
5. 打开一个终端窗口，切换到您下载文件所在的目录，然后执行以下操作：
• su
• chmod a+x jdk-6(version)-linux-i586-rpm.bin
• ./jdk-6(version)-linux-i586-rpm.bin
• 同意许可协议。

如果您没有 root 权限：

1. 访问 http://java.sun.com/javase/downloads/index.jsp
2. 点击最新版本旁边的“下载”。
3. 阅读并接受本许可协议。
4. 在“Linux 平台”下点击并下载自解压 build（而非 RPM）。
5. 打开一个终端窗口，切换到您下载文件所在的目录，然后输入以下命令：
• chmod +x jdk-6(version)-linux-i586-rpm.bin
• 切换到要安装的文件所在的目录。
• 运行自解压二进制文件。如果要将其安装在当前目录中，只需输入 ./jdk-6(version)-linux-i586-rpm.bin 即可
• 同意许可协议。

如果遇到问题，请点击此处查看更详细的安装说明。

安装 Ant

GData Java 客户端库需要 Ant 1.7 或更高版本。如果您已安装 Ant，请在命令提示符处输入 ant -version 来检查版本。如果您需要获取最新版本，或者您没有安装最新版本，请按照以下说明操作。如果您已设置 Java 和 Ant，请跳至获取 mail.jar。

1. 访问 http://ant.Apache.org/bindownload.cgi
2. 点击 .tar.gz 的下载链接。
3. 提取文件，方法是打开一个终端窗口，切换到包含下载文件的目录，然后输入以下命令：
• gunzip apache-ant-(version)-bin.tar.gz
• tar xvf apache-ant-(version)-bin.tar
4. 将 ant bin 目录添加到 PATH 环境变量中。
5. 添加或修改 ANT_HOME 环境变量，以将其设置为新位置。
6. 添加或修改 JAVA_HOME 环境变量，以将其设置为 JDK 的安装位置。

如果遇到任何问题，请点击此处查看 Ant 安装文档。

获取 mail.jar

包含 JavaMail API 以实现媒体支持。

1. 访问 http://java.sun.com/products/javamail/downloads/index.html
2. 点击“下载”按钮。确保您下载的是版本 1.4 或更高版本。
3. 阅读并接受本许可协议。
4. 点击包含 JavaMail 的 .zip 文件的链接。
5. 将文件unzip到您的计算机并注意其位置。mail.jar 将位于根目录 javamail-(version) 下

获取 activate.jar

包含 JavaBeans 激活框架，用于提供媒体支持。

1. 访问 JAF 下载页面。
2. 点击“下载”按钮。
3. 阅读并接受本许可协议。
4. 点击包含激活框架的 .zip 文件的链接。
5. 将文件unzip到您的计算机并注意其位置。activation.jar 将位于根目录 jaf-(version) 下

获取 servlet.jar

servlet.jar（可能名为 servlet-api.jar）可在 servlet 容器（J2EE、Tomcat、WebLogic 等）中找到。它用于 AuthSub 和 Google Base 示例。以下说明介绍了如何获取 Tomcat 6.x。

1. 访问 http://tomcat.Apache.org/download-60.cgi
2. 在 Core Binary Distribution 下下载 .tar.gz 文件。
3. 使用 gunzip 和 tar 将下载内容解压缩，如上面的安装 Ant 部分所示。
4. “servlet.jar”将位于“apache-tomcat-(version)/lib”下

现在，您应该已经拥有获取 GData Java 客户端库所需的一切！

安装 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 文件的位置。

注意：在 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("[e-mail]", "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("[e-mail]", "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/[e-mail]/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 等热门工具。以下是一些可能对您有用的其他链接：

• GData Java 客户端库首页
• Google 数据 API 列表
• Java 开发者指南适用于以下 Google 数据 API：
  • Content API for Shopping
  • Blogger
  • 通讯录
  • Google 日历
  • Google 文档列表
  • Google 财经
  • Google 电子表格
  • Google Search Console
  • YouTube
• 编写代码：将 Eclipse 与 Google 数据 API 配合使用
• Google 数据 API Java 客户端 Eclipse 插件

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

附录：设置环境变量

在 Windows 或 Linux 上设置环境变量的说明。您无需为 Mac OS X 设置任何内容。

Windows

系统变量将应用于计算机上的所有用户。如果您因没有管理员权限而无法修改系统变量，请按照此处的说明操作。

如果您拥有管理员权限：

1. 右键点击“我的电脑”，然后选择“属性”。
2. 点击“高级”标签页。
3. 点击“环境变量”。
4. “添加”或“修改”系统变量：（替换您本地机器上的位置）
• 添加或修改 ANT_HOME，并将该值设置为 C:\ant
• 添加或修改 JAVA_HOME，并将该值设置为 C:\jdk
• 添加或修改 Path，并在末尾附加 ;C:\ant\bin;C:\jdk\bin（分号分隔目录路径）
• 添加或修改 CLASSPATH，并附加所需的 .jar 文件，具体取决于您要使用的服务。请确保已包含“.”；这表明当前的目录。.;C:\gdata\java\lib\gdata-core-1.0.jar;C:\gdata\java\lib\gdata-calendar-1.0.jar 等
5. 重新启动以确保它们生效。

注意：请确保变量不含引号（即“或”），并且结尾不是 \ 或 /。

如果您没有管理员权限：

1. 右键点击“我的电脑”，然后选择“属性”。
2. 点击“高级”标签页。
3. 点击“环境变量”。
4. “添加”或“修改”用户变量：（替换掉本地机器上的位置）
• 添加或修改 ANT_HOME，并将该值设置为 C:\ant
• 添加或修改 JAVA_HOME，并将该值设置为 C:\jdk
• 添加或修改 Path，并在末尾附加 ;C:\ant\bin;C:\jdk\bin（分号分隔目录路径）
• 添加或修改 CLASSPATH，并附加所需的 .jar 文件，具体取决于您要使用的服务。请确保已包含“.”；这表明当前的目录。.;C:\gdata\java\lib\gdata-core-1.0.jar;C:\gdata\java\lib\gdata-calendar-1.0.jar 等
5. 重新启动以确保它们生效。

注意：请确保变量不含引号（即“或”），并且结尾不是 \ 或 /。

您刚刚修改的用户变量只会应用于您的用户个人资料。

Linux

1. 在编辑器（位于主目录下）中打开 .bash_profile 文件。
2. 将以下内容添加到您的 .bash_profile，注意替换文件在机器上的实际位置：
• export ANT_HOME=/usr/local/ant
• export JAVA_HOME=/usr/local/jdk
• export PATH=${PATH}:${ANT_HOME}/bin
• 您需要为要使用的服务添加 .jar 文件。例如 export CLASSPATH=${CLASSPATH}:/home/username/gdata/java/lib/gdata-core-1.0.jar:/home/username/gdata/java/lib/gdata-calendar-1.0.jar:/home/username/gdata/java/sample/util/lib/sample-util.jar
3. source .bash_profile，用于设置变量

注意：请确保变量不含引号（即“或”），并且结尾不是 \ 或 /。