Blogger Data API

http://code.google.com/intl/ja/apis/blogger/docs/2.0/developers_guide_java.html

 Developer’s Guide: Java

BloggerデータAPIはクライアントアプリケーションに GoogleデータAPIフィードの形式でBolggerの内容を閲覧・更新することを可能にします。
クライアントアプリケーションは新しいブログポストの作成、既存のブログポストの編集または削除、詳細な基準に一致するブログポストのクエリをするためにBloggerデータAPIを使うことが出来ます。
BloggerデータAPIの機能の背景の提供に加えて、このガイドはJava client libraryを使用してベーシックデータAPIと対話する例を提供します。 クライアントライブラリのセットアップのヘルプについてはGetting Started with the Google Data Java Client Libraryを見てください。ドキュメントと対話する為のJava クライアントライブラリによって使用される根本的なプロトコルについてより理解することに興味がある場合はprotocol guideを見てください。

 内容

 対象読者

このドキュメントはBloggerと対話できるJavaクライアントアプリケーションを作成したいプログラマーを対象としています。
このドキュメントは対象読者がGoogle Data APIs protocol.の背後にある概括的な概念を理解していると仮定します。
クライアントライブラリによって提供されるクラスとメソッドについてのリファレンス情報についてはJava client library API referenceを見てください。概括的なBloggerデータAPIリファレンス情報については、Protocol reference guideを見てください。

 はじめに

クライアントライブラリのセットアップのヘルプについてはGetting Started Guideを見てください。
Javaクライアントライブラリを使用するにはJava 1.5が必要です。クライアントライブラリのダウンロード後に  java/lib/gdataclient-1.0.jarファイル内に(このページでの学習を)始める為に必要なクラスを見つけるでしょう。

Bloggerアカウントの作成

テスト目的でBloggerアカウントのサインアップ をしたいと思うかもしれません。BloggerはGoogle Accountsを使用してますので、既にGoogleアカウントを持っている場合、準備完了です。

サンプルコードの実行

このドキュメントで示される全てのサンプルコードを含む完動サンプルクライアントはJavaクライアントライブラリ配布物内のgdata/java/sample/blogger/BloggerClient.javaで利用可能です。構築と実行の手順はサンプルディレクトリのREADME.txt ファイルに含まれています。
サンプルクライアントはBloggerデータAPIの使い方を説明する為に供給されたブログで幾つかの操作を実行します。
自身のコードにこのドキュメントの例を組み込むには次のimportステートメントが必要です:

import com.google.gdata.client.*;
import com.google.gdata.data.*;
import com.google.gdata.util.*;
import java.io.IOException;
import java.net.URL;

 Bloggerサービスへの認証

BloggerデータAPIを使用してパブリックとプライベート両方のフィードにアクセス出来ます。パブリックフィードはいかなる認証も要求しませんが、リードオンリーです。ブログを修正したい場合、クライアントソフトはプライベートフィードをリクエストする前に認証する必要があります。次の2つのアプローチの内、いずれかを使用して認証出来ます: AuthSub プロキシ認証 または ClientLogin ユーザーネーム/パスワード 認証。
一般的なGoogle Data APIでの認証についてのより詳しい情報はauthentication documentationを見てください。
このドキュメントの以降のセクションのサンプルの多くは認証済みGoogleService オブジェクトを作成しているという前提で進めます。

AuthSub プロキシ 認証

AuthSubプロキシ認証はGoogleアカウントで自身のユーザー達を認証することが必要なwebアプリケーションによって使用されます。webサイトオペレータとクライアントコードはBloggerユーザー用のユーザーネームとパスワードにアクセスしません; 代わりに、クライアントは、クライアントが特定のユーザーの代理をすることが出来る特別なAuthSubトークンを取得します。 より詳しい情報についてはAuthSub documentationを見てください。
ユーザーが初めてアプリケーションを訪れた時、ユーザーはまだ認証されていません。この場合、ユーザーが自身のブログへのアクセスリクエストを認証するようにGoogleページへ向かわせる何らかの情報とリンクを表示する必要があります。JavaクライアントライブラリはGoogle ページのURLを生成するための機能を提供しています。以下のコードはAuthSubリクエストページのURLを取得します:

String next = "http://www.example.com/welcome.html";
String scope = "http://www.blogger.com/feeds/";
boolean secure = false;
boolean session = true;
String authSubLogin = AuthSubUtil.getRequestUrl(next, scope, secure, session);

getRequestUrl メソッドは以下のパラメータを使用します (AuthSubRequestハンドラにより使われるクエリパラメータと一致しています):
next
Googleが認証後にユーザーを転送すべきページのURL
scope
アプリケーションがリクエストしているBloggerフィードにアクセスする為のトークンを指示します。 使用されるscope文字列は http://www.blogger.com/feeds/ (当然、URLエンコード済み) です。
secure
クライアントがセキュアトークンをリクエストするかどうかを指示します。
session
返されたトークンがマルチユース(セッション) トークンと交換できるか指示します。 ※マルチユース=複数回繰り返し使用出来る?
上記の例はセキュアトークンをリクエストしていない呼び出しであることを表しています ( secure の値が false)。 結果としてのリクエストURLは以下のようになります:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session;=1&secure;=0&next;=http%3A%2F%2Fwww.example.com%2Fwelcome.html

ユーザーはGoogleサイトへのリンクを辿り、自身のGoogleアカウントを認証します。
ユーザーの認証後、AuthSubシステムはAuthSubRequest URLの next クエリパラメータで指定したURLへユーザーを転送します。AuthSubシステムは token クエリパラメータの値として認証トークンをそのURLへ追記します。例えば:

http://www.example.com/welcome.html?token=yourAuthToken

このトークンの値はシングルユースAuthSubトークンを表しています。この例ではsession = trueと指定されているので、  以下のように 、urlFromAuthSub がAuthSubがトークンを追記したURLである場合、このトークンはAuthSubSessionToken サービスを呼び出すことによってAuthSubセッショントークンと交換することが出来ます?:

String token = AuthSubUtil.getTokenFromReply(urlFromAuthSub);
String sessionToken = AuthSubUtil.exchangeForSessionToken(token, null);

つまり、 exchangeForSessionToken メソッドへnull(未登録モード)またはプライベートキー(登録モード)のどちらかに加えてワンタイムユーストークンを渡すとAuthSubインターフェイスはセッショントークンを返します。登録アプリケーションとプライベートキーについてのより詳しい情報はAuthSubドキュメンテーションの”Signing requests“セクションを見てください。  
これでアプリケーションはBloggerとの以降の対話でセッショントークンを使用することが出来ます。Javaクライアントライブラリへ各リクエストで自動的にセッショントークンを送信することを指示するには、GoogleServiceオブジェクトの setAuthSubToken メソッドを呼び出します:

GoogleService.setAuthSubToken(sessionToken, null);

その後、クライアントライブラリは自動的に全てのリクエストと共にトークンを送信します。

ClientLogin ユーザーネーム/パスワード 認証

クライアントがスタンドアローン、シングルユーザー用”インストールされた”クライアント(デスクトップアプリケーションのような)の場合、ClientLogin認証を使ってください。GoogleServiceのオブジェクトのsetUserCredentialsメソッドを呼び出してください。そうすれば以降全てのBloggerとの対話は認証済みとなるでしょう:

GoogleService myService = new GoogleService("blogger", "exampleCo-exampleApp-1");
myService.setUserCredentials("user@example.com", "secretPassword");

上記のコードでは GoogleService コンストラクタへ2つのパラメータを渡しています。最初のパラメータは対話(利用)したいサービスの名前です。2つ目のパラメータはcompanyNameapplicationNameversionID形式のアプリケーションの名前です。
リクエストとレスポンスのサンプルを含むClientLogin認証についてのより詳しい情報はAuthentication for Installed Applicationsドキュメンテーションを見てください。
Note: 与えられたセッションで全てのリクエストで同じトークンを使うには、各Bloggerリクエストで新しいトークンを取得しないでください?
Note: ClientLoginドキュメンテーションで記述されているように、認証リクエストは失敗しCAPTCHA チャレンジを要求するかもしれません。GoogleにCAPTCHA チャレンジの発行と処理をして欲しい場合は、ユーザーを https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (ClientLogin ドキュメンテーションで与えられるCAPTCHA処理URLではなく)へ送ります。

 ブログのリストの取得

BloggerデータAPIは 特定のユーザーのブログをリストにしたフィードを提供します;そのフィードは”メタデータ”として知られています。
次のサンプルコードはメタフィードを取得し各ブログタイトルを出力する為に認証済みGoogleServiceオブジェクトを使います。

public static void printUserBlogs(GoogleService myService)
throws ServiceException, IOException {

// フィードのリクエスト
final URL feedUrl = new URL("http://www.blogger.com/feeds/default/blogs");
Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

// 結果の出力
System.out.println(resultFeed.getTitle().getPlainText());
for (int i = 0; i < resultFeed.getEntries().size(); i++) {
Entry entry = resultFeed.getEntries().get(i);
System.out.println("t" + entry.getTitle().getPlainText());
}
}

getFeed メソッドによって使用されるURLに注意してください。これはデフォルトのメタフィードのURLです; 現在、認証されているユーザーのブログのリストを返します。異なるユーザーのフィードにアクセスするにはメタフィードURLの default の箇所にそのユーザーのIDにします。ユーザーのIDはユーザープロフィールURLの最後にある数字の文字列です。

 ポストの作成

BloggerデータAPIはエントリの下書き(ドラフト)の作成と同様に新しいブログエントリの作成と公開(出版)することを可能にします。
Note: 現在、ポストの著作者をカスタマイズすることはサポートされていません。全ての新しいポストは現在認証されているユーザーによって作成されたかのように見えます?

ブログポストの公開

新しいブログエントリを公開するためにJavaクライアントライブラリを使うことが出来ます。
最初にブログポストを表すEntryオブジェクトを作成します。それからブログポストのタイトル、内容、その他の属性を設定します。最後に、ポストを挿入する為にGoogleServiceオブジェクトを使います。以下は新しいブログポストを公開する方法の例です:

public static Entry createPost(
GoogleService myService, String blogID, String title,
String content, String userName)
throws ServiceException, IOException {
//挿入するエントリの作成
Entry myEntry = new Entry();
myEntry.setTitle(new PlainTextConstruct(title));
myEntry.setContent(new PlainTextConstruct(content));

// サービスへ新しいエントリの挿入を依頼
URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
return myService.insert(postUrl, myEntry);
}

insert メソッドはパラメータとしてサービスのポストURLを使います。その後、Bloggerによって格納されると、メソッドはエントリを返します。 返されたエントリは送信したエントリと同一ですが、ポストIDのような、Bloggerによって追加された様々な要素も含みます。
何らかの理由でリクエストが失敗した場合、Bloggerは異なるステイタスコードを返すかもしれません。ステータスコードについての情報はGoogle Data API protocol reference documentを見てください。

 ドラフトブログポスト(下書き)の作成

ドラフトポストは公開ポストと同じ方法で作成されますが、Entry オブジェクトのdraft属性を設定する必要があります。 ハイライトされた一行を追加することによって上記のようなブログポストをドラフトとして作成できます。

public static Entry createPost(GoogleService myService, String blogId,
String title, String content, String userName,
Boolean isDraft)
throws ServiceException, IOException {
// 挿入するエントリを作成
Entry myEntry = new Entry();
myEntry.setTitle(new PlainTextConstruct(title));
myEntry.setContent(new PlainTextConstruct(content));
myEntry.setDraft(isDraft);

// サービスへ新しいエントリの挿入を依頼
URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
return myService.insert(postUrl, myEntry);
}

ドラフトポストを取得し、draft属性をfalseに設定してからポストを更新することによって既存のドラフトポストを公開ポストに変更出来ます。次の2セクションでポストの取得と更新をカバーします。

 ポストの取得

次のセクションはqueryパラメータがある場合とない場合でのブログポストのリストを取得する方法を説明します。
Blogger 公開フィードのクエリは認証なしで出来ます。したがって setUserCredentials メソッドを呼び出しまたは、公開ブログからポストを取得する前にAuthSub認証をする必要はありません。

 全ブログポストの取得

ユーザーのポストを取得するには、ブログメタフィードを取得する為に使われるgetFeed メソッドと同じものを呼びますが、この時ははブログをポストするフィードURLを送信します:

public static void printAllPosts(
GoogleService myService, String blogId)
throws ServiceException, IOException {
// フィードのリクエスト
URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

// 結果の出力
System.out.println(resultFeed.getTitle().getPlainText());
for (int i = 0; i < resultFeed.getEntries().size(); i++) {
Entry entry = resultFeed.getEntries().get(i);
System.out.println("t" + entry.getTitle().getPlainText());
}
System.out.println();
}

 クエリパラメータを使用したポストの取得

Blogger データ API は、公開された、または与えられた日付範囲内に更新されたブログポストのリクエストのような、指定した判定基準に一致したエントリのセットをリクエストすることを許可します。これを行うには、 Query オブジェクトを作成し、 GoogleService.getQuery メソッドへ渡します。
例えば日付範囲クエリを送信するには、Query オブジェクトのsetPublishedMin と setPublishedMax メソッドを使います。次のコードは与えられたスタートタイムとエンドタイムの間に公開されたブログポスト全てのタイトルを出力します:

public static void printDateRangeQueryResults(
GoogleService myService, String blogId,
DateTime startTime, DateTime endTime)
throws ServiceException, IOException {
//クエリの作成とリクエストの提出
URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
Query myQuery = new Query(feedUrl);
myQuery.setPublishedMin(startTime);
myQuery.setPublishedMax(endTime);
Feed resultFeed = myService.query(myQuery, Feed.class);

// 結果の出力
System.out.println(resultFeed.getTitle().getPlainText() +
" posts between " + startTime + " and " + endTime);
for (int i = 0; i < resultFeed.getEntries().size(); i++) {
Entry entry = resultFeed.getEntries().get(i);
System.out.println("t" + entry.getTitle().getPlainText());
System.out.println("t" + entry.getUpdated().toStringRfc822());
}
System.out.println();
}

 Query オブジェクトはをポストを取得するために使われるポストフィードURLと同じものを使用して構築されているということに注意してください。
Blogger データ API は以下のQuery メソッドをサポートしています:
addCategoryFilter
フィードの結果をフィルタリングするカテゴリ(labelsとしても知られる)を指定します。 例えば http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie Fritz と Laurieの両方のレーベルを伴うエントリが返されます。
setMaxResults
返されるエントリ数の最大値を設定します。
setPublishedMin, setPublishedMax
公開日付の範囲を設定します。
setStartIndex
1ベースのインデックスの取得した結果の最初を設定します?(ページング用)
setUpdatedMin, setUpdatedMax
エントリの更新日付の範囲を設定します。  orderbyパラメータにupdatedがセットされていない場合、これらのパラメータは無視されます。
Note: 現在、orderby クエリパラメータのためのセッターメソッドはありません。しかしながら、これを設定する必要がある場合はQuery.addCustomParameter() メソッドを使うことが出来ます。
クエリパラメータについてのより詳しい情報についてはBlogger Data API Reference Guide と Google Data APIs Reference Guideを見てください。

 ポストの更新

既存のブログポストを更新するには、最初に更新したいエントリを取得し、修正してからupdate メソッドを使用してBloggerへそれを送信します。次のコードはブログエントリのタイトルの修正します。エントリは既にサーバから取得済みと仮定しています。

public static Entry updatePostTitle(
GoogleService myService, Entry entryToUpdate, String newTitle)
throws ServiceException, IOException {
entryToUpdate.setTitle(new PlainTextConstruct(newTitle));
URL editUrl = new URL(entryToUpdate.getEditLink().getHref());
return myService.update(editUrl, entryToUpdate);
}

上記のコードは完全に新しい更新済みのポストを含むEntryを返します。他のプロパティを更新するには、単にupdateを呼び出す前に Entryにそれらをセットします。
Note: 現在、ポストに関連付けられた著作者データの修正はサポートされていません。

 ポストの削除

ポストを削除するには、以下のように GoogleService オブジェクトの delete メソッドへポストの編集URLを渡します:

public static void deletePost(
GoogleService myService, String editLinkHref)
throws ServiceException, IOException {
URL deleteUrl = new URL(editLinkHref);
myService.delete(deleteUrl);
}

 コメント

Blogger データ API はコメントの作成、取得、削除を可能にします。コメントの更新はサポートされていません。 (これはwebインターフェイスでも利用可能ではありません)

コメントの作成

コメントをポストするには、以下のように Entry オブジェクトを作成して挿入します:

public static Entry createComment(
GoogleService myService, String blogID, String postId,
String commentText)
throws ServiceException, IOException {
// コメントフィードURIの構築
String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
URL feedUrl = new URL(commentsFeedUri);

// コメント用の新しいエントリの作成とGoogleServiceへの提出
Entry myEntry = new Entry();
myEntry.setContent(new PlainTextConstruct(commentText));
return myService.insert(feedUrl, myEntry);
}

Note: 現在、認証されているユーザーによって所有されるブログへのみコメントのポストが出来ます。
Note:現在、コメントの著作者をカスタマイズすることはサポートされていません。全ての新しいコメントは現在認証されているユーザーによって作成されたかのように見えます?

 コメントの取得

ポストのコメントフィードURLから特定したポストへのコメントを取得することが出来ます:

public static void printAllComments(
GoogleService myService, String blogID, String postId)
throws ServiceException, IOException {
// コメントフィードURIの構築と指定したポストでのコメントのリクエスト
String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
URL feedUrl = new URL(commentsFeedUri);
Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

// 結果の表示
System.out.println(resultFeed.getTitle().getPlainText());
for (int i = 0; i < resultFeed.getEntries().size(); i++) {
Entry entry = resultFeed.getEntries().get(i);
System.out.println("t" +
((TextContent) entry.getContent()).getContent().getPlainText());
System.out.println("t" + entry.getUpdated().toStringRfc822());
}
System.out.println();
}

またはブログのコメントフィードURLを使用することによって、全てのポストからコメントを取得することが出来ます:

http://www.blogger.com/feeds/blogID/comments/default

 コメントの削除

コメントを削除するには、以下のように GoogleService オブジェクトのdelete メソッドへコメント編集URLを渡します:

public static void deleteComment(GoogleService myService, String editLinkHref)
throws ServiceException, IOException {
URL deleteUrl = new URL(editLinkHref);
myService.delete(deleteUrl);
}