DNPP on Tumblr

Tumblr APIの使い方を勝手に和訳したもの

Tumblr, プログラミング

これは僕がTumblr APIのリファレンスを許可を得ずに勝手に和訳したものです。

英語の原文は、こちらにあります。

http://www.tumblr.com/docs/api

Tumblr APIは一般的なHTTPのリクエストを実行します。ですから、様々なアプリケーションからWebを通じてTumblrを使うことができます。

Tumblrのデータを読むのは簡単です。http://(you).tumblr.com/api/read からXML形式のデータを取ってくることができます。以下にデータの例を示します。

<tumblr version="1.0">
    <tumblelog ... >
        ...
        <feeds>
            <feed ... />
            <feed ... />
            ...
        </feeds>
    </tumblelog>
    <posts>
        <post type="regular" ... >
            <regular-title>...</regular-title>
            <regular-body>...</regular-body>
        </post>
        <post type="link" ... >
            <link-text>...</link-text>
            <link-url>...</link-url>
        </post>
        <post type="quote" ... >
            <quote-text>...</quote-text>
            <quote-source>...</quote-source>
        </post>
        <post type="photo" ... >
            <photo-caption>...</photo-caption>
            <photo-url max-width="500">...</photo-url>
            <photo-url max-width="400">...</photo-url>
            ...
        </post>
        <post type="conversation" ... >
            <conversation-title>...</conversation-title>
            <conversation-text>...</conversation-text>
            <conversation>
                <line name="..." label="...">...</line>
                <line name="..." label="...">...</line>
                ...
            </conversation>
        </post>
        <post type="video" ... >
            <video-caption>...</video-caption>
            <video-source>...</video-source>
            <video-player>...</video-player>
        </post>
        <post type="audio" ... >
            <audio-caption>...</audio-caption>
            <audio-player>...</audio-player>
        </post>
        ...
    </posts>
</tumblr>

デフォルトでは20のポストです。GETパラメータを用いることで、取得するデータをいろいろ変えることができます。GETパラメータは以下の通りです。

• start - 何番目のポストから取ってくるか指定できます。デフォルト値は0。
• num - いくつのポストを取ってくるか指定できます。デフォルトでは20で、最大で50です。
• type - 取ってくるポストの種類を指定できます。指定しなかったり空値だったりすると、すべての型のポストを取得します。
  ポストの種類は、text, quote, photo, link, chat, video, audioのうちから選んでください。
• id - 特定のIDのポストを指定します。startやnum, typeの代わりに使うことができます。
• filter - textコンテンツに対してフィルターをかけます。以下の二種類のフィルタがあります。
  • text - プレーンテキストのみ。HTMLは駄目。
  • none - ポストの内容は取得しません。そのポストの種類だけが帰ってきます。(Markdownを使う人がいます。このオプションを使うと、MarkdownはHTMLに変換されません。)
• tagged - 日付順に逆順にソートして、タグを付加してポストを取得します。(新しい順になるということ)
  古い順にソートしたい場合はchrono=1とするとよい。
• search - ポストを検索することができます。
• state (Authenticated read(後述)が要求されます) - draft, queue, submissionのうちひとつを指定することができます。それぞれの状態にあるポストのリストを作成することができます。

詳細なサンプルを、Marco.orgやthe demo blogでご覧になれます。Firefoxのような今時のブラウザはXMLをきれいに構造化して表示してくれるでしょう。

/api/readの代わりに/api/read/jsonを取得に使うと、 アウトプットはJSONとしてJavascriptの変数に割り当てられます。上記に述べたポスト取得用のパラメータはすべて使うことができます。また、追加としてcallbackを使えます。

• callback - このパラメータをセットすると、tumblr_api_read変数の代わりにこの関数がセットされます。

例:

<script type="text/javascript" src="http://(you).tumblr.com/api/read/json"></script>

<script type="text/javascript">
    // The variable "tumblr_api_read" is now set.
    document.write(
        '<a href="' + tumblr_api_read[1][0]['@url'] + 
        '">Most recent Tumblr post</a>'
    );
</script>

debug=1というGETパラメータを付加することで、人間の読みやすい形で構造を見ることができます。アウトプットはPHPのprint_r()関数のようなものになります。

/api/readでプライベートのポストを取得するためには、アカウント認証からemailとpasswordのパラメータを取得する必要があります。これによってDashboardを取得できます。詳しくは/api/writeで後述します。

<post>ノードの中で private=”True” とXMLで指定された場合にプライベートなポストが可視になります。

http://www.tumblr.com/api/dashboard に対してAuthenticated readでしたようにポストを読むことができます。使用できるパラメータは以下の通りです。

• email - アカウントのメールアドレス
• password - アカウントのパスワード
• start, num, type, filter(オプション) - /api/readと同じです。startの最大値は250です。

アウトプットはXML形式です。

Dashboardをキャッシュに大量に読み込むことがあるでしょう。リクエストは10秒ごとにしか実行できないことに注意してください。

もし限度を超えた大量の読み込みを行った場合、503エラーが返るかもしれません。あまり読み込みにがっつかないでください。

Write APIは非常にシンプルなHTTPのインタフェースです。ポストを投稿するためには、以下に示すようなパラメータとともに http://www.tumblr.com/api/write にリクエストを投げるだけ済みます。

• email - アカウントのメールアドレス。
• password - アカウントのパスワード。
• type - ポストのパラメータです。
• (content parameters) - ポストのタイプによって変化するパラメータ。
• generator(オプション) - アプリケーションが付加することのできる64文字以下の短い説明です。例えば、”John’s Widget 1.0”のようなものです。
• date(オプション) - 投稿日時を指定することができます。日時のフォーマットは曖昧性のない表記なら大抵のものが使えます。例えば、’2007-12-01 14:50:02’のようなものです。未来の日時を指定することはできません。
• private(オプション) - 1か0で指定します。プライベートのポストはダッシュボードと認証されたリンクにしか表示されません。ブログのメインページには表示されません。
• tags(オプション) - カンマで区切ってポストにタグを付加することができます。オプションとして、タグはダブルクオートで囲むことができます。
• format(オプション) - htmlかmarkdown。
• group(オプション) - アカウントの二つ目のブログにポストします。つまり、
  mygroup.tumblr.com(パブリックなグループのみ)
• slug(オプション) - 以下のようにURLをカスタマイズできます。
  myblog.tumblr.com/post/123456/this-string-right-here
  最大で55文字です。
• state(オプション) - 以下のうちでひとつを指定することができます。
  • published(デフォルト値)
  • draft - のちに公開するとして、tumblogのDraftフォルダに保存しておく。
  • submission - tumblelogのMassageフォルダに追加します。
  • queue - tumblelogに投稿する時間を数分後もしくは数時間後に設定できます。特定の未来の時間に投稿したい場合、publish-onという追加パラメータを使用します。publish-onは、例えば publish-on=2010-01-01T13:34:00 のように指定します。日付のフォーマットが不正の場合、401エラーが帰ってきてポストは作成されません。

ポストの作成後にポストの状態を変更したい場合(例えばdraftをpublishedにしたり)、”ポストを編集する“を御覧下さい。いくつかの追加パラメータを指定することで、ポストを変更することができます。

Note : もしすでに存在するdraftやqueueのポストをpublishedに変更する場合などは、初めて状態をpublishedにしたときにIDが割り当てられます。

• send-to-twitter (オプション、投稿後にこの属性を変更することはできません) - TwitterとTumblrの連携を設定しているときに、Twitterに投稿するかどうかを以下のパラメータを用いて指定することができます。
  • no(デフォルト値) - Twitterには投稿しません。
  • auto - Twitterに自動的に投稿します。投稿にはポストの概要が付加されます。
  • (any other value) - Twitterにポストを送るときに使うカスタムのメッセージです。

このパラメータが設定されていない場合、TumblrのCustomizeスクリーンで”Send my Tumblr posts to Twitter“にチェックが入っているかどうかでTwitterに投稿されるかどうかが判定されます。

有効なポストのタイプを、それらがサポートするパラメータと共に示します。

• regular - 以下のうちのどちらかが必要
  • title
  • body(HTMLが使用できる)
• photo - sourceかdataのどちらかを使用します。どちらも使用した場合、souceが優先されます。
  • source - 画像データのURL。WebからアクセスできるURLでなければいけません。ローカルデータやイントラネットのロケーションであってはいけない。
  • data - 画像イメージ。ファイルのアップロードに関しては後述します。
  • caption (オプション、HTMLが利用できる)
  • click-through-url (オプション)
• quote
  • quote
  • source (オプション)
• link
  • name (オプション)
  • url
  • description (オプション、HTMLが利用できる)
• conversation
  • title (オプション)
  • conversation
• video - embedとdataのどちらかを利用してください。どちらも利用することはできません。
  • embed - 動画が埋め込まれた完全なHTMLか、YouTubeの動画のURL。
  • data - ビデオのデータ。アップロードについては後述します。
  • title (オプション) - Videoをアップロードするときにだけ使用することができます。
  • caption (オプション、HTMLが利用できる)
• audio
  • data - オーディオファイルです。MP3かAIFFの形式のファイルにしてください。ファイルのアップロードについては後述します。
  • externally-hosted-url (オプション、dataの代わりに使います) - すでに外部のサービスにアップロードされたMP3ファイルのURLを指定します。ファイルのサイズは外部のサービスに依存します。
  • caption (オプション、HTMLが利用できる)

上記に述べたような特定のパラメータを使用して、データをアップロードできます。アップロードの方式には、以下の二つの方式があります。

• multipart/form-data method。この方式はWebからデータをアップロードするときによく用いられる方式です。最大のサイズは、
  • videoは50MB
  • photoは10MB
  • audioは10MB

オーバーヘッドの少ない方式ですので、こちらの方式をオススメします。

• Nomal POST Method。この方式は、他のPOST変数とおなじようにファイルをアップロードするものです。最大のサイズは
  • videoは5MB
  • photoも5MB
  • audioも5MB

各種のリクエストに対して、標準的なHTTPのステータス値を返します。

• 201 Created - 成功です。作成されたポストのIDが返ってきます。
• 403 Forbidden - メールアドレスかパスワードが間違っています。
• 400 Bad Request - 少なくとも1つのエラーが発生しています。エラーはプレーンテキストで返ります。

<?php

// Authorization info
$tumblr_email    = 'info@davidville.com';
$tumblr_password = 'secret';

// Data for new record
$post_type  = 'regular';
$post_title = 'The post title';
$post_body  = 'This is the body of the post.';

// Prepare POST request
$request_data = http_build_query(
    array(
        'email'     => $tumblr_email,
        'password'  => $tumblr_password,
        'type'      => $post_type,
        'title'     => $post_title,
        'body'      => $post_body,
        'generator' => 'API example'
    )
);

// Send the POST request (with cURL)
$c = curl_init('http://www.tumblr.com/api/write');
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, $request_data);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($c);
$status = curl_getinfo($c, CURLINFO_HTTP_CODE);
curl_close($c);

// Check for success
if ($status == 201) {
    echo "Success! The new post ID is $result.\n";
} else if ($status == 403) {
    echo 'Bad email or password';
} else {
    echo "Error: $result\n";
}

?>

もしなにかトラブルが発生したら、まずPOSTのパラメータのエンコーディングを疑ってください。それでも解決しない問題等ありましたら、support@tumblr.comまでどうぞ。

ポストを編集するには、すでに述べた/api/writeリクエストを用います。以下のPOSTパラメータを付加することにより、ポストを編集することができます。

• post-id - 編集したいポストのIDを整数型で。

その他のパラメータは/api/writeのものと同じです。

• type, private, format - これらの値は無視されます。省略してください。これらの値はポストの作成時に決めた値から変更することはできません。
• tags, generator, date - これらの値はオプションです。もし指定されていたら、もとの値を上書きします。省略された場合、これらの値は変更されません。

ポストを編集するためには、 /api/write の認証済みのポストを作成してください。しかしポストは http://www.tumblr.com/api/delete に投げる必要があります。次のPOSTパラメータを付加してください。

• post-id - 削除したいポストのIDを整数型で。

すべてのコンテンツにかんするパラメータは無視されます。認証用のパラメータとポストのIDのみが必要です。

http://www.tumblr.com/api/authenticateにメールアドレスとパスワードのパラメータのみ含まれたポストを投げることにより、認証を行い、ユーザ制限やブログといったアカウント情報を得ることができます。

アウトプットはXML形式です。ルート要素の<tumblr>は<user>ノードをひとつ含みます。また、<tumblelog>要素をブログのメンバーシップひとつにつきひとつ含みます。(ユーザのデフォルトのブログを含みます)

<user>に属するもの :

• can-upload-audio : “1” ユーザはMP3ファイルをアップロードすることができる。
• can-upload-aiff : “1” ユーザはAIFFの音楽ファイルをアップロードできる。
• can-upload-video : “1” ユーザはビデオをアップロードできる。アップロードされたビデオはTumblrを通じてvimeoにアップロードされる。
• max-video-bytes-uploaded : ユーザがアップロードできるビデオファイルの上限サイズ。ユーザはTumblrを通じてVimeoにログインすることになります。

<tumblelog>に属するもの

• title
• type : publicかprivateか
• private-id (private blogのみ) : プライベートブログのID。/api/writeグループのパラメータを使用します。
• name (public blogのみ)
• url (public blogのみ)
• avatar-url (public blogのみ)
• is-primary : yes ユーザのデフォルトブログだった場合。

以下の機能は近い将来破棄される可能性があるため使用を推奨しません。

• list-tumblelogs
• check-vimeo
• check-audio

これらの機能は/api/authenticateに含まれています。

iPhoneアプリでユーザのDashboardが表示したい場合、Tumblrは既にiPhoneに最適化されたウェブサイトを表示することができます。http://www.tumblr.com/iphone

もしTumblrの外部にユーザのログイン情報を格納して、そこからログインしたいという場合、　http://www.tumblr.com/login にログインのHTTP POSTを投げることで実現できます。以下のパラメータが必要です。

• email
• password
• redirect_to : ログイン後に開きたいURL

Cocoaでの例を以下に示します。

NSString *email           = @"example@email.com";
NSString *password        = @"password";
NSString *destination_url = @"/iphone";

NSMutableURLRequest *request = [[NSMutableURLRequest alloc]
    initWithURL:[NSURL URLWithString:@"http://www.tumblr.com/login"]
];
[request setHTTPMethod:@"POST"];
NSString *request_body = [NSString 
    stringWithFormat:@"email=%@&password=%@&redirect_to=%@",
    [email           stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding],
    [password        stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding],
    [destination_url stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding]
];
[request setHTTPBody:[request_body dataUsingEncoding:NSUTF8StringEncoding]];
/* Load the request here with an NDA-covered iPhone component
   that can view the web.
*/
[request release];

ほとんどのアプリケーションで、ポストの作成、編集、読み込みを行うためにTumblrのブラウザベースのログインシステム http://www.tumblr.com/login を使う必要があることはありません。

もし作成しようとしているアプリケーションが /api/read や /api/write のみを使うようなものだった場合、coockieやログイン制限について心配する必要はまったくありません。

もしも http://www.tumblr.com/login を使用するのであれば、以下のようなことに気をつけてください。

• Coockieは思わぬところで無効になったり、期限切れになったりします。それは保証がきかない機能なのです。無効なログインCoockieを使用すると、 http://www.tumblr.com/login にリダイレクトされます。
• ログインCookieが無効であった場合、Coockieのログイン制限にひっかかっているかもしれません。ログインCoockieを使い果たさないように注意してください。特に、リクエストで保持し続けることはやめてください。普通のブラウザベースのログインをする際に頻繁にログアウトしてしまう原因になります。
• http://www.tumblr.com/login を使ってログインし、ポストを投げるアプリケーションを作成する場合、そのCoockieが複製であるかどうかの判定はなされません。

/api/read や /api/write で事足りる場合、http://www.tumblr.com/login は使用しないでください。

http://www.tumblr.com/login のシステムは告知なく変更されることがあります。

• 2010/2/19 Dashboard APIを追加しました。
  Dashboard APIはこちらでアナウンスされています。