月別: 2011年2月

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

http://code.google.com/intl/ja/apis/documents/docs/3.0/developers_guide_java.html

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

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

ドキュメントリストデータAPIの機能の背景の提供に加えて、このガイドは Java client libraryを使用してAPIと対話する例を提供します。クライアントライブラリのセットアップのヘルプについてはGetting Started with the Google Data Java Client Libraryを見てください。ドキュメントと対話する為のJava クライアントライブラリによって使用される根本的なプロトコルについてより理解することに興味がある場合はprotocol guideを見てください。
重要: Google ドキュメンドリストデータ API v3.0はLabs段階です。 この機能は正式公開までに予期せぬ変更があるかもしれません。バージョン2.0が最新のグラデュエイティッドバージョン(正式公開バージョン?)です。
    1. Audience
    2. Getting Started

 対象読者

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

 はじめに

Googleドキュメントは認証にGoogleアカウントを使用するので、Googleアカウントを持っている場合は準備完了です。そうでない場合はアカウントを作成することが出来ます。

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

クライアントライブラリのインストールとセットアップのヘルプについては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(ライブラリ)をインストールした後、始めるために必要なクラスをjava/lib/gdata-document-3.0.jar と java/lib/gdata-client-1.0.jarのjarファイル内にクラスを見つけるでしょう。 ドキュメントリストAPIはさらにMediaServiceを継承しているので、上記の依存ライブラリリストの java/lib/gdata-media-1.0.jarとJavaMail( mail.jar ) を含む必要があります。

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

  • 完全に動作するサンプルアプリケーション—ダウンロードした gdata-samples.java.zip 内のサブディレクトリにあります。 
  • Javaソース—/trunk/java/sample/docs/DocumentListDemo.java (ソースタブからアクセス出来るSVNリポジトリ). このソースで、ドキュメントリストフィードをどのように使用するかを説明する操作の数を調べることが出来ます。.

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

Tip: Eclipseプラグインを簡単にセットアップするにはUsing Eclipse with Google Data APIs の記事を見てください。
最初に幾つかのインポートが必要です。(作成するアプリケーションの要求によります)  推奨は以下の通りです:
import com.google.gdata.client.*;
import com.google.gdata.client.docs.*;
import com.google.gdata.data.MediaContent;
import com.google.gdata.data.acl.*;
import com.google.gdata.data.docs.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;



次に、DocsService オブジェクトをセットアップします。このオブジェクトはドキュメントリストAPIへの(認証を伴った)クライアント接続を表します:

DocsService client = new DocsService("yourCo-yourAppName-v1");

applicationName 引数はcompany-applicationname-versionというフォーマットに従わなければなりません。このパラメータはロギング目的で使用されます。

注意: 以降のガイドは clientという変数名のDocsService オブジェクトを作成しているという前提で進めます

 ドキュメントリストAPIへの認証

Javaクライアントライブラリはパブリックかまたはプライベートのフィードで動作させることが可能です。ドキュメントリストデータAPIはドキュメントサーバでの認証を要求するプライベートフィードへのアクセスを提供します。これはClientLogin のユーザーネーム/パスワード認証、AuthSub、または OAuth経由で行うことが可能です。
アプリケーションに使用する必要がある認可の種類がわからない場合は アカウントドキュメンテーション内の Getting Started with Account Authorization を見てください。

※原文に変更あり? 認証方法の説明でOAuthが上に来て、
「This process is shown in the following diagram:(このプロセスは以下の図において示されます:)」という一文が追加された?
特に致命的な変更ではないので取り敢えず放置しておきます。

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

AuthSubはwebベースのアプリケーションで使用されるグーグル独自の認証プロトコルです。webベースアプリケーションがGoogleアカウントによって保護されているユーザーのデータへアクセスしなければならない時、AuthSubが使用されます。どのようにAuthSubが動くかやプロジェクトにAuthSubをセットアップする方法を学ぶには AuthSub for Web Applications ガイド内のWorking with AuthSubを見てください。
ユーザーが初めてアプリケーションを訪れた時、アプリケーションがユーザー自身のGoogleデータへアクセスすることを承諾する必要があります。これを達成する為に、アプリケーションは最初にsingle-use tokenを取得しなければなりません。これはユーザーのログインクレデンシャル(ユーザーネーム/パスワード)をさらすことなくアプリにユーザーデータへのアクセスを承諾します。一般的に、ユーザーは自身のGoogleアカウントを使用して認証(ログイン)するようユーザー達に指示する何らかのテキストとリンクまたはボタンを見るでしょう。 ユーザーがアクセスを承諾した後、ユーザーはドキュメントリストデータAPIフィードからデータを取得することが出来るURLを指示されます。
WebアプリケーションでAuthSubを使用するためには、最初single-use tokenをリクエストします (説明を見てください)

AuthSub認証を使用してsingle-use tokenを取得する為に、Googleデータ Java クライアントライブラリによって提供されている getRequestUrl() メソッドを使用します。
import com.google.gdata.client.*;
String nextUrl = "http://www.example.com/welcome.jsp";
String scope = "https://docs.google.com/feeds/";
boolean secure = false;  // set secure=true to request secure AuthSub tokens
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://docs.google.com/feeds/";
boolean secure = false;  // set secure=true to request AuthSub tokens
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);
getRequestUrl()メソッドは幾つかのパラメータを取ります。これらのパラメータはAuthSubRequest ドキュメントで詳細に記述されています。 single-use tokenを取得する方法を理解したら、以下のやり方も読解出来ます?:

OAuth

OAuthはweb、モバイル、デスクトップアプリケーション向けに考えられたオープン標準な認証プロトコルです。OAuthプロトコルは、全てのデータリクエストは電子署名されていて、あなたがあなたのドメインを登録していなければいけない点においてAuthSubの secure and registered モード に似ています?
AuthSub認証と同様に、初めてのユーザーは アプリケーションによる自身のGoogleデータへのアクセスを承諾する必要があります。 一般的にユーザーは自身のGoogleアカウントを使用して認証(ログイン)するようユーザー達に指示する何らかのテキストとリンクまたはボタンを見るでしょう。ユーザーがアクセスを承諾した後、ユーザーはドキュメントリストデータAPIフィードからデータを取得することが出来るURLを指示されます。
webベースのアプリケーションでOAuthを使う為にこの順番に従って処理してください。それぞれの処理はあなたが使用することが出来る関連したコードサンプルが以下にあります:
  1. リクエストトークンの取得
  2. リクエストトークンの認可
  3. アクセストークンへの交換
  4. サービスを対話する為のアクセストークンの使用

デスクトップ/モバイルアプリケーション向けClientLogin

ClientLogin はユーザーをGoogleアカウントへ認証することを必要とするデスクトップまたはモバイルアプリケーションで使われるべきです。アプリケーションの初回起動時、username/passwordの入力をユーザーに促します。 以降の使用ではユーザーを認証する為にこの認証トークンを使います。
説明

ClientLoginを使う為に DocsService オブジェクトのsetUserCredentials() メソッドを実行しします。 DocsService オブジェクトはGoogleServiceを継承しています。 ユーザーの代わりにリクエストを作成しているクライアントにeメールアドレスとパスワードを指定してください? 例えば:
DocsService client = new DocsService("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を見てください。

 ドキュメントのリストの取得

ログインしたユーザーの全てのドキュメントのリストを取得する為に以下のURLへ認証済みGETリクエストを使用します :
https://docs.google.com/feeds/default/private/full


結果は DocumentListFeed オブジェクトで、とりわけ DocumentListEntry オブジェクトのリストを含みます?
 (feed.getEntries()(で取得出来るGDataエントリは?) それぞれ以下のようなオブジェクトを表しています:
  • スプレッドシート
  • プレゼンテーション
  • ワードプロセッサ文書
  • PDF
  • 任意のファイル
  • フォルダ
DocumentListEntrythe protocol documentで示される情報をカプセル化しています。
以下の例はドキュメントのリストを取得する色々な方法を例証します。例の多くは スプレッドシートのリストまたはフォルダのリストというようなタイプによって制限されたドキュメントのリストを返すためにカテゴリを使っています。それぞれ、以下のコードはフィードの結果をコマンドラインに出力します。
public void printDocuments(DocumentListFeed feed) {
 
for (DocumentListEntry entry : feed.getEntries()) {
   
String resourceId = entry.getResourceId();
   
System.out.println(" -- Document(" + resourceId + "/" + entry.getTitle().getPlainText() + ")");
 
}
}


例:全てのドキュメントの一覧(リスト)を出力する:



この広範囲に渡る例は現在ログインしているユーザーが利用可能な全てのドキュメントをリストにします。 これをするにはカテゴリの無いベースフィードクエリを使用します。

public void showAllDocs() throws IOException, ServiceException {
  URL feedUri
= new URL("https://docs.google.com/feeds/default/private/full/");
 
DocumentListFeed feed = client.getFeed(feedUri, DocumentListFeed.class);

 
for (DocumentListEntry entry : feed.getEntries()) {
    printEntry
(entry);
 
}
}
public void printEntry(DocumentListEntry entry) {
 
String resourceId = entry.getResourceId();
 
String docType = entry.getType();

 
System.out.println("'" + entry.getTitle().getPlainText() + "' (" + docType + ")");
 
System.out.println("  link to Google Docs: " + entry.getDocumentLink().getHref());
 
System.out.println("  resource id: " + resourceId);
 
System.out.println("  doc id: " + entry.getDocId());//<--- add ")"

 
// print the parent folder the document is in
 
if (!entry.getParentLinks().isEmpty()) {
   
System.out.println("  Parent folders: ");
   
for (Link link : entry.getParentLinks()) {
     
System.out.println("    --" + link.getTitle() + " - " + link.getHref());
   
}
 
}

 
// print the timestamp the document was last viewed
 
DateTime lastViewed = entry.getLastViewed();
 
if (lastViewed != null) {
   
System.out.println("  last viewed: " + lastViewed.toUiString());
 
}

 
// print who made the last modification
 
LastModifiedBy lastModifiedBy = entry.getLastModifiedBy();
 
if (lastModifiedBy != null) {
   
System.out.println("  updated by: " +
        lastModifiedBy
.getName() + " - " + lastModifiedBy.getEmail());
 
}

 
// Files such as PDFs take up quota
 
if (entry.getQuotaBytesUsed() > 0) {
   
System.out.println("Quota used: " + entry.getQuotaBytesUsed() + " bytes");
 
}

 
// print other useful metadata
 
System.out.println("  last updated: " + entry.getUpdated().toUiString());
 
System.out.println("  viewed by user? " + entry.isViewed());
 
System.out.println("  writersCanInvite? " + entry.isWritersCanInvite().toString());
 
System.out.println("  hidden? " + entry.isHidden());
 
System.out.println("  starred? " + entry.isStarred());
 
System.out.println("  trashed? " + entry.isTrashed());
 
System.out.println();
}

ページ操作による結果選択

デフォルトでAPIはユーザーのドキュメントリストの内、最初の100件の文章を返します。これは帯域幅を節約しパフォーマンスを改善します。ユーザーのドキュメントの残りを取得する為には、 feed.getNextLink().getHref()に従ってページ操作する必要があります? この例はユーザー所有の完全なドキュメントリストを取得する方法を示しています:
DocumentQuery query = new DocumentQuery(new URL("https://docs.google.com/feeds/default/private/full"));
// Get Everything
DocumentListFeed allEntries = new DocumentListFeed();
DocumentListFeed tempFeed = client.getFeed(query, DocumentListFeed.class);
do {
    allEntries
.getEntries().addAll(tempFeed.getEntries());
    tempFeed
= client.getFeed(new URL(tempFeed.getNextLink().getHref()),DocumentListFeed.class);} while (tempFeed.getEntries().size() > 0);
System.out.println("User has " + allEntries.getEntries().size() + " total entrie s");
for (DocumentListEntry entry : allEntries.getEntries()) {
     printEntry
(entry);
}

※tempFeed.getNextLink()でnullが返された場合(データの終端で毎回?)、

tempFeed = client.getFeed(new URL(tempFeed.getNextLink().getHref()),DocumentListFeed.class);} 

の行でNullPointerExceptionが発生します。

if(tempFeed.getNextLink() == null){
     break;
}

みたいなコードを挿入するかwhile文の条件を変更する必要があると思います。


カテゴリ別リストの取得
以下の例はどのようにカテゴリによる様々な一覧(リスト)を取得出来るかを示します。全ての利用可能なリストについてはreference guideを見てください。

spreadsheet カテゴリを使用してスプレッドシートのみのリストを取得:
URL feedUri = new URL("https://docs.google.com/feeds/default/private/full/-/spreadsheet");
DocumentListFeed feed = client.getFeed(feedUri, DocumentListFeed.class);
printDocuments
(feed);
document カテゴリを使用してワードプロセッサ文書のみのリストを取得:
URL feedUri = new URL("https://docs.google.com/feeds/default/private/full/-/document");
DocumentListFeed feed = client.getFeed(feedUri, DocumentListFeed.class);
printDocuments
(feed);
presentation と mine カテゴリを使用してユーザーが所有するプレゼンテーションのみのリストを取得:
URL feedUri = new URL("https://docs.google.com/feeds/default/private/full/-/presentation/mine");
DocumentListFeed feed = client.getFeed(feedUri, DocumentListFeed.class);
printDocuments
(feed);
folder カテゴリを使用してフォルダのリストを取得:
URL feedUri = new URL("https://docs.google.com/feeds/default/private/full/-/folder");
DocumentListFeed feed = client.getFeed(feedUri, DocumentListFeed.class);
printDocuments
(feed);
trashed カテゴリを使用してゴミ箱内のオブジェクトのリストを取得:
URL feedUri = new URL("https://docs.google.com/feeds/default/private/full/-/trashed");
DocumentListFeed feed = client.getFeed(feedUri, DocumentListFeed.class);
printDocuments
(feed);
showdeleted パラメータを使用して通常のクエリ結果とゴミ箱内のオブジェクトのリストを表示:
URL feedUri = new URL("https://docs.google.com/feeds/default/private/full/?showdeleted=true");
DocumentListFeed feed = client.getFeed(feedUri, DocumentListFeed.class);
printDocuments
(feed);

ドキュメントリソースID

このガイドではしばしばドキュメントIDとドキュメントリソースIDという概念に言及しています。ドキュメントIDはいくつかの状況で使用されています。そのほとんどはドキュメントのエクスポートまたはIDによるエントリのクエリーです。
ドキュメントIDを取得するために、entry.getResourceId() を使用します(DocumentListEntry オブジェクトの子(メンバークラス)です). 各リソースIDはそのユニークIDとともにドキュメントタイプを含みます:

type:docID



entry.getDocId(),を使用することによってドキュメントIDを取得出来るけれども、このメソッドはオブジェクトタイプを返しません。 そういった理由からドキュメントのフルリソースIDを取得するentry.getResourceID() を使うことを推奨しています。自身でこのロジックを実装する必要がありません。

Java Task Queue Configuration

http://code.google.com/intl/en/appengine/docs/java/config/queue.html

 Java タスクキュー設定

アプリケーションが処理を実行する為にtask queues を使うつもりである場合、アプリは名前付きキューを定義するかデフォルトキュー用の設定をする為に設定ファイルを含むことが出来ます。Javaアプリでこのファイルはqueue.xmlと命名され、WAR内のWEB-INF/ ディレクトリに存在します。

 queue.xmlについて

JavaアプリはWAR内のアプリのWEB-INF/ ディレクトリにあるqueue.xmlを使用してタスキキューを定義出来ます。queue.xml がない場合、アプリは QueueFactory.getDefaultQueue()によって返されるデフォルトキューを使用することが出来ます。
次の例は3件のキューを定義しています:


 

   
default
   
1/s
 

 

   
mail-queue
   
2000/d
   
10
 

 

   
background-processing
   
5/s
 

アプリのキューの設定はアプリの全てのバージョンに適用されます。 与えられたアプリのバージョンがタスクをキューに入れた場合、キューはそのアプリのバージョン用のタスクハンドラを使用します。
全てのアプリは毎秒5件のタスクのレートで処理するデフォルトキューを持ちます。 queue.xmlに default という名のキューを定義することによってこのキュー用の設定をカスタマイズ出来ます。設定しない場合、 defaultは最初に使用される時まで管理コンソールで表示されません。

アプリはqueue.xmlで定義したキューとデフォルトキューにのみタスクを追加出来ます。キューを除去した、新しいqueue.xmlをアップロードしても、そのキューがまだタスクを抱えてる場合、キューは”一時停止”(処理レートが0にセットされる)になりますが削除されません。キュー定義をした新しい queue.xmlをアップロードすることによって削除したキューを再び使用可能に出来ます?

は更にと名付けられた要素を含むことも出来ます。 これは全てのキューで 消費することが可能なストレージタスクデータの総量を指定します?
(※原文 specifies specifies?)
この値は単位が後に続く数です。: B = バイト, K = キロバイト, M =メガバイト, G =ギガバイト, T =テラバイト。 たとえば100K は100キロバイト制限に指定します。ストレージ制限を越えてキューにタスクを追加しようとした場合、タスク追加の呼び出しは失敗します。デフォルト制限値は100M (100メガバイト)です。

 実行に失敗したタスクの再試行設定

タスクキュー内のタスクは多くの理由で失敗することがあります。タスクは実行に失敗した場合(200-299の範囲外のHTTPステイタスコードが返さることによって)、Appエンジンはそのタスクが成功するまでリトライします。 デフォルトではシステムは余りにも多すぎるリクエストでアプリケーションを溢れさせることを避ける為に漸進的にリトライレートを減らしますが、スケジュールリトライはタスクが成功するまで最大一時間に一回、再発を試みます。


さらにqueues.xml  要素を追加することによりタスクのリトライをあなたのスキーム(枠組みをもった計画)で指定出来ます。この追加をすることで指定したキューでの失敗したタスクのリトライする回数の最大値を指定することがを可能です。さらにリトライ試行のタイムリミットと試行間隔の制御もセット出来ます。
以下の例は様々なリトライのシナリオを説明しています:
  • fooqueueでは、タスクは最初の実行試行から少なくとも2日間の間に7回リトライされます。 両方の制限を超過すると、そのタスクは永久に失敗します。
  • barqueueでは、Appエンジンは再送限度に達し最大間隔で無制限にリトライするまで、各リトライ間の間隔を線形状に増やしてタスクのリトライを試みます。(したがってリクエスト間の間隔は10s, 20s, 30s, …, 190s, 200s, 200s, …となります).
  • bazqueueでは、間隔は最小の再送間隔から二倍に増加していき、最大の間隔で無制限にリトライします。(したがってリクエストの間の間隔は10s, 20s, 40s, 80s, 120s, 160s, 200s, 200s, …となります).


 

   
fooqueue
   
1/s
   

     
7
     
2
   

 

 

   
barqueue
   
1/s
   

     
10
     
200
     
0
   

 

 

   
bazqueue
   
1/s
   

     
10
     
200
     
2
   

 

 キュー定義

queue.xml ファイルはというルート要素を持つXMLファイルです。この要素は0件以上の要素 を含みます。(それぞれ名付けられたキューにつき一つ)
 要素はキュー用の設定を含みます。以下の要素を含むことが出来ます:
キューの名前. これはQueueFactory.getQueue()を呼び出した時に指定した名前です。
キューの名前には文字、数字、ハイフンを使うことが出来ます。
このキューでどれくらいの頻度でタスクが処理されるか。この値は後にスラッシュと時間の単位が続く数です。単位が秒の場合はs、分の場合はm、時間の場合はh、日数の場合はd です。例えば値が5/m なら1分間に五回の割合で処理されます。
(0/sのように)数が0の場合, キューは”一時停止”であるとみなされ、タスクは処理されません。
タスクキューはタスクをキューから取り出すするために”トークンバケット”アルゴリズムを使用します。 バケットサイズは、多数のタスクがキューにありレートが高い時、どれくらい速くキューが処理されるかを制限します? これはタスクがキューに入れられた後すぐに処理を開始するので高い処理レートを可能にしますが、短期間に多数のタスクがキューに入れられた場合、リソース使用を制限します? キュー用に が指定されていない場合、デフォルト値は5です。
アルゴリズムについてより詳しい情報は wikipediaの記事:トークンバケットを見てください。
実行に失敗したタスクのリトライ試行を設定します。この追加をすることで指定したキューでの実行に失敗したタスクがリトライする最大回数を指定することが可能になります。さらにリトライ試行の時間制限と試行間隔の制御もセット出来ます。

実行に失敗したタスクをリトライを試みる最大回数。task-age-limitと一緒に指定されている場合、Appエンジンは両方の制限に達するまでタスクをリトライします。 
タスクが失敗した後、タスクをリトライする前に待機する最小秒数。
タスクが失敗した後、タスクをリトライする前に待機する最大秒数。
増加が一定になる前の実行に失敗したタスクのリトライ間隔が二倍にされる時の最大値? 一定値は以下の式で求められます?:  2**(max-doublings – 1) * min-backoff-seconds.
実行に失敗したタスクをリトライする時間制限。(タスクが作成されてからの秒数)  この値は時間の単位が続く数です。単位が秒の場合はs、分の場合はm、時間の場合はh、日数の場合はd です。例えば値が5d ならタスクの実行が初めて試みられた後、5日間の制限を指定します。task-retry-limitと一緒に指定されている場合、Appエンジンは両方の制限に達するまでタスクをリトライします。 

 タスクキュー設定の更新

アプリ用のタスクキュー設定は appcfg.sh update を使用してアプリケーションをアップロードした時に更新されます。  フルアプリケーションを アプリのタスクキューの設定を更新出来ます。queue.xml ファイルをアップロードするために, appcfg.sh update_queues コマンドを使用します:

./appengine-java-sdk/bin/appcfg.sh update_queues myapp/war

より詳しい情報はUploading an and Managing a Java App を見てください。