月別: 2011年2月

Google Sites APIs-(1)


  Java Language Guide (v1.2)-(1)
GoogleサイトデータAPIは Google Siteの内容へのアクセス、公開、修正を可能にします。さらにクライアントアプリケーションは最近の活動のリストのリクエスト、改訂履歴の取得、添付物のダウンドードが出来ます。
サイトデータAPIの機能の背景の提供に加えて、このガイドはJava client libraryを使用してAPIと対話する例を提供します。 クライアントライブラリのセットアップのヘルプについてはGetting Started with the Google Data Java Client Libraryを見てください。ドキュメントと対話する為のJava クライアントライブラリによって使用される根本的なプロトコルについてより理解することに興味がある場合はprotocol guideを見てください。

 Contents

  1. Audience
  2. Getting Started
  3. Authenticating to the Sites API
    1. AuthSub for web applications
    2. OAuth for web or installed/mobile applications
    3. ClientLogin for installed/mobile applications
  4. Site Feed
    1. Listing sites
    2. Creating new sites
    3. Copying a site
    4. Updating a site’s metadata
    5. Web address mappings New
  5. Activity Feed
  6. Revision Feed
  1. Content Feed
    1. Retrieving content
    2. Deleting Content
    3. Downloading Attachments
  2. ACL Feed
    1. Overview of Sharing Permissions (ACLs)
    2. Retrieving the ACL feed
  3. Special Topics
    1. Retrieving a feed or entry again

 対象読者

このドキュメントはGoogleサイトと対話することが出来る Google Data Java Client Libraryを使用してクライアントアプリケーションを作成したい開発者を対象としています。

 はじめに

Googleサイトは認証にGoogleアカウントまたはGoogleAppsアカウントを使用します。アカウントを持っている場合は準備完了です。そうでない場合はアカウントを作成することが出来ます。

ライブラリのインストール

クライアントライブラリのインストールとセットアップのヘルプについてはGetting Started with the Google Data Java Client Libraryを見てください。Eclipseを使用している場合、さらにその記事でGoogle Data APIs Eclipse plugin.を使用してプロジェクトをセットアップする方法を説明しています。はじめにするべきことは次の通りです:
  1. Java 1.5 より新しいバージョンをインストール
  2. クライアントライブラリのダウンロード (gdata-src.java.zipの最新バージョン)
  3. リストにある依存ライブラリ群のダウンロード
  4. サンプルアプリケーション のダウンロード( gdata-samples.java.zipの最新バージョン)

.jars(ライブラリ)をインストールした後、プロジェクトに以下のものを含む必要があります:
  1. java/lib/gdata-sites-1.2.jar
  2. java/lib/gdata-core-1.0.jar
  3. java/lib/gdata-client-1.0.jar
  4. java/lib/gdata-spreadsheet-3.0.jar (リストページ/リストアイテムを使う場合)
さらに、依存するライブラリを必ず含めてください。(gdata-media-1.0.jarmail.jar、google-collect....jarなど)

サンプルアプリケーションの実行

完全に動作するサンプルアプリケーション—ダウンロードした gdata-samples.java.zip 内のサブディレクトリにあります。さらにソースはソースタブからアクセス出来るSVNリポジトリの/trunk/java/sample/sites/ で利用可能です。 SitesDemo.java はユーザーがサイトAPIを使う方法を説明する、幾つかの操作を実行することを可能にします?
サンプルを実行するために java/sample/util/lib/sample-util.jar を含む必要があることに注意してください。

あなたのプロジェクトの作成を開始する

TipEclipseプラグインを簡単にセットアップするにはUsing Eclipse with Google Data APIs の記事を見てください。
アプリケーションの必要に従い、幾つかのライブラリをインポートをする必要があります。以下のインポートで始めることを推奨します:
import com.google.gdata.client.*;
import com.google.gdata.client.sites.*;
import com.google.gdata.data.*;
import com.google.gdata.data.acl.*;
import com.google.gdata.data.media.*;
import com.google.gdata.data.sites.*;
import com.google.gdata.data.spreadsheet.*;  // If working with listpages / listitems
import com.google.gdata.util.*;
次に SitesService オブジェクトをセットアップする必要があります。このオブジェクトはサイトAPIへのクライアント接続を表します。
SitesService client = new SitesService("yourCo-yourAppName-v1");
applicationName 引数はcompany-applicationname-versionというフォーマットに従わなければなりません。このパラメータはロギング目的で使用されます。
注意: 以降のガイドは clientという変数名のSitesServiceオブジェクトを作成しているという前提で進めます

 サイトAPIへの認証

Javaクライアントライブラリはパブリックかまたはプライベートのフィードで動作させることが可能です。サイトデータAPIは
あなたが実行使用としている操作とサイトのパーミッションに従ってプライベート/パブリックフィードへのアクセスを提供します。クライアントに認証を要求する何か-たとえば、更新せずに公開サイトの内容フィードを読み取ることが出来るかもしれません?これはClientLogin のユーザーネーム/パスワード認証、AuthSub、または OAuth経由で行うことが可能です。
AuthSub、OAuth、ClientLoginについてのより詳しい情報はGoogle Data APIs Authentication Overview を見てください。
TipAPIはSSL (HTTPS)をサポートしています。AuthSub/OAuthを使用している場合は、SSL上でフィードをリクエストする為に必ず https://sites.google.com/feeds/ のスコープを指定します。Google Appsドメインでは管理コントロールパネルの’Require SSL’設定がAPIから尊重(参照?)されることに注意してください。client.useSsl()を呼ぶことによって全てのAPIリクエストにHTTPSを強制できます。

Webアプリケーション向けAuthSub

AuthSub Authentication for Web Applications はユーザーをGoogleアカウントへ認証することを必要とするクライアントアプリケーションで使用されるべきです。オペレータはGoogleサイトユーザー用のユーザーネームとパスワードを入力する必要がありません。AuthSubトークンのみが必要です。

アプリケーションにAuthSubを組み入れるための手順は以下を見てください

シングルユーストークンのリクエスト

ユーザーが初めてアプリケーションに訪れた時、ユーザーは認証する必要があります。一般に開発者はユーザーを認証する為のAuthSub承認ページへとユーザーを向かわせる何らかのテキストとリンクを表示し、彼らのドキュメントへのアクセス権をリクエストします。Google データ Java クライアントライブラリはこのURLを生成する機能を提供しています。以下のコードはAuthSubRequest ページへのリンクをセットアップします。.
import com.google.gdata.client.*;
String nextUrl = "http://www.example.com/welcome.jsp";
String scope = "https://sites.google.com/feeds/";
boolean secure = true;
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(nextUrl, scope, secure, session);
Google Apps ホスティッドドメインでユーザーを認証したい場合:
import com.google.gdata.client.*;
String hostedDomain = "example.com";
String nextUrl = "http://www.example.com/welcome.jsp";
String scope = "https://sites.google.com/feeds/";  // SSL is also supported
boolean secure = true;
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);
getRequestUrl() メソッドは(AuthSubRequest ハンドラによって使用されるクエリパラメータに一致している) 幾つかのパラメータを取ります:
  • the next URL — ユーザーがログインし、アクセスに承諾した後にGoogleが転送するURL;
    上記の例では http://www.example.com/welcome.jsp
  • the scope —上記の例では https://sites.google.com/feeds/
  • トークンが registered modeで使用されるかどうかを指示するboolean値;上記の例ではfalse
  • トークンを後でセッショントークンと交換するかどうかを指示する二番目のboolean値;上記の例ではtrue

セッショントークンに更新(交換)する

セッショントークンについての情報を取得する

セッショントークを無効にする

web/インストールされた/モバイルアプリケーション向けOAuth

OAuthはAuthSubの代わりとして使うことが出来、webアプリケーション向けに考えられています。OAuthは全てのデータリクエストが電子署名されていなければならない、あなたのドメインに登録していなければならないという点でAuthSubの secure and registered mode を使用するのと似ています。
インストールされたアプリケーションにOAuthを組み入れる手順を以下を見てください。

リクエストトークンの取得

リクエストトークンの認可

アクセストークンの更新(交換)

インストールされた/モバイルアプリケーション向けClientLogin

ClientLogin はGoogleアカウントへ認証することを必要とするデスクトップまたはモバイルアプリケーションで使われるべきです。最初の実行においてアプリケーションはユーザーにユーザーネーム/パスワードの入力を促します。後のリクエストにおいて認証トークンは参照されます。

インストールされたアプリケーションにClientLoginを組み入れる手順を以下を見てください
 ClientLoginを使用するにはGoogleServiceを継承したSitesService オブジェクトのsetUserCredentials()メソッドを実行してください。
ユーザーの代わりにリクエストを作成しているクライアントにeメールアドレスとパスワードを指定してください?例えば; 
SitesService client = new SitesService("yourCo-yourAppName-v1");
client
.setUserCredentials("example@gmail.com", "pa$$word");
Tipアプリケーションが初めてユーザーの認証に成功したら、後の使用で再利用するためにデータベースに認証トークンを格納してください。アプリケーション起動時に毎回ユーザーネーム/パスワードの入力を促す必要はありません。より詳しい情報はRecalling an auth token を見てください。
JavaアプリケーションでのClientLoginの使用についてのより詳しい情報はUsing ClientLogin with the Google Data API Client Librariesを見てください。

 サイトフィード

サイトフィードはユーザーが所有するかまたは閲覧許可を持っているGoogleサイトをリスト(一覧)にするために使用することが出来ます。さらに既存のサイトの名前を修正のために使用することも出来ます。Google Appsドメインにおいてはさらに、サイトを丸ごと作成またはコピーするために使用することも出来ます。

 サイトをリストにする

サイトフィードをクエリするにはサイトフィードURLにHTTP GETを送信します:
https://sites.google.com/feeds/site/site/
Javaクライアントでは、サイトフィードを扱うためにSiteFeed と SiteEntry クラスを使用することが出来ます?:
(※一番目のuseの訳し方がよくわからない)
public String getSiteFeedUrl() {
 
String domain = "site";  // または サイトがGoogle Appsでホストされている場合はあなたのドメイン (例えば example.com)
 
return "https://sites.google.com/feeds/site/" + domain + "/";
}
public void getSiteFeed() throws IOException, ServiceException {
 
SiteFeed siteFeed = client.getFeed(new URL(getSiteFeedUrl()), SiteFeed.class);
 
for (SiteEntry entry : siteFeed.getEntries()){
   
System.out.println("title: " + entry.getTitle().getPlainText());
   
System.out.println("site name: " + entry.getSiteName().getValue());
   
System.out.println("theme: " + entry.getTheme().getValue());
   
System.out.println("");
 
}
}
上記のコードはサイトのタイトル、サイトの名前、サイトのテーマを出力します。他のgetterメソッドを使ってフィードの他のプロパティにアクセスすることも出来ます。

 新しいサイトの作成

Note: この機能はGoogle Appsドメインでのみ利用可能です。
新しいサイトは新しいSiteEntry を作成し、サイトフィード上でclient(SiteServiceオブジェクト)のinsert()メソッドを呼び出すことによって作成出来ます。
この例はテーマ”slate”(任意設定)で真新しいサイトを作成し、サイトネーム(必須)と説明(任意)を指定しています:
public String getSiteFeedUrl() {
 
String domain = "example.com";
 
return "https://sites.google.com/feeds/site/" + domain + "/";
}
public SiteEntry createSite(String title, String summary, String theme)
   
throws MalformedURLException, IOException, ServiceException {
 
SiteEntry entry = new SiteEntry();
  entry
.setTitle(new PlainTextConstruct(title));
  entry
.setSummary(new PlainTextConstruct(summary));

 
Theme tt = new Theme();
  tt
.setValue(theme);
  entry
.setTheme(tt);

 
return client.insert(new URL(getSiteFeedUrl()), entry);
}
SiteEntry newSiteEntry = createSite("My Site Title", "summary for site", "slate");
上記のリクエストはGoogle Appsドメインのexample.comの下に新しいサイトを作成するでしょう。従って、サイトのURLはhttps://sites.google.com/a/example.com/my-site-titleになります。
サイトの作成が成功した場合、サーバはサイトへのリンク、サイトのACLフィードへのリンク、サイトネーム、タイトル、要約、その他のサーバによって追加される要素を含んだSiteEntry オブジェクトを返します。

 サイトのコピー

Note: この機能はGoogle Appsドメインでのみ利用可能です。
サイトをコピーすることは新しいサイトを作成することと似ています。違いは複製するサイト自身のリンクを含む新しいSiteEntry にリンクをセットする必要があるということです? 以下はCreating new sites セクションで作成したサイトを複製する例です:
public SiteEntry copySite(String title, String summary, String sourceHref)
   
throws MalformedURLException, IOException, ServiceException {
 
SiteEntry entry = new SiteEntry();
  entry
.setTitle(new PlainTextConstruct(title));
  entry
.setSummary(new PlainTextConstruct(summary));
  entry
.addLink(SitesLink.Rel.SOURCE, Link.Type.ATOM, sourceHref);

 
return client.insert(new URL(getSiteFeedUrl()), entry);
}
String sourceHref = newSiteEntry.getLink(SitesLink.Rel.SOURCE, Link.Type.ATOM).getHref();
SiteEntry myTwin = copySite("Duplicate Site", "A copy", sourceHref);
重要な点:
  • 認証したユーザーが所有するサイトとサイトテンプレートのみコピーすることが出来ます。
  • サイトテンプレートもコピー出来ます。Googleサイト設定ページで”Publish this site as a template”設定にチェックが入っている場合、サイトはテンプレートです。
  • 別のドメインからソースサイトであなたが所有者としてリストされているサイトをコピー出来ます?

 サイトのメタデータの更新

サイトの改名、テーマまたは要約の変更をするには、最初に対象のサイトを含むSiteEntryを取得し、1つ以上のプロパティを変更し、それからSiteEntryupdate()メソッドを呼び出します。この例は以前のサイトのテーマを変更し、サイトを改名します:
myTwin.setTitle(new PlainTextConstruct("better-title"));
Theme theme = myTwin.getTheme();
theme
.setValue('iceberg');
myTwin
.setTheme(theme);
SiteEntry updatedSiteEntry = myTwin.update();
System.out.println(updatedSiteEntry.getTitle().getPlainText();

 webアドレスマッピング

webアドレスマッピングは、サイトユーザーが自身のドメインをGoogleサイトにマップすることを可能にします。例えば、 http://sites.google.com/a/domain.com/mysiteの代わりにhttp://www.mydomainsite.com を使用することが出来ます。 サイトが何処でホストされるかによって、手動でサイトのwebアドレスマッチングを変更することが出来ます。より詳しい情報は我々のhelp centerの記事を見てください。

 サイトのwebアドレスマッチングの取得

サイトのwebアドレスマッチングを返すには、with-mappings=trueパラメータを付けてサイトエントリ/フィードを取って来てください:
(※上記文章はquery.setWithMappings(true);のことを指している?)
SiteQuery query = new SiteQuery(new URL("https://sites.google.com/feeds/site/siteName"));
query
.setWithMappings(true);
SiteFeed feed = service.getFeed(query, SiteFeed.class);
for (SiteEntry entry : feed.getEntries()) {
 
System.out.println("Mappings for '" + entry.getSiteName().getValue() + "':");
 
for (Link link : entry.getWebAddressMappingLinks()) {
   
System.out.println("  " + link.getHref());
 
}
}
既存のマッピングはrel=’webAddressMapping’を伴ったlinks として表示されます。 例えば上記の例ではサイト http://sites.google.com/site/myOtherTestSiteを指す三件のwebAddressMappingsがあります。

 webアドレスマッチングの変更

Note: webアドレスマッチングで動かす場合、全てのGET/POST/PUTオペレーションはwith-mappings=true パラメータを指定すべきです。パラメータ指定が無い場合、webAddressMappings はサイトエントリ(GET)では返されず、エントリのマッピング更新/除去(PUT)する時に考慮されません?
マッピングを追加、更新、削除するには、新しいサイトを作成 または サイトのメタデータの更新する時に、そのようなリンクを単純に指定、変更、除去をします。 with-mappings=trueパラメータはサイトフィードURIに含まれていなければなりません。 Note: アドレスマッチングを更新するには サイト管理者、またはGoogle Appsがホストをしているサイトの場合はドメイン管理者である必要があります。
例えば、以下のリクエストは http://www.mysitemapping.com マッピングをhttp://www.my-new-sitemapping.comへ更新し、エントリからリンクを外すことにより http://www.mysitemapping2.com を除去します:
SiteEntry entry = client.getEntry(new URL("https://sites.google.com/feeds/site/site/siteName?with-mappings=true"), SiteEntry.class);
// マッピングの変更 (全てのマッピングの除去、 再びそれらの幾つかを追加、マッピングの変更を追加?)
entry
.removeLinks(SitesLink.Rel.WEBADDRESSMAPPING, Link.Type.HTML);
entry
.addLink(SitesLink.Rel.WEBADDRESSMAPPING, Link.Type.HTML, "http://www.my-new-sitemapping.com");
// マッピングを伴ったエントリの更新
entry
.update();
Note, さらにwebアドレスマッチングはサイトを作成/コピーする時間を指定できます?

 アクティビティフィード

アクティビティフィードを取得することによってサイトの最近の活動(変更)を取得出来ます。アクティビティフィードの各エントリはサイトに対して行われた変更の情報を含みます。
アクティビティフィードをクエリするには、アクティビティフィードURLへHTTP GET を送信します:
https://sites.google.com/feeds/activity/site/siteName
Javaクライアントでは、 ActivityEntry オブジェクトを返すActivityFeed クラスを使用します:
public String buildActivityFeedUrl() {
 
String domain = "site";  // またはサイトがGoogle Appsでホストされているサイトの場合はあなたのドメイン(例えば example.com)
 
String siteName = "mySite";
 
return "https://sites.google.com/feeds/activity/" + domain + "/" + siteName + "/";
}
public void getActivityFeed() throws IOException, ServiceException {
 
ActivityFeed activityFeed = client.getFeed(new URL(buildActivityFeedUrl()), ActivityFeed.class);
 
for (BaseActivityEntry entry : activityFeed.getEntries()){
   
System.out.println(entry.getSummary().getPlainText());
   
System.out.println(" revisions link: " + entry.getRevisionLink().getHref());
 
}
}
Note: このフィードにアクセスするにはそのサイトの所有者か共同者である必要があります。クライアントはAuthSub、 OAuth、またはClientLoginトークンを使用して認証しなければなりません。Authenticating to the Sites serviceを見てください。

 リビジョンフィード

任意のコンテントエントリの改訂履歴を取得するにはエントリのリビジョンリンクにHTTP GET を送信します:
https://sites.google.com/feeds/revision/site/siteName/CONTENT_ENTRY_ID
この例はコンテントフィードをクエリし、それから最初のコンテントエントリ用のリビジョンフィードを取得します:
ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl()), ContentFeed.class);
URL revisionFeedUrl
= new URL(contentFeed.getEntries().get(0).getRevisionLink().getHref()); //最初のエントリを使用
public void getRevisionFeed(String revisionFeedUrl) throws IOException, ServiceException {
 
RevisionFeed revisionFeed = client.getFeed(revisionFeedUrl, RevisionFeed.class);
 
for (BaseContentEntry entry : revisionFeed.getEntries()){
   
System.out.println(entry.getTitle().getPlainText());
   
System.out.println(" updated: " + entry.getUpdated().toUiString() + " by " +
        entry
.getAuthors().get(0).getEmail());
   
System.out.println(" revision #: " + entry.getRevision().getValue());
 
}
}
Note:: このフィードにアクセスするにはそのサイトの所有者か共同者である必要があります。クライアントはAuthSub、 OAuth、またはClientLoginトークンを使用して認証しなければなりません。Authenticating to the Sites serviceを見てください。(※コロンが1つ余分?)

Google Sites APIs-(2)

  Java Language Guide (v1.2)-(2)

 コンテントフィード

コンテントフィードの取得

コンテントフィードはサイトの最新の内容をリストにします。コンテントフィードURLへHTTP GET を送信することにより、アクセスすることが出来ます:
https://sites.google.com/feeds/content/site/siteName
フィードパラメータ
説明
site
site” またはGoogle Apps でホストされているあなたのドメイン(例えばexample.com)
siteName
あなたのサイトのweb空間での名前;サイトのURL内にあります(例えばmySite).
コンテントフィードを取得してくる例:
public String buildContentFeedUrl() {
 
String domain = "site";  // または Google Appsにホストされているサイトの場合、あなたのドメイン(例えばexample.com)
 
String siteName = "mySite";
 
return "https://sites.google.com/feeds/content/" + domain + "/" + siteName + "/";
}
ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl()), ContentFeed.class);
結果として生じるcontentFeedはサーバからのレスポンスを含むContentFeedオブジェクトです。 Each entry of contentFeed の各エントリはユーザーのサイト内の異なるページまたはアイテムを表します。 ContentFeed は色々なタイプのオブジェクト(全てBaseContentEntryを継承している:ListItemEntryListPageEntryAttachmentEntry,WebAttachmentEntryFileCabinetPageEntryAnnouncementsPageEntryAnnouncementEntryWebPageEntryCommentEntry)を含みます。
以下はContentFeed内の色々なエントリのタイプをリストにする例です。各エントリタイプは色々なプロパティを含んでいますが、ここでは全てを出力していません。
public String getContentBlob(BaseContentEntry entry) {
 
return ((XhtmlTextConstruct) entry.getTextContent().getContent()).getXhtml().getBlob();
}
// エントリの数値IDを解凍する
private String getEntryId(String selfLink) {
 
return selfLink.substring(selfLink.lastIndexOf("/") + 1);
}
public void printContentEntries(ContentFeed contentFeed) {
 
System.out.println("Listing all WebPageEntry:");
 
for (WebPageEntry entry : contentFeed.getEntries(WebPageEntry.class)) {
   
System.out.println(" title: " + entry.getTitle().getPlainText());
   
System.out.println(" id: " + getEntryId(entry));
   
if (entry.getParentLink() != null) {
     
System.out.println(" parent id: " + getEntryId(entry.getParentLink().getHref()));
   
}
   
System.out.println(" author: " + entry.getAuthors().get(0).getEmail());
   
System.out.println(" content: " + getContentBlob(entry));
 
}

 
System.out.println("Listing all ListPageEntry:");
 
for (ListPageEntry entry : contentFeed.getEntries(ListPageEntry.class)) {
   
System.out.println(" title: " + entry.getTitle().getPlainText());
   
System.out.println(" id: " + getEntryId(entry));
   
for (Column col : entry.getData().getColumns()) {
     
System.out.print(" [" + col.getIndex() + "] " + col.getName() + "t");
   
}
 
}

 
for (ListItemEntry entry : contentFeed.getEntries(ListItemEntry.class)) {
   
for (Field field : entry.getFields()) {
     
System.out.print(" [" + field.getIndex() + "] " + field.getValue() + "t");
   
}
   
System.out.println("n");
 
}

 
System.out.println("Listing all FileCabinetPageEntry:");
 
for (FileCabinetPageEntry entry : contentFeed.getEntries(FileCabinetPageEntry.class)) {
   
System.out.println(" title: " + entry.getTitle().getPlainText());
   
System.out.println(" id: " + getEntryId(entry));
   
System.out.println(" content: " + getContentBlob(entry));
 
}

 
System.out.println("Listing all CommentEntry:");
 
for (CommentEntry entry : contentFeed.getEntries(CommentEntry.class)) {
   
System.out.println(" in-reply-to: " + entry.getInReplyTo().toString());
   
System.out.println(" content: " + getContentBlob(entry));
 
}

 
System.out.println("Listing all AnnouncementsPageEntry:");
 
for (AnnouncementsPageEntry entry : contentFeed.getEntries(AnnouncementsPageEntry.class)) {
   
System.out.println(" title: " + entry.getTitle().getPlainText());
   
System.out.println(" id: " + getEntryId(entry));
   
System.out.println(" content: " + getContentBlob(entry));
 
}

 
System.out.println("Listing all AnnouncementEntry:");
 
for (AnnouncementEntry entry : contentFeed.getEntries(AnnouncementEntry.class)) {
   
System.out.println(" title: " + entry.getTitle().getPlainText());
   
System.out.println(" id: " + getEntryId(entry));
   
if (entry.getParentLink() != null) {
     
System.out.println(" parent id: " + getEntryId(entry.getParentLink().getHref()));
   
}
   
System.out.println(" draft?: " + entry.isDraft());
   
System.out.println(" content: " + getContentBlob(entry));
 
}

 
System.out.println("Listing all AttachmentEntry:");
 
for (AttachmentEntry entry : contentFeed.getEntries(AttachmentEntry.class)) {
   
System.out.println(" title: " + entry.getTitle().getPlainText());
   
System.out.println(" id: " + getEntryId(entry));
   
if (entry.getParentLink() != null) {
     
System.out.println(" parent id: " + getEntryId(entry.getParentLink().getHref()));
   
}
   
if (entry.getSummary() != null) {
     
System.out.println(" description: " + entry.getSummary().getPlainText());
   
}
   
System.out.println(" revision: " + entry.getRevision().getValue());
   
MediaContent content = (MediaContent) entry.getContent();
   
System.out.println(" src: " + content.getUri());
   
System.out.println(" content type: " + content.getMimeType().getMediaType());
 
}

 
System.out.println("Listing all WebAttachmentEntry:");
 
for (WebAttachmentEntry entry : contentFeed.getEntries(WebAttachmentEntry.class)) {
   
System.out.println(" title: " + entry.getTitle().getPlainText());
   
System.out.println(" id: " + getEntryId(entry));
   
if (entry.getParentLink() != null) {
     
System.out.println(" parent id: " + getEntryId(entry.getParentLink().getHref()));
   
}
   
if (entry.getSummary() != null) {
     
System.out.println(" description: " + entry.getSummary().getPlainText());
   
}
   
System.out.println(" src: " + ((MediaContent) entry.getContent()).getUri());
 
}
}
Note:: このフィードは認証を必要とするかもしれないし、しないかもしれません; サイト共有のパーミッションに依存します。サイトが非公開の場合、クライアントはAuthSub, OAuth, or ClientLoginトークンを使用することにより認証しなければなりません。Authenticating to the Sites serviceを見てください。

 コンテントフィードをクエリする例

標準の Google データ API クエリパラメータの幾つかと、サイトAPI特有のパラメータを使用してコンテントフィードを検索出来ます。より詳しい情報とサポートされている全パラメータのリストについてはReference Guideを見てください。
Note: このセクションでの例はコンテントフィードの取得.のbuildContentFeedUrl() メソッドを利用します。

 特定の種類のエントリを取得

特定の種類のエントリのみを取得するには kindパラメータを使用します。この例は attachment エントリを返します:
ContentQuery query = new ContentQuery(new URL(buildContentFeedUrl()));
query
.setKind("webpage");
ContentFeed contentFeed = client.getFeed(query, ContentFeed.class);
for (AttachmentEntry entry : contentFeed.getEntries(AttachmentEntry.class)) {
 
System.out.println(entry.getTitle().getPlainText());
}
1種類以上のエントリタイプを返すには各 kind を’,’で分離します。この例はfilecabinetlistpageエントリを返します:
URL url = new URL(buildContentFeedUrl() + "?kind=filecabinet,listpage");
ContentFeed contentFeed = client.getFeed(url, ContentFeed.class);
for (FileCabinetPageEntry entry : contentFeed.getEntries(FileCabinetPageEntry.class)) {
 
System.out.println(" title: " + entry.getTitle().getPlainText());
}
for (ListPageEntry entry : contentFeed.getEntries(ListPageEntry.class)) {
 
System.out.println(" title: " + entry.getTitle().getPlainText());
}

 パスによるページの取得

Googleサイト内でのページの相対パスがわかっている場合、特定のページを取得するためにpathパラメータを使用することが出来ます。この例は http://sites.google.com/site/siteName/path/to/the/pageにあるページを返します:
ContentQuery query = new ContentQuery(new URL(buildContentFeedUrl()));
query
.setPath("/path/to/the/page");
ContentFeed contentFeed = client.getFeed(query, ContentFeed.class);
for (BaseContentEntry entry : contentFeed.getEntries()) {
 
System.out.println(" title: " + entry.getTitle().getPlainText());
}

親ページ以下の全てのエントリの取得

ページのコンテントエントリIDが分かっている場合 (例えば以下の例では”1234567890″)、(もしあれば)全ての子エントリを取得するためにparentパラメータを使用することが出来ます:
ContentQuery query = new ContentQuery(new URL(buildContentFeedUrl()));
query
.setParent("1234567890");
ContentFeed contentFeed = client.getFeed(query, ContentFeed.class);
追加パラメータについてはReference Guideを見てください。


 コンテントの作成

新しいコンテント (webページ, リストページ, ファイルキャビネットページ, アナウンスページ,その他.)はコンテントフィードへHTTP POST を送信することによって作成出来ます:
https://sites.google.com/feeds/content/site/siteName
サポートするノードタイプのリストについてはReference Guideの kind パラメータを見てください。

 新しいアイテム/ページの作成

この例はサイトのトップレベルの下にページボディに何らかのXHTMLを含み、ヘッドタイトルに ‘New WebPage Title’をセットした新しいwebpageを作成します:
private void setContentBlob(BaseContentEntry entry, String pageContent) {
 
XmlBlob xml = new XmlBlob();
  xml
.setBlob(pageContent);
  entry
.setContent(new XhtmlTextConstruct(xml));
}
   
public WebPageEntry createWebPage(String title, String content)
   
throws MalformedURLException, IOException, ServiceException {
 
WebPageEntry entry = new WebPageEntry();
  entry
.setTitle(new PlainTextConstruct(title));

  setContentBlob
(entry, content); // Entry's HTML content

 
return client.insert(new URL(buildContentFeedUrl()), entry);
}
WebPageEntry createdEntry = createWebPage("New Webpage Title", "HTML content");
System.out.println("Created! View at " + createdEntry.getHtmlLink().getHref());
リクエストが成功した場合、createdEntry はサーバで作成されたエントリのコピーを含みます。

 カスタマイズしたURLパス下でのアイテム/ページの作成

デフォルトでは、先の例はhttp://sites.google.com/site/siteName/new-webpage-title の下に作成され、’New Webpage Title’というページのヘッダ(見出し)を持ちます。 つまり、 はURLのnew-webpage-titleに正規化(統一?)されます。ページのURLパスをカスタマイズするには、要素をセットします。
この例は’File Storage’というヘッダで新しいfilecabinetページを作成しますが、 要素を指定することによって( http://sites.google.com/site/siteName/file-storageの代わりに) URL http://sites.google.com/site/siteName/files の下にページを作成します。
(※ 要素を指定することによって->FileCabinetPageEntry#setPageName()でページネームを指定することによって?)
public FileCabinetPageEntry createFileCabinetPage(String title, String content, String customPageName)
   
throws MalformedURLException, IOException, ServiceException {
 
FileCabinetPageEntry entry = new FileCabinetPageEntry();
  entry
.setTitle(new PlainTextConstruct(title));

  setContentBlob
(entry, content); // エントリのHTMLコンテント

  entry
.setPageName(new PageName(customPageName)); // カスタムページパスのアップロード

 
return client.insert(new URL(buildContentFeedUrl()), entry);
}
FileCabinetPageEntry createdEntry = createFileCabinetPage("File Storage", "HTML content", "files");
System.out.println("Created! View at " + createdEntry.getHtmlLink().getHref());
サーバはページのURLパスの命名に次の優先順位規則を使用します:
  1. 、存在する場合。 a-z, A-Z, 0-9, -, _で構成されなければなりません。
  2. 、ページネームが存在しない場合、nullであってはいけません。正規化は、+、連続する空白文字を’-‘へ調整し、a-z, A-Z, 0-9, -, _.に一致しない文字を除去します?

    ※タイトルを「test+  test  sあss++s@g」のようにした場合、URLは「test-test-sa-ss-s-g 」となるようなので、
    使用が許されている文字に変換できる文字は変換され、それ以外は単体でも連続して存在してもを’-‘に変換されるようです。

サブページの作成

親ページの下にサブページ(子ページ)を作成するには、エントリに親ページへのリンクをセットしなければなりません。  
リンクの href は親ノード自身のリンクとなります?
public AnnouncementEntry postAnnouncement(String title, String content, AnnouncementsPageEntry parentPage)
   
throws MalformedURLException, IOException, ServiceException {
 
AnnouncementEntry entry = new AnnouncementEntry();
  entry
.setTitle(new PlainTextConstruct(title));

  setContentBlob
(entry, content); // エントリの HTML コンテント

 
// 親ページの下にアナウンスメントエントリを作成するためにエントリのペアレントリンクをセットします。
  entry
.addLink(SitesLink.Rel.PARENT, Link.Type.ATOM, parentPage.getSelfLink().getHref());

 
return client.insert(new URL(buildContentFeedUrl()), entry);
}
ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl() + "?kind=announcementspage"), ContentFeed.class);
AnnouncementEntry createdEntry = postAnnouncement("Party!!", "My place, this weekend", contentFeed.getEntries().get(0));
System.out.println("New post by " + createdEntry.getAuthors().get(0).getName());
上記の例はユーザーのコンテントフィードで最初に見つかるアナウンスページの下に新しい announcement を作成します。アナウンスメントタイトルは”Party!!”、内容は”My place, this weekend”がセットされます。

 ページテンプレート

 ページテンプレートの作成

ページテンプレートを作成するプロセス(過程)は新しいアイテムとページの作成 と サブページの作成と同じです。違いは ‘http://schemas.google.com/g/2005#template’と’template’をそれぞれセットされたtermとレーベルを備えたcategory の追加です。
この例は新しいwebpage テンプレートを作成します.
// テンプレートウェブページエントリ.
WebPageEntry entry = new WebPageEntry();
// タイトルと内容のセット
entry
.setTitle(new PlainTextConstruct("Page template title"));
XmlBlob xml = new XmlBlob();
xml
.setBlob("Content for page template");
entry
.setContent(new XhtmlTextConstruct(xml));
// テンプレートカテゴリのセット
Category TEMPLATE_CATEGORY = new Category(TemplateCategory.Scheme.LABELS,
   
TemplateCategory.Term.TEMPLATE, TemplateCategory.Label.TEMPLATE);
entry
.getCategories().add(TEMPLATE_CATEGORY);
// テンプレートウェブページエントリの挿入
WebPageEntry createdEntry = client.insert(new URL("https://sites.google.com/feeds/content/site/siteName"), entry);

 テンプレートからのページの作成

ページテンプレートの作成と同様にページテンプレートのセルフリンクを指しているrel=’http://schemas.google.com/sites/2008#template’を備えた を含むことによってテンプレートから新しいページを生成出来ます。 
この例は 新しい filecabinet テンプレートを作成し、それからそのテンプレートから新しい filecabinet ページを生成します。
URL feedUrl = new URL("https://sites.google.com/feeds/content/site/siteName");
// 1. キャビネットページテンプレートの作成
FileCabinetPageEntry inputTemplateEntry = new FileCabinetPageEntry();
inputTemplateEntry
.setTitle(new PlainTextConstruct("File cabinet page template title"));
XmlBlob xml = new XmlBlob();
xml
.setBlob("Content for page template");
inputTemplateEntry
.setContent(new XhtmlTextConstruct(xml));
// テンプレートカテゴリのセット
Category TEMPLATE_CATEGORY = new Category(TemplateCategory.Scheme.LABELS,
   
TemplateCategory.Term.TEMPLATE, TemplateCategory.Label.TEMPLATE);
inputTemplateEntry
.getCategories().add(TEMPLATE_CATEGORY);
// 2. ファイルキャビネットページテンプレートのインスタンスを作成
FileCabinetPageEntry templateEntry = client.insert(feedUrl, inputTemplateEntry);
// ページテンプレートへのリンクの指定
FileCabinetPageEntry templateInstanceEntry = new FileCabinetPageEntry();
templateInstanceEntry
.setTitle(new PlainTextConstruct("File cabinet template instance"));
templateInstanceEntry
.addLink(new Link(SitesLink.Rel.TEMPLATE, Link.Type.ATOM, templateEntry.getSelfLink().getHref()));
FileCabinetPageEntry createdFileCabinetFromTemplate =  client.insert(feedUrl, templateInstanceEntry);
Note: テンプレートが を定義しているのに関わらず、エントリにも一つ含まれることが必要です。さらに注意することは、  要素を含んでいない場合、サーバはエントリをリジェクト(拒絶)します。

 ファイルの更新

ちょうどGoogleサイトのように、APIはフィルキャビネットページまたは親ページへの添付アップロードをサポートします
親ページへ添付物をアップロードするには、コンテントフィードURLに HTTP POSTリクエストを送信します:
https://sites.google.com/feeds/content/site/siteName
全ての添付物のタイプは親ページへアップロードされなければなりません。したがってアップロードしようとしている AttachmentEntryまたはWebAttachmentEntry オブジェクトへ親ページへのリンクをセットします。より詳しい情報は サブページの作成を見てください。

 添付物のアップロード

この例はユーザーコンテントフィードで最初に見つかったFileCabinetPageEntry へPDFファイルをアップロードします。 添付物は’Getting Started’というタイトルと’HR packet’という説明(任意)で作成されます。
MimetypesFileTypeMap mediaTypes = new MimetypesFileTypeMap();
mediaTypes
.addMimeTypes("application/msword doc");
mediaTypes
.addMimeTypes("application/vnd.ms-excel xls");
mediaTypes
.addMimeTypes("application/pdf pdf");
mediaTypes
.addMimeTypes("text/richtext rtx");
// ... SitesHelper.java のmimeタイプのより完全なリストを見てください
public AttachmentEntry uploadAttachment(File file, BasePageEntry parentPage,
   
String title, String description) throws IOException, ServiceException {
 
AttachmentEntry newAttachment = new AttachmentEntry();
  newAttachment
.setMediaSource(new MediaFileSource(file, mediaTypes.getContentType(file)));
  newAttachment
.setTitle(new PlainTextConstruct(title));
  newAttachment
.setSummary(new PlainTextConstruct(description));
  newAttachment
.addLink(SitesLink.Rel.PARENT, Link.Type.ATOM, parentPage.getSelfLink().getHref());

 
return client.insert(new URL(buildContentFeedUrl()), newAttachment);
}
ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl() + "?kind=filecabinet"), ContentFeed.class);
FileCabinetPageEntry parentPage = contentFeed.getEntries(FileCabinetPageEntry.class).get(0);
AttachmentEntry attachment = uploadAttachment(
   
new File("/path/to/your/file.pdf"), parentPage, "Getting Started", "HR packet");
System.out.println("Uploaded!");
アップロードに成功した場合、attachment は作成された添付物エントリのコピーを含みます。

 フォルダへの添付物のアップロード

 FileCabinetPageEntry内の既存のフォルダに添付物をアップロードするには、フォルダの名前がセットされた’term’属性を備えたカテゴリを含みます。 例えば uploadAttachment()メソッド内に以下の行を追加します:
newAttachment.getCategories().add(new Category("http://schemas.google.com/sites/2008#folder", "FolderName"));

 web添付物

web添付物は添付物の特別な種類です。基本的に、web添付物とはファイルキャビネットの一覧に追加することの出来るweb上の他のファイルへのリンクです。この機能はGoogleサイトユーザーインターフェイスの’URLによるファイルの追加’アップロードメソッドと似ています。 
Note: web添付物はファイルキャビネットの下にのみ作成することが出来ます。他のタイプのページにアップロードすることは出来ません。
この例はユーザーのコンテントフィードで最初に見つかったFileCabinetPageEntryの下にWebAttachmentEntryを作成します。タイトルと説明(任意)はそれぞれ’GoogleLogo’と’nice colors’にセットされます。
public WebAttachmentEntry uploadWebAttachment(String contentUrl, FileCabinetPageEntry filecabinet,
   
String title, String description) throws MalformedURLException, IOException, ServiceException {
 
MediaContent content = new MediaContent();
  content
.setUri(contentUrl);

 
WebAttachmentEntry webAttachment = new WebAttachmentEntry();
  webAttachment
.setTitle(new PlainTextConstruct(title));
  webAttachment
.setSummary(new PlainTextConstruct(description));
  webAttachment
.setContent(content);
  webAttachment
.addLink(SitesLink.Rel.PARENT, Link.Type.ATOM,
      filecabinet
.getSelfLink().getHref());

 
return client.insert(new URL(buildContentFeedUrl()), webAttachment);
}
ContentFeed contentFeed = client.getFeed(new URL(buildContentFeedUrl() + "?kind=filecabinet"), ContentFeed.class);
FileCabinetPageEntry parentPage = contentFeed.getEntries(FileCabinetPageEntry.class).get(0);
WebAttachmentEntry webAttachment =
    uploadWebAttachment
("http://www.google.com/images/logo.gif", parentPage, "Google's Logo", "nice colors");
System.out.println("Web attachment created!");
POSTは’http://www.google.com/images/logo.gif’のイメージを指すリンクをユーザーのファイルキャビネットに作成します。

 コンテントの更新

 ページのメタデータ/htmlコンテントの更新

BaseContentEntryを継承したオブジェクトのメタデータ (タイトル、ページネーム、その他) とページ内容はエントリの update() メソッドを使用することによって編集することが出来ます。それはエントリのeditリンクへHTTP PUT リクエストを送信します。
次の例は以下の変更をしてListPageEntryを更新します:
  • タイトルを ‘Updated Title’に変更
  • ページのHTMLコンテントを’

    Updated HTML Content

    ‘へ更新

  • リストの最初のカラムの見出しは”Owner”へ変更されます。
ContentFeed contentFeed = client.getFeed(
   
new URL(buildContentFeedUrl() + "?kind=listpage"), ContentFeed.class);
ListPageEntry listPage = contentFeed.getEntries(ListPageEntry.class).get(0); // 最初に見つかったリストページを更新
// タイトルの更新
listPage
.setTitle(new PlainTextConstruct("Updated Title"));
// HTMLコンテントの内容
XmlBlob xml = new XmlBlob();
xml
.setBlob("

Updated HTML Content

");
listPage
.setContent(new XhtmlTextConstruct(xml));
// 最初のカラムの見出しを変更
listPage
.getData().getColumns().get(0).setName("Owner");
// listPage.setPageName(new PageName("new-page-path"));  // 更にページのURLパスを変更することも出来ます
ListPageEntry updatedEntry = listPage.update();
System.out.println("ListPage updated!");

 添付ファイルの内容の更新

 AttachmentEntryに対して、エントリの MediaSource を設定して、updateMedia(boolean)メソッドを使用することによってコンテント(内容)を更新することも出来ます。
この例は既存の添付物の内容を更新します:
public AttachmentEntry updateFile(AttachmentEntry entry, File newFile)
   
throws IOException, ServiceException {
 
// メディアタイプの定義についてはUploading Attachmentsを見てください
  entry
.setMediaSource(new MediaFileSource(newFile, mediaTypes.getContentType(newFile)));
 
return entry.updateMedia(false);
}
この例はエントリのedit-mediaリンクへHTTP PUT リクエストを送信します。返されたAttachmentEntryは更新された内容を含みます。

 添付物のメタデータ+内容の更新

 updateMedia()メソッドを使用することによって、一回の呼び出しで添付物のメタデータとその内容を更新することが出来ます。ファイル内容かメタデータのどちらか、または両方を更新出来ます。
この例は添付物のタイトルを’New Title’へ変更し、その説明を更新し、そのファイルの内容を新しいzipファイルに置換えます。リクエストは新しいファイル内容を含むので、AttachmentEntryupdateMedia()メソッドを使用します。
public AttachmentEntry updateAttachment(AttachmentEntry entry, File newFile, String newTitle, String newDescription)
   
throws IOException, ServiceException  {
 
//メディアタイプの定義についてはUploading Attachmentsを見てください
  entry
.setMediaSource(new MediaFileSource(newFile, mediaTypes.getContentType(newFile)));
  entry
.setTitle(new PlainTextConstruct(newTitle));
  entry
.setSummary(new PlainTextConstruct(newDescription));

 
return entry.updateMedia(true);
}
ContentFeed contentFeed = client.getFeed(
   
new URL(buildContentFeedUrl() + "?kind=attachment&max-results;=1"), ContentFeed.class);
AttachmentEntry attachment = contentFeed.getEntries(AttachmentEntry.class).get(0); // 最初に見つかった添付物を更新します
AttachmentEntry updatedAttachment = updateAttachment(attachment, new File("/path/to/file.zip"), "New Title", "better stuff");

 コンテントの削除

Googleサイトからページまたはアイテムを除去するには、最初にコンテントエントリを取得し、それからそのエントリのdelete()メソッドを呼び出します。
entry.delete();
サービスクラス(オブジェクト?)へエントリのeditリンクとETagの値を渡すことによってサービスクラスの delete() メソッドを使用することも出来ます:
client.delete(entry.getEditLink().getHref(), "*"); // Note: using "*" may overwrite another client's changes.
エントリの削除に成功した場合、サーバはHTTP 200 OKを返します。

 添付物のダウンロード

AttachmentEntryをダウンロードするには、エントリのコンテントsrc リンクへHTTP GET リンクを送信します。
ディレクトリ”/path/to/save/file/”へのユーザーのコンテントフィード内で最初に見つかったAttachmentEntryをダウンロードします:
private void downloadFile(String downloadUrl, String fullFilePath) throws IOException, ServiceException {
 
System.out.println("Downloading file from: " + downloadUrl);

 
MediaContent mc = new MediaContent();
  mc
.setUri(downloadUrl);
 
MediaSource ms = service.getMedia(mc);

 
InputStream inStream = null;
 
FileOutputStream outStream = null;

 
try {
    inStream
= ms.getInputStream();
    outStream
= new FileOutputStream(fullFilePath);

   
int c;
   
while ((c = inStream.read()) != -1) {
      outStream
.write(c);
   
}
 
} finally {
   
if (inStream != null) {
      inStream
.close();
   
}
   
if (outStream != null) {
      outStream
.flush();
      outStream
.close();
   
}
 
}
}
public void downloadAttachment(AttachmentEntry entry, String directory) throws IOException, ServiceException {
 
String url = ((OutOfLineContent) entry.getContent()).getUri();
  downloadFile
(url, directory + entry.getTitle().getPlainText()); // セーブファイルネームとしてエントリのタイトルを使用
}
ContentFeed contentFeed = client.getFeed(
   
new URL(buildContentFeedUrl() + "?kind=attachment&max-results;=1"), ContentFeed.class);

downloadAttachment
(contentFeed.getEntries(AttachmentEntry.class).get(0), "/path/to/save/file/");
System.out.println("Downloaded.");

 ACL フィード

共有パーミッション(ACLs)の概要

ACLフィードの各ACLエントリはユーザー、ユーザーグループ、ドメイン、(公開サイトでの) デフォルトアクセスのいずれかの特定のエンティティ(エンティティ)のアクセスロールを表しています。エントリは明示的なアクセスを備えたエンティティに対してのみ表示されます - あるエントリはGoogle サイトユーザーインターフェイスの共有スクリーンの”People with Access”パネルで各eメールアドレスに対して表示されます? したがって、ドメイン管理者がサイトに暗黙的アクセスをしてもドメイン管理者は表示されません?

 ロール

ロール要素はエンティティが持つことが出来るアクセスレベルを表します。
gAcl:role 要素で使用可能なタイプは4種類あります:(※3種類のように思うが原文ではfour?)
  • reader — 閲覧者 (リードアクセスオンリーと等価).
  • writer — 共同者 (リード/ライトアクセスと等価).
  • owner — 一般にサイト管理者(リード/ライトアクセスと等価).

 スコープ

スコープ要素はこのアクセスレベルをもつエンティティを表します。
 gAcl:scope 要素で使用可能な値のタイプは4種類あります:
  • user — eメールアドレスの値、例えば”user@gmail.com”.
  • group — Googleグループのeメールアドレス、例えば”group@domain.com”.
  • domain — Google Apps ドメインネーム、例えば”domain.com”.
  • default — typeの値が常に”default”固定の使用可能なスコープが一つだけあります? (例えば). 特にこのスコープは公開サイトでデフォルトでどんなユーザーのアクセスを管理します?
Note: ドメインは gAcl:role の値に”owner” アクセスをセットすることは出来ません、彼らはリーダーまたはライターにのみなることが出来ます。

 ACLフィードの取得

AclFeed クラスと AclEntry クラスはサイトの共有パーミッションを管理するために使うことが出来、サービスクラスの getFeed() メソッドを使用して取得することが出来ます。
次の例は引数として与えられたサイトのACLフィードを取得して各 AclEntryのパーミッションを出力します:
public String getAclFeedUrl(String siteName) {
 
String domain = "site";  // またはサイトがGoogle Appsにホストされている場合は、あなたのドメイン(例えばexample.com)
 
return "https://sites.google.com/feeds/acl/site/" + domain + "/" + siteName + "/";
}
public void getAclFeed(String siteName) throws IOException, ServiceException {
 
AclFeed aclFeed = client.getFeed(new URL(getAclFeedUrl(siteName)), AclFeed.class);
 
for (AclEntry entry : aclFeed.getEntries()) {
   
System.out.println(entry.getScope().getValue() + " (" + entry.getScope().getType() + ") : " +
                       entry
.getRole().getValue());
 
}
}

getAclFeed
('my-site-name');
SiteFeed内のエントリで動いている場合、各SiteEntry はそのACLフィードへのリンクを含みます? 例えばこのコードは SiteEntryのACLフィードを取得します:
String aclLink = siteEntry.getLink(SitesAclFeedLink.Rel.ACCESS_CONTROL_LIST, Link.Type.ATOM).getHref();
AclFeed aclFeed = client.getFeed(new URL(aclLink), AclFeed.class);

 サイトの共有

Noteドメインがそのようなパーミッション(例えば、Google Apps ドメインのドメイン外共有が有効、など)を許す設定の場合でのみ、共有ACLは可能です? 
APIを使用してGoogleサイトを共有するには、クライアントは新しいAclEntryを作成し、サーバにそれを POST する必要があります。(※原文、”,”が一つ余計?)
以下はサイトにreaderとして’user@example.com’ を追加する例です:
AclRole role = new AclRole("reader");
AclScope scope = new AclScope(AclScope.Type.USER, "user@example.com");
AclEntry aclEntry = addAclRole(role, scope, entry);
 
public AclEntry addAclRole(AclRole role, AclScope scope, SiteEntry siteEntry)
   
throws IOException, MalformedURLException, ServiceException  {
 
AclEntry aclEntry = new AclEntry();
  aclEntry
.setRole(role);
  aclEntry
.setScope(scope);
 
 
Link aclLink = siteEntry.getLink(SitesAclFeedLink.Rel.ACCESS_CONTROL_LIST, Link.Type.ATOM);
 
return client.insert(new URL(aclLink.getHref()), aclEntry);
}
 使用可能なAclScope と AclRoles の値についてはACL feed Overview セクションを見てください。

 グループ・ドメインレベルでの共有

sharing a site (with a single user?)と同様に GoogleグループまたはGoogle Appsドメインでサイトを共有することが出来ます。
グループeメールアドレスの共有:
AclScope scope = new AclScope(AclScope.Type.GROUP, "group_name@example.com");
ドメイン全体での共有:
AclScope scope = new AclScope(AclScope.Type.DOMAIN, "example.com");
ドメインレベルでの共有はGoogle Apps ドメインでいて、かつサイトをホストしているドメインのみでサポートされます。たとえば、http://sites.google.com/a/domain1.com/siteAはdomain1.comのサイト全体のみを共有出来ますがdomain2.comは出来ません。Google Appsドメインでホストされていないサイト(例えば http://sites.google.com/site/siteB)はドメインを招待出来ません? (※invite?)

 共有パーミッションの変更

サイトの既存の共有パーミッションを変更するには(※原文 modify抜け?)、 最初にその対象となるAclEntry を取得し、希望のパーミッションに変更し、それからサーバ上のACLを変更するためにAclEntryupdate() メソッドを呼び出します。
この例は’user@example.com’を writer (共同者)に更新することによって、Sharing a site セクションの例で我々が前に扱ったaclEntryを変更します:
aclEntry.setRole(new AclRole("writer"));
AclEntry updatedAclEntry = aclEntry.update();
 
// 更にクライアントのupdate メソッドを使うことも出来ます。
// client.update(new URL(aclEntry.getEditLink().getHref()), aclEntry);
ETagsについてのより詳しい情報は、Google Data APIs reference guideを見てください。

 共有パーミッションの除去

共有パーミッションを除去するには、最初に AclEntryを取得し、それからそれのdelete()メソッドを呼びます:
aclEntry.delete();
 
// 更にクライアントのdeleteメソッドを使うことも出来ます。
// client.delete(new URL(aclEntry.getEditLink().getHref()), aclEntry);
ETagsについてのより詳しい情報は、Google Data APIs reference guideを見てください。
  

  スペシャルトピック

 フィードまたはエントリの再取得

以前に取得したフィードまたはエントリを取得したい場合、最後に取得した時から変更があった時のみリストまたはエントリを送信するようにサーバに伝えることにより、効率を改善することが出来ます
この種類の条件付き取得をするには、getFeed()getEntry() メソッド両方で ETagの値または If-Modified-Since ヘッダ用の DateTime オブジェクトを受諾する追加の引数を指定します?。 entry.getEtag()でエントリのETagにアクセス出来ます。
この例はコンテントwebページエントリで条件付き取得を行います:
String feedUrl = "https://sites.google.com/feeds/content/site/siteName/123456789";
WebPageEntry entry = client.getEntry(new URL(feedUrl), WebPageEntry.class, ""GVQHSARDQyp7ImBq"");
サーバがこのリクエストを受け取ると、サーバはリクエストしたアイテムが指定したETagと同じETagを持っているかどうかを確認するためにチェックします。 ETagが一致した場合、アイテムは変更されておらず、サーバはHTTP 304と 投げられるであろうNotModifiedException 例外のどちらかを返します?
ETagsが一致しない場合、 アイテムは最後にリクエストした時から変更されており、サーバはアイテムを返します。
ETagsについてのより詳しい情報は、Google Data APIs reference guideを見てください。

Google Documents List Data API v3.0 – (2)

Google Documents List Data API v3.0 – (1)

Google Documents List Data API v3.0 – (3)



Java Language Guide (v3.0) – (2)

   ドキュメント内容の取得

フルテキスト検索からフォルダ内容検索まで、さまざまなメソッドを使用して指定した内容を取得または検索出来ます。  このセクションはドキュメント内容を取得する幾つかの方法を示します。さらに、全てのドキュメントの内容をくまなく検査する為にフルテキストクエリ文字列(q パラメータ)を使うことが出来ます。ドキュメントリストに特有のパラメータについてのより詳しい情報はDocuments List Data API Reference Guideで見つけることが出来ます。 追加情報については the standard Google Data API query parametersをいくつかを見てください。

完全タイトル検索

ドキュメントの全内容の代わりにタイトルとの一致でドキュメントを取得することが可能です。これを行うために、ドキュメントリストフィードに対しての複雑なクエリを構築するために DocumentQueryクラスを使用することが出来ます。
この例は、明示的に完全タイトル(での検索)を示すためにtitleパラメータとtitle-exactパラメータを使用しています。 このパラメータは大文字・小文字を区別しない(case-insensitive)、または複数のドキュメントは同じタイトルを持つことが出来るので、フィードは返されます?
次の例は”Test”というタイトルに最初に一致する10件のドキュメントを検索します。
URL feedUri = new URL("https://docs.google.com/feeds/default/private/full/");
DocumentQuery query = new DocumentQuery(feedUri);
query
.setTitleQuery("Test");
query
.setTitleExact(true);
query
.setMaxResults(10);
DocumentListFeed feed = client.getFeed(query, DocumentListFeed.class);
printDocuments
(feed);
Notetitle-exact クエリは大文字・小文字を区別しません。

フルテキスト検索

 qパラメータまたはDocumentQueryオブジェクトのsetFullTextQuery()メソッドを使用してドキュメントの内容を検索出来ます。 
URL feedUri = new URL("https://docs.google.com/feeds/default/private/full/");
DocumentQuery query = new DocumentQuery(feedUri);
query
.setFullTextQuery("Something to search for");
DocumentListFeed feed = client.getFeed(query, DocumentListFeed.class);
printDocuments
(feed);
このコードは全てのドキュメントの全内容を“Something to search for”という文字列で検索し、この文字列が見つかった全てのドキュメントを返します。 これは全てのドキュメントのタイトルの検索とは異なります。

フォルダ内容の取得

特定のフォルダにあるオブジェクトのリストを取得する為に、フォルダのフィードURLへHTTP GET を送信します。 URLは次のようなものになります:
https://docs.google.com/feeds/default/private/full/folder%3Afolder_id/contents
※folder_id はGoogleDocsでフォルダを開いた時の「folder.0.」以降の文字列のようです。







ドキュメントリスト中のフォルダAtomエントリは全て、このようなリンクを含むでしょう。フォルダのコンテンツフィードはフォルダエントリの タグのsrc属性で見つけることが出来ます。例は以下の通りです:

String foldersFeedUri = ((MediaContent) folderEntry.getContent()).getUri();
//フォルダーのリソースidを知っている場合、手動でfoldersFeedUriを構築することも出来ます。(例えば folder%3Afolder_id)
// URL foldersFeedUri = new URL("https://docs.google.com/feeds/default/private/full/folder%3Afolder_id/contents");
DocumentQuery query = new DocumentQuery(feedUri);
query
.setFullTextQuery("Something to search for");
DocumentListFeed feed = client.getFeed(query, DocumentListFeed.class);
printDocuments
(feed);
   
デフォルトではフォルダエントリもフォルダフィード内で返されます。 (例えば showfolders=true パラメータを含む必要はありません。 Documents List Data API Reference Guideで定義されているクエリパラメータを使用してフォルダフィードをクエリすることも出来ます。

  ドキュメントのアップロード

このセクションではドキュメントのアップロードする為に使用出来る様々なメソッドを説明します。

内容が空のドキュメントの作成

この例はドキュメント用メタデータを含む DocumentListEntryオブジェクトを作成することによってドキュメントリストフィードで新しいワードプロセッサ文書を作成します?
DocumentListEntry createdEntry = null;
//空のワードプロセッサ文書を作成
createdEntry
= createNewDocument("NewDocTitle", "document");
System.out.println("Document now online @ :" + createdEntry.getDocumentLink().getHref());
//空のプレゼンテーションを作成
createdEntry
= createNewDocument("NewPresentationTitle", "presentation");
System.out.println("Presentation now online @ :" + createdEntry.getDocumentLink().getHref());
//空のスプレッドシートを作成
createdEntry
= createNewDocument("NewSpreadsheetTitle", "spreadsheet");
System.out.println("Spreadsheet now online @ :" + createdEntry.getDocumentLink().getHref());
public DocumentListEntry createNewDocument(String title, String type)
   
throws IOException, ServiceException {
 
DocumentListEntry newEntry = null;
 
if (type.equals("document")) {
    newEntry
= new DocumentEntry();
 
} else if (type.equals("presentation")) {
    newEntry
= new PresentationEntry();
 
} else if (type.equals("spreadsheet")) {
    newEntry
= new SpreadsheetEntry();
 
}
  newEntry
.setTitle(new PlainTextConstruct(title));

 
// 共同者が他の人とドキュメントを共有するのを妨げますか?
 
// newEntry.setWritersCanInvite(false);

 
// 作成中のドキュメントも隠す(非表示にする?)ことが出来ます
 
// newEntry.setHidden(true);

 
return client.insert(new URL("https://docs.google.com/feeds/default/private/full/"), newEntry);
}

内容があるドキュメントのアップロード

サーバへドキュメントをアップロードするために、 setFile() メソッドを使用してファイルを新しいDocumentListEntry に添付することが出来ます。 ファイルをこのエントリに関連付け、 DocumentListEntry.を挿入した時、コンテンツがサーバへ送られるでしょう。 
この以下の例はファイルの絶対パスを与えられた場合にファイルをアップロードする方法を示します。 サーバへ送られたマイムタイプはファイルの拡張子から推定されることに注意してください。
DocumentListEntry uploadedEntry = uploadFile("/path/to/your/file.doc", "TitleToUse");
System.out.println("Document now online @ :" + uploadedEntry.getDocumentLink().getHref());
public DocumentListEntry uploadFile(String filepath, String title)
   
throws IOException, ServiceException  {
 
File file = new File(filepath);
 
String mimeType = DocumentListEntry.MediaType.fromFileName(file.getName()).getMimeType();

 
DocumentListEntry newDocument = new DocumentListEntry();
  newDocument
.setFile(file, mimeType);
  newDocument
.setTitle(new PlainTextConstruct(title));

 
// 共同者が他の人とドキュメントを共有するのを妨げますか?
 
// newDocument.setWritersCanInvite(false);

 
return client.insert(new URL("https://docs.google.com/feeds/default/private/full/"), newDocument);
}
Note: 上記のサンプルはドキュメントの名前に”TitleToUse”をセットしていますが、 PlainTextConstruct コンストラクタに文字列を渡す事によって違う名前を選ぶことは自由です。

フォルダへのドキュメントの作成/アップロード

フォルダ内での空のドキュメント作成

既存のフォルダに空のドキュメント、プレゼンテーション、スプレッドシートを作成するために、フォルダのAtomコンテントソースURLへ POST リクエストを送る必要があります。これを行う一つの方法は親フォルダの URL を受け入れるために我々のcreateNewDocument() メソッドをオーバーロードすることです。ここではfolderEntryは対象(転送先)フォルダを表す DocumentListEntry オブジェクトと仮定しています。 
String destFolderUrl = ((MediaContent) folderEntry.getContent()).getUri();
// 代わりに手動でdestFolderUrlを構築出来ます。 (例えばフォルダのリソースidを持っている場合のみ?):
// URL destFolderUrl = new URL("https://docs.google.com/feeds/default/private/full/FOLDER_RESOURCE_ID/contents");
DocumentListEntry createdEntry = createNewDocument("NewDocument", "document", destFolderUrl);
System.out.println("Document now online in folder '" +
    folderEntry
.getTitle().getPlainText() + "' @ :" + createdEntry.getDocumentLink().getHref());
public DocumentListEntry createNewDocument(String title, String type, URL uri)
   
throws IOException, ServiceException {
 
DocumentListEntry newEntry = null;
 
if (type.equals("document")) {
    newEntry
= new DocumentEntry();
 
} else if (type.equals("presentation")) {
    newEntry
= new PresentationEntry();
 
} else if (type.equals("spreadsheet")) {
    newEntry
= new SpreadsheetEntry();
 
}
  newEntry
.setTitle(new PlainTextConstruct(title));

 
return client.insert(uri, newEntry);
}
public DocumentListEntry createNewDocument(String title, String type)
   
throws MalformedURLException, IOException, ServiceException {
 
return createNewDocument(title, type, new URL("https://docs.google.com/feeds/default/private/full/"));
}

フォルダへのドキュメントのアップロード

フォルダ内にドキュメントを作成するのと同様に、既存のドキュメント、プレゼンテーション、スプレッドシートを 対象(転送先)フォルダの URL を受け入れる為に(上記で定義した) uploadFile() メソッド をオーバーロードすることによってフォルダへアップロードすることが出来ます。 folderEntryはアップロードしたいフォルダを表す有効な DocumentListEntry オブジェクトと仮定します。
String destFolderUrl = ((MediaContent) folderEntry.getContent()).getUri();
DocumentListEntry uploadedEntry = uploadFile("/path/to/your/file.doc", "TitleToUse", destFolderUrl);
System.out.println("Document now online in folder '" +
    folderEntry
.getTitle().getPlainText() + "' @ :" + uploadedEntry.getDocumentLink().getHref());
// URL引数によって指定した特定のフォルダにファイルをアップロード
public DocumentListEntry uploadFile(String filepath, String title, URL uri)
   
throws IOException, ServiceException  {
 
File file = new File(filepath);
 
DocumentListEntry newDocument = new DocumentListEntry();
 
String mimeType = DocumentListEntry.MediaType.fromFileName(file.getName()).getMimeType();
  newDocument
.setFile(new File(filepath), mimeType);
  newDocument
.setTitle(new PlainTextConstruct(title));

 
return client.insert(uri, newDocument);
}
// ルートドキュメントリストへファイルをアップロード
public DocumentListEntry uploadFile(String filepath, String title)
   
throws IOException, ServiceException  {
 
return uploadFile(filepath, title, new URL("https://docs.google.com/feeds/default/private/full/"));
}





  ドキュメントの更新


ドキュメントの更新は他のクライアント変更を上書きしていないことを確認するためにETagの使用を必要とします。 documentEntry.getEtag().を呼び出すことによってエントリのETagは取得出来ます。
Note:最後にドキュメントを取得して以来、誰かがそれを更新したかどうかに関わらずゴミ箱に入れたい場合はエントリのETagの値に"*"を用いてください。エントリを無条件で削除します。
ETagについてより詳しい情報はGoogle Data APIs reference guideを見てください。

メタデータの更新

ここにドキュメントの内容は変更せずにメタデータを更新する例があります。ドキュメントの名前は’Updated Title’に変更されます。entry内の DocumentListEntry を既に取得していると仮定しています。
entry.setTitle(new PlainTextConstruct("Updated Title"));
DocumentListEntry updatedEntry = entry.update();
// 代わりに DocsService オブジェクトの update()メソッドを使うこともできます。:
// DocumentListEntry updatedEntry = client.update(new URL(entry.getEditLink().getHref()), entry, entry.getEtag());
System.out.println(updatedEntry.getTitle().getPlainText());
更新に成功すると、サーバはHTTP 200 OK ステータスコードと更新したエントリのコピーを返します。指定ETagがそのエントリの現在のETagに一致しないために更新に失敗した場合(最後にエントリを取得してからサーバ上で変更されたことを意味します)、サーバはHTTP 412 Precondition Failed ステイタスコードを返します。その場合は、サーバから最新のエントリを取得し、修正を加えた後で再び更新を試みるべきです。

ドキュメント内容の置き換え

ドキュメントの内容を更新するために、DocumentListEntryupdateMedia() メソッドを使います。次の例は“updated content”のドキュメントの内容に置換えます。entryを既に取得していると仮定しています。
entry.setMediaSource(new MediaByteArraySource("updated content".getBytes(), "text/plain"));
DocumentListEntry updatedEntry = entry.updateMedia(true);

ドキュメント内容とメタデータの更新

ドキュメントの内容とメタデータを同時に更新するために前の例のようにDocumentListEntryupdateMedia()メソッドを使いますが、さらにエントリ自身も更新します。
次の例はnewer_data.docの内容とドキュメントの内容を置換え、ドキュメントのタイトルを‘Newer Title’へ変更し、さらに共同者が他の人とドキュメントを共有するのを妨げます。 entryを既に取得していると仮定しています。
File file = new File("/path/to/file/newer_data.doc");
String mimeType = DocumentListEntry.MediaType.fromFileName(file.getName()).getMimeType();
entry
.setMediaSource(new MediaFileSource(file, mimeType));
entry
.setTitle(new PlainTextConstruct("Newer Title"));
entry
.setWritersCanInvite(false);
DocumentListEntry updatedEntry = entry.updateMedia(true);

Google Documents List Data API v3.0 – (3)


Google Documents List Data API v3.0 – (1)

Java Language Guide (v3.0) -(3)

   ドキュメントとフォルダの削除

ドキュメントまたはフォルダをゴミ箱に入れる/削除するには他のクライアント変更を上書きしていないことを確認するためにETagの使用を必要とします。documentEntry.getEtag().を呼び出すことによってエントリのETagは取得出来ます。
Note:最後にドキュメントを取得して以来、誰かがそれを更新したかどうかに関わらずゴミ箱に入れたい場合はエントリのETagの値に"*"を用いてください。エントリを無条件で削除します。
ETagについてより詳しい情報はGoogle Data APIs reference guideを見てください。


ドキュメントまたはフォルダをゴミ箱に入れる
ドキュメントを捨てるとドキュメントをゴミ箱に移動します。取得したDocumentListEntryオブジェクトでdelete() メソッドを呼び出せます:
entry.delete()
代わりに、サービスオブジェクトのdeleteメソッドを呼び出し、エントリの編集リンクとETagを渡すことが出来ます:
client.delete(new URL(entry.getEditLink().getHref()), entry.getEtag());
最後に、DocumentListEntry オブジェクトとしてエントリを持っていない場合、リソースidを使用して手動で編集リンクを構築します:
client.delete(new URL("https://docs.google.com/feeds/default/private/full/RESOURCE_ID"), "*");
削除に成功すると、サーバはHTTP 200 OK ステータスコードを返します。指定ETagがそのエントリの現在のETagに一致しないために削除に失敗した場合(最後にエントリを取得してからサーバ上で変更されたことを意味します)、サーバはHTTP 412 Precondition Failed ステイタスコードを返します。その場合は、サーバから最新のエントリを取得し、修正を加えた後で再び更新を試みるべきです。

ドキュメントまたはフォルダの削除
ドキュメントまたはフォルダを削除するとユーザーのドキュメントリストからオブジェクトを永久に除去します。ドキュメントを削除するプロセスはドキュメントを捨てる(ゴミ箱に入れる)のと同様で、 delete=true パラメータを含みます。URLで引数を渡すために DocsServiceオブジェクトのdelete() メソッドを使います:
client.delete(new URL(entry.getEditLink().getHref() + "?delete=true"), entry.getEtag());

  ドキュメントのダウンロードとエクスポート

ドキュメントリストフィードからドキュメントをエクスポートするためには、ドキュメントのAtomエントリ、またはドキュメント、スプレッドシート、プレゼンテーションのidが必要です。(例えばスプレッドシート:12345) 各タイプのドキュメントは有効なエクスポート形式のセットをもっていることに注意してください。
重要: 全てのタイプのドキュメントをダウンロードするのに同じOAuth/AuthSubトークンを使いたい場合は、 docs.google.comspreadsheets.google.com, anddocs.googleusercontent.comに有効なマルチスコープトークンをリクエストします。例えばAuthSub/OAuthのスコープパラメータは以下のようになります: scope=https://docs.google.com/feeds/ http://spreadsheets.google.com/feeds/ http://docs.googleusercontent.com/.
このセクションの例は次のdownloadFile() ヘルパーを再利用します。これはローカルディスクにファイルをダウンロードします:
public void downloadFile(String exportUrl, String filepath)
   
throws IOException, MalformedURLException, ServiceException {
 
System.out.println("Exporting document from: " + exportUrl);

 
MediaContent mc = new MediaContent();
  mc
.setUri(exportUrl);
 
MediaSource ms = client.getMedia(mc);

 
InputStream inStream = null;
 
FileOutputStream outStream = null;

 
try {
    inStream
= ms.getInputStream();
    outStream
= new FileOutputStream(filepath);

   
int c;
   
while ((c = inStream.read()) != -1) {
      outStream
.write(c);
   
}
 
} finally {
   
if (inStream != null) {
      inStream
.close();
   
}
   
if (outStream != null) {
      outStream
.flush();
      outStream
.close();
   
}
 
}
}

 ワードプロセッサ文書のエクスポート

次の例はユーザーのドキュメントリストの最初にあるドキュメントを取得し、.docファイルとしてDocumentListEntry オブジェクトをエクスポートします。exportFormatはセーブするファイルの拡張子から推定されることに注意してください。このケースだと.docです。 更にドキュメントのリソースIDを取り、手動でエクスポートURLを構築する上記のヘルパーが要ります。
URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full/-/document?max-results=1");
List<DocumentListEntry> entries  = client.getFeed(feedUrl, DocumentListFeed.class).getEntries();

downloadDocument
(entries.get(0), "/path/to/export/to/myDoc.doc");
// または
// downloadDocument("document:dfrkj84g_9128gtvh8nt", "/path/to/export/to/myDoc.doc");
public void downloadDocument(String resourceId, String filepath)
   
throws IOException, MalformedURLException, ServiceException {
 
String docId = resourceId.substring(resourceId.lastIndexOf(":") + 1);
 
String fileExtension = filepath.substring(filepath.lastIndexOf(".") + 1);
 
String exportUrl = "https://docs.google.com/feeds/download/documents/Export?docId=" +
      docId
+ "&exportFormat;=" + fileExtension;
  downloadFile
(exportUrl, filepath);
}
public void downloadDocument(DocumentListEntry entry, String filepath)
   
throws IOException, MalformedURLException, ServiceException {
 
String fileExtension = filepath.substring(filepath.lastIndexOf(".") + 1);
 
String exportUrl = ((MediaContent) entry.getContent()).getUri() + "&exportFormat;=" + fileExtension;
  downloadFile
(exportUrl, filepath);
}

 プレゼンテーションのエクスポート

同じ考え方がプレゼンテーションのエクスポートに適用出来ます。次の例はユーザーのドキュメントリストの最初にあるプレゼンテーションを取得し、.pdfファイルとして DocumentListEntryをエクスポートします。  更にプレゼンテーションのリソースIDを取り、手動でエクスポートURLを構築する上記のヘルパーが要ります。
URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full/-/presentation?max-results=1");
List<DocumentListEntry> entries  = client.getFeed(feedUrl, DocumentListFeed.class).getEntries();

downloadPresentation
(entries.get(0), "/path/to/export/to/myPresentation.pdf");
// または
// downloadPresentation("presentation:dfrkj84g_9128gtvh8nt", "/path/to/export/to/myPresentation.pdf");
public void downloadPresentation(String resourceId, String filepath)
   
throws IOException, MalformedURLException, ServiceException {
 
String docId = resourceId.substring(resourceId.lastIndexOf(":") + 1);
 
String fileExtension = filepath.substring(filepath.lastIndexOf(".") + 1);
 
String exportUrl = "https://docs.google.com/feeds/download/presentations/Export?docId=" +
      docId
+ "&exportFormat;=" + fileExtension;
  downloadFile
(exportUrl, filepath);
}
public void downloadPresentation(DocumentListEntry entry, String filepath)
   
throws IOException, MalformedURLException, ServiceException {
 
String fileExtension = filepath.substring(filepath.lastIndexOf(".") + 1);
 
String exportUrl = ((MediaContent) entry.getContent()).getUri() + "&exportFormat;=" + fileExtension;
  downloadFile
(exportUrl, filepath);
}

 スプレッドシートのエクスポート

重要: スプレッドシートをダウンロードするために、クライアントソフトはスプレッドシートAPIで有効なトークンを必要とします。より詳しい情報はdownloading spreadsheets using AuthSub/OAuthdownloading spreadsheets using ClientLoginを見てください。
同じ考え方がスプレッドシートのエクスポートに適用出来ます。次の例はユーザーのドキュメントリストの最初にあるスプレッドシートを取得し、.csvファイルとして DocumentListEntryをエクスポートします。  更にスプレッドシートのリソースIDを取り、手動でエクスポートURLを構築する上記のヘルパーが要ります。
(※原文だとpresentations’s resource IDですがコピペして修正し忘れているのかどうか不明です。ここでは“スプレッドシート”と訳しています) 
URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full/-/spreadsheet?max-results=1");
List<DocumentListEntry> entries  = client.getFeed(feedUrl, DocumentListFeed.class).getEntries();

downloadSpreadsheet
(entries.get(0), "/path/to/export/to/mySpreadsheet.csv");
// または
// downloadSpreadsheet("spreadsheet:dfrkj84g_9128gtvh8nt", "/path/to/export/to/mySpreadsheet.csv");
public void downloadSpreadsheet(String resourceId, String filepath)
   
throws IOException, MalformedURLException, ServiceException {
 
String docId = resourceId.substring(resourceId.lastIndexOf(":") + 1);
 
String fileExtension = filepath.substring(filepath.lastIndexOf(".") + 1);
 
String exportUrl = "https://spreadsheets.google.com/feeds/download/spreadsheets" +
     
"/Export?key=" + docId + "&exportFormat;=" + fileExtension;

 
//.csv または.tsvへエクスポートする場合,どのシートにエクスポートするか指定するgidパラメータを追加します
 
if (fileExtension.equals("csv") || fileExtension.equals("tsv")) {
    exportUrl
+= "&gid;=0";  // gid=0 の場合、最初のシートのみがダウンロードされます
 
}

  downloadFile
(exportUrl, filepath);
}
public void downloadSpreadsheet(DocumentListEntry entry, String filepath)
   
throws IOException, MalformedURLException, ServiceException {
 
String fileExtension = filepath.substring(filepath.lastIndexOf(".") + 1);
 
String exportUrl = ((MediaContent) entry.getContent()).getUri() + "&exportFormat;=" + fileExtension;

 
//.csv または.tsvへエクスポートする場合,どのシートにエクスポートするか指定するgidパラメータを追加します
 
if (fileExtension.equals("csv") || fileExtension.equals("tsv")) {
    exportUrl
+= "&gid;=0";  // gid=0 の場合、最初のシートのみがダウンロードされます
 
}

  downloadFile
(exportUrl, filepath);
}

 AuthSub/OAuth を使用したスプレッドシートのエクスポート

スプレッドシートをダウンロードするのに同じOAuth/AuthSubトークンを使いたい場合は、 docs.google.comspreadsheets.google.com, anddocs.googleusercontent.comに有効なマルチスコープトークンをリクエストします。
例えばAuthSubUtil.getRequestUrl()以下のような形で渡します:
String scope = "https://docs.google.com/feeds/ https://spreadsheets.google.com/feeds/"  
そうすれば上記の例はそのまま動きます。

  ClientLoginを使用したスプレッドシートのエクスポート
ClientLoginでは,プロセスは多少複雑です。最初に (スプレッドシートトークンを取得する為の)SpreadsheetsService オブジェクトを作成し、それから DocsService オブジェクトへトークンを交換します? この例はこのプロセスを説明します:
import com.google.gdata.client.spreadsheet.SpreadsheetService;
// authトークンを取得する為にスプレッドシートAPIに対して認証します
SpreadsheetService spread_client = new SpreadsheetService("yourCo-yourAppName-v1");
spread_client
.setUserCredentials("example@gmail.com", "pa$$word");
//スプレッドシートトークンを ドキュメントトークンの代わりに使用します
UserToken docsToken = (UserToken) client.getAuthTokenFactory().getAuthToken();
UserToken spreadsheetsToken = (UserToken) spread_client.getAuthTokenFactory().getAuthToken();
client
.setUserToken(spreadsheetsToken.getValue());

downloadSpreadsheet
(entry, "/path/to/export/to/spreadsheet.xls");
// ドキュメントリストクライアントへドキュメントトークンを戻します
client
.setUserToken(docsToken.getValue());

 PDFファイルのダウンロード

ネイティブPDFファイルは.pdf以外のフォーマットでエクスポートすることは出来ません。更にこのタイプのファイル用のダウンロードURLを手動で構築することは出来ません。代わりにDocumentListEntryタグのsrcリンクへ認証済みHTTP GET を送信します:
URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full/-/pdf?max-results=1");
List<DocumentListEntry> entries  = client.getFeed(feedUrl, DocumentListFeed.class).getEntries();

downloadPDF
(entries.get(0), "/path/to/export/to/myPDF.pdf");
// または
// downloadPDF("pdf:dfrkj84g_9128gtvh8nt", "/path/to/export/to/my_pdf_file.pdf");
public void downloadPDF(DocumentListEntry entry, String filepath)
   
throws MalformedURLException, IOException, ServiceException {
 
MediaContent mc = (MediaContent) entry.getContent();
 
String fileExtension = mc.getMimeType().getSubType();
 
String exportUrl = mc.getUri();

 
// PDF ファイルは異なる形式でエクスポートすることは出来ません
 
String requestedExtension = filepath.substring(filepath.lastIndexOf(".") + 1);
 
if (!requestedExtension.equals(fileExtension)) {
   
System.err.println("Warning: " + mc.getMimeType().getMediaType() +
       
" cannot be downloaded as a " + requestedExtension + ". Using ." +
        fileExtension
+ " instead.");
    filepath
= filepath.substring(0, filepath.lastIndexOf(".") + 1) + fileExtension;
 
}

  downloadFile
(exportUrl, filepath);
}
public void downloadPDF(String resourceId, String filepath)
   
throws MalformedURLException, IOException, ServiceException {
 
// 最初に,リソースIdを使用してエントリを取得します
  URL url
= new URL("https://docs.google.com/feeds/default/private/full/" + resourceId);
 
DocumentListEntry entry = client.getEntry(url, DocumentListEntry.class);
  downloadPDF
(entry, filepath);
}
注意: PDFをダウンロードする時に使用するサーバはhttps://docs.googleusercontent.comです。したがって必ず https://docs.googleusercontent.comでも有効な複数スコープのAuthSub/OAuth トークンをリクエストします。  Downloading Documents セクションのメモを見てください。ClientLoginのために特別にすべきことはありません。

 フォルダ管理

フォルダの作成

サブフォルダの作成はフォルダ内での空のドキュメントの作成と似ています。 FolderEntryを受けいれられるように createNewDocument() メソッド (上記のオーバーロードバージョンを修正します。
DocumentListEntry folderEntry = createFolder("New Folder");
public DocumentListEntry createFolder(String title) throws IOException, ServiceException {
 
DocumentListEntry newEntry = new FolderEntry();
  newEntry
.setTitle(new PlainTextConstruct(title));
  URL feedUrl
= new URL("https://docs.google.com/feeds/default/private/full/");
 
return client.insert(feedUrl, newEntry);
}

ドキュメントとフォルダの移動

親フォルダにドキュメントまたはフォルダを移動するにはソース用とドキュメントの移動先用の
DocumentListEntry オブジェクトが必要です。それからソースドキュメント/フォルダのIDをそのAtom   にセットした新しいエントリを作成します。最後にHTTP  POST をフォルダエントリコンテントsrcリンクへ送信します。 (※文脈からUltimatelyとthenを入れ替えて訳しました)

例は次のようになります:

フォルダへのリソースの移動

public DocumentListEntry moveToFolder(DocumentListEntry sourceEntry, DocumentListEntry destFolderEntry)
   
throws IOException, MalformedURLException, ServiceException {

 
DocumentListEntry newEntry = null;

 
String docType = sourceEntry.getType();
 
if (docType.equals("document")) {
    newEntry
= new DocumentEntry();
 
} else if (docType.equals("presentation")) {
    newEntry
= new PresentationEntry();
 
} else if (docType.equals("spreadsheet")) {
    newEntry
= new SpreadsheetEntry();
 
} else if (docType.equals("folder")) {
    newEntry
= new FolderEntry();
 
} else if (docType.equals("pdf")) {
    newEntry
= new PdfEntry();
 
} else {
    newEntry
= new DocumentListEntry(); // 未知のタイプ
 
}
  newEntry
.setId(sourceEntry.getId());

 
String destFolderUri = ((MediaContent) destFolderEntry.getContent()).getUri();

 
return client.insert(new URL(destFolderUri), newEntry);
}

フォルダからのリソースの移動

親フォルダの外へのフォルダまたはドキュメントの移動はソースフォルダエントリのeditリンク上で delete() を実行し、ドキュメントのリソースIDを追加することで出来ます。 documentEntry と parentFolderEntry はそれぞれソースエントリを表す DocumentListEntryオブジェクト(即ち、フォルダから除去されるもの)とドキュメントを除去するフォルダと仮定しています。
moveOutOfFolder(documentEntry, parentFolderEntry);
public void moveOutOfFolder(DocumentListEntry sourceEntry, DocumentListEntry parentFolderEntry)
   
throws IOException, MalformedURLException, ServiceException {
 
String folderContentUri = ((MediaContent) parentFolderEntry.getContent()).getUri();
  client
.delete(new URL(folderContentUri + "/" + sourceEntry.getResourceId()), sourceEntry.getEtag());
}

  フォルダ共有設定の変更

ACLフィードの取得

ドキュメントまたはフォルダのACLパーミッションを取得するには、Atomエントリからのエントリの が必要です? DocumentListEntry はこの値を見つけるためのgetAclFeedLink()メソッドを持っています。
次の例はログインしたユーザーが所有する最初のドキュメントを取得、そのACLフィードを抽出、パーミッションエントリの出力をします:
DocumentQuery query = new DocumentQuery(new URL("https://docs.google.com/feeds/default/private/full/-/mine"));
DocumentListFeed resultFeed = client.getFeed(query, DocumentListFeed.class);
DocumentListEntry entry = resultFeed.getEntries().get(0);
AclFeed aclFeed = client.getFeed(new URL(entry.getAclFeedLink().getHref()), AclFeed.class);
for (AclEntry aclentry : aclFeed.getEntries()) {
 
System.out.println(
      
aclentry.getScope().getValue() + " (" + aclentry.getScope().getType() + ") : " + aclentry.getRole().getValue());
}

aclentryと言った感じでリネームしないと重複でエラーになります。

 ドキュメントのACLフィードの変更

 新しいパーミッションの追加

ドキュメントまたはフォルダに新しいパーミッションを追加するには、クライアントソフトは新しいAclEntry を作成し、それをサーバにPOSTする必要があります。
以下は entry(DocumentListEntry)オブジェクトによって表されるドキュメント/フォルダへ‘user@example.com’をreader として追加する例です :
AclRole role = new AclRole("reader");
AclScope scope = new AclScope(AclScope.Type.USER, "user@example.com");
AclEntry aclEntry = addAclRole(role, scope, entry);
public AclEntry addAclRole(AclRole role, AclScope scope, DocumentListEntry entry)
   
throws IOException, MalformedURLException, ServiceException  {
 
AclEntry aclEntry = new AclEntry();
  aclEntry
.setRole(role);
  aclEntry
.setScope(scope);

 
return client.insert(new URL(entry.getAclFeedLink().getHref()), aclEntry);
}
AclRoleで使用出来る値はreaderwriterownerです。

 グループとドメインレベルでの共有

sharing with a single userと同様に、あなたがGoogle Appsドメインを持っている場合、グループまたはドメイン中でドキュメントまたはフォルダを共有出来ます。
GoogleAppsドメイン全体でドキュメントまたはフォルダを共用するには、以下のようにAclScopeをセットします:
AclScope scope = new AclScope(AclScope.Type.DOMAIN, "example.com");
Note: ドメインがそのようなパーミッション(例えば、Google Apps ドメインのドメイン外共有が有効、など)を許す設定の場合でのみ、共有ACLは可能です? 
Googleメーリングリストでドキュメントまたはフォルダを共有するには、以下のようにAclScopeをセットします:
AclScope scope = new AclScope(AclScope.Type.GROUP, "mailing_list@example.com");

 共有パーミッションの更新

既存のACLパーミッションをその対象となるaclエントリのeditリンクへPUTリクエスト(と更新した内容の実体)を送信することで更新できます。
この例は‘user@example.com’をwriter(共同者)に更新することによって以前のaclEntry変更します:
aclEntry.setRole(new AclRole("writer"));
AclEntry updatedAclEntry = aclEntry.update();
//clientオブジェクトのupdateメソッドを使うことも出来ます
// client.update(new URL(aclEntry.getEditLink().getHref()), aclEntry);

 共有パーミッションの除去

パーミッションの削除はACLエントリの editリンクへ DELETE を送る必要があります。
aclEntry.delete();
// clientオブジェクトのdeleteメソッドを使うことも出来ます
// client.delete(new URL(aclEntry.getEditLink().getHref()), aclEntry);

  ドキュメントリビジョン(改訂)

ドキュメントの改訂(履歴?)の取得

ドキュメントリビジョンはRevisionFeedRevisionEntryクラス経由で利用可能です。ACL用の タグと同様に、ドキュメントエントリはリビジョンフィードを指し示すタグを持ちます。ドキュメントの改訂履歴を取得するには、リビジョンフィードへHTTP GETを送信します。この例はentry 内のDocumentListEntry オブジェクトの改訂履歴を取得し、そのフィードについて幾つかの情報を出力します:
RevisionFeed revisionFeed = getRevisionsFeed(entry);
// または
// RevisionFeed revisionFeed = getRevisionsFeed("document:12345");
for (RevisionEntry revisionEntry : revisionFeed.getEntries()) {
  printRevisionEntry
(revisionEntry);
}
public RevisionFeed getRevisionsFeed(String resourceId) throws IOException,
   
MalformedURLException, ServiceException {
  URL url
= new URL("https://docs.google.com/feeds/default/private/full/" + resourceId + "/revisions");
 
return client.getFeed(url, RevisionFeed.class);
}
public RevisionFeed getRevisionsFeed(DocumentListEntry entry) throws IOException,
   
MalformedURLException, ServiceException {
  URL url
= new URL(entry.getSelfLink().getHref() + "/revisions");
 
return client.getFeed(url, RevisionFeed.class);
}
public void printRevisionEntry(RevisionEntry entry) {
 
StringBuffer output = new StringBuffer();
//※下2つはnullチェックをしないとエラーが発生する可能性があります。
  output
.append(" -- " + entry.getTitle().getPlainText());
  output
.append(", created on " + entry.getUpdated().toUiString() + " ");
  output
.append(" by " + entry.getModifyingUser().getName() + " - "
     
+ entry.getModifyingUser().getEmail() + "n");
  output
.append("    " + entry.getHtmlLink().getHref());

 
System.out.println(output);
}
RevisionEntry:のプロパティ;
  • RevisionEntry.getUpdated() はリビジョンが作成されたタイムスタンプ(時刻)です。
  • RevisionEntry.getModifyingUser() はそのリビジョンの作成者です。
Note: ドキュメントとプレゼンテーションのリビジョンが自動インクリメントリビジョンナンバーを持つ間は、リビジョンがシーケンシャルなシークエンスによらずに削除されるとこれらはギャップを持つかもしれません? スプレッドシートのリビジョンはほとんど同一に見えますが、リビジョンidsはゼロベースでも自動インクリメントでもありません-代わりにリビジョンのタイムスタンプベースで、ランダムに見える数の連なりになるでしょう?

リビジョンのダウンロード

ドキュメントのダウンロードと同様に、ここのリビジョンをダウンロードし、 exportFormatを指定することが出来ます。(※andが余計?) この例ではrevisionEntryとしてRevisionEntryオブジェクトを既に持っていると仮定します。さらに downloadFile()helperを再利用します (from above).
downloadRevision(revisionEntry, "/path/to/export/to/myDocument.pdf");
public void downloadRevision(RevisionEntry entry, String filepath)
   
throws IOException, MalformedURLException, ServiceException {
 
String fileExtension = filepath.substring(filepath.lastIndexOf(".") + 1);
 
String exportUrl = ((OutOfLineContent) entry.getContent()).getUri() + "&exportFormat;=" + fileExtension;
  downloadFile
(exportUrl, filepath);
}
Note: 適切なサービスに有効なAuthSub/OAuth、またはClientLoginトークンが必要となります?
downloading documentsを見てください。(※validが一つ余計?)