jetpack.lib.twitterは、Twitter REST APIを扱う非常にシンプルで軽量なライブラリです。単なるXMLHTTPRequestの糖衣構文以上の事ができます。
ライブラリを使うには、Twitter's own APIに慣れている必要があるでしょう. (簡単です！)
メソッドについて
各メソッドはそれぞれTwitter APIに対応しています. 例えば、つぶやくためのAPIメソッドstatuses/updateは,jetpack.lib.twitter.statuses.update()に対応します. trends/currentを呼ぶ為には jetpack.lib.twitter.trends.current()を使います. searchは？ jetpack.lib.twitter.search()です. スラッシュをドットに変えれば、だいたいうまくいくでしょう。
ほとんどのTwitter APIメソッドがサポートされていますが、サポートされていないものもあります。リストを取得するメソッドやスパムを報告するメソッド、OAuthはサポートされていません。使いたい機能がサポートされていなかった場合は、バグを報告するか、. パッチを書いて下さい!
引数について
ライブラリの全てのメソッドは単一のオブジェクトを引数にとります。オブジェクトの定義の方法は2通りあります。
シンプルな一つ目の方法は、Twitterメソッドのパラメータを表現するオブジェクトのプロパティを定義する方法です。例えば、いくつかのTwitterのメソッドはidパラメーターを取ります。これらのメソッドを使う場合、idプロパティを定義してユーザのIDをセットします。(TwitterのAPIリファレンスに様々なメソッドのパラメータの解説が載っています)。 また、successとerrorという特別なパラメーターも存在します. successはリクエストが成功した場合に呼び出されるコールバック関数で、errorはリクエストが失敗時に呼び出されるコールバック関数です. ライブラリは受け取ったコールバックを単純にjQuery.ajax()渡すため, 以下のように呼び出されます。
success(data, textStatus)dataはデコードされたJSONレスポンスです。textStatusはステータスを表すシンプルな文字列です。
error(xmlHttpRequest, textStatus, errorThrown)xmlHttpRequestはリクエストで使われたXHRです.textStatusはエラーの型を表すシンプルな文字列です.errorThrownは送出された例外オブジェクトです.
以下の全てのサンプルコードでは引数の与え方に、最初の単純な方法を使っています。
jQuery.ajax()に慣れた人は2番目の方法を使うのがよいでしょう。実際、与えられたオブジェクトはほとんどそのままjQuery.ajaxに渡されます。つまり、引数として渡されるオブジェクトのdataプロパティはTwitterメソッドのパラメータとして使われます。この方法では様々なjQuery.ajax()オプションをリクエストで使えるでしょう。例えば、data、success、complete、などです。以下に2番目の方法を使ったサンプルを表示します。
jetpack.lib.twitter.statuses.update({
data: {
status: "O frabjous day!"
},
username: "basic_auth_username",
password: "basic_auth_password",
success: function () console.log("Hey!")
});
ユーザの認証
以下で示すように、2番目の方法を使って認証が必要なメソッドにユーザ名とパスワードを渡す事ができます。
もしくはもっと簡単に、Firefoxにたよることもできます。jetpack.lib.twitter.statuses.update()のように認証が必要なメソッドを使った時に、ユーザ名とパスワードを渡さなければ、Firefoxはまだ認証が済んでいないユーザの為にプロンプトを表示します。
どちらの方法もHTTPベーシック認証を使っています. いずれライブラリはOAuthするかもしれません。 Twitter's authentication documentation に関連する情報が記載されています。
よくある質問
Twitter's API FAQを見て下さい。 JetpackのTwitter libraryはTwitter APIの非常に薄いラッパーなので、ここに載っている事がだいたい当てはまりますし、載っていない事はあてはまらないでしょう。
サンプルコード
つぶやく
jetpack.lib.twitter.statuses.update({ status: "O frabjous day!" });
Firefox will prompt for a username and password if the user is not already authenticated with Twitter.
ユーザの情報を取得する
jetpack.lib.twitter.users.show({
id: "mozlabs",
success: function (data, status) console.log(data.toSource()),
error: function (xhr, errMsg, errObj) console.error(xhr.responseText)
});
ユーザのフォロワーを取得する
jetpack.lib.twitter.statuses.friends({
id: "mozlabs",
page: 3,
success: function (data, status) console.log(data.toSource()),
error: function (xhr, errMsg, errObj) console.error(xhr.responseText)
});
トレンド
jetpack.lib.twitter.trends({
success: function (data, status) console.log(data.toSource()),
error: function (xhr, errMsg, errObj) console.error(xhr.responseText)
});
検索
jetpack.lib.twitter.search({
q: "#jetpack",
lang: "ja",
rpp: 10,
page: 5,
since_id: 1337,
success: function (data, status) console.log(data.toSource()),
error: function (xhr, errMsg, errObj) console.error(xhr.responseText)
});