Tumblr APIの使い方を勝手に和訳したもの
和訳について
これは僕がTumblr APIのリファレンスを許可を得ずに勝手に和訳したものです。
英語の原文は、こちらにあります。
http://www.tumblr.com/docs/api
概要
Tumblr APIは一般的なHTTPのリクエストを実行します。ですから、様々なアプリケーションからWebを通じてTumblrを使うことができます。
/api/read
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コンテンツに対してフィルターをかけます。以下の二種類のフィルタがあります。
- tagged - 日付順に逆順にソートして、タグを付加してポストを取得します。(新しい順になるということ)
古い順にソートしたい場合はchrono=1とするとよい。 - search - ポストを検索することができます。
- state (Authenticated read(後述)が要求されます) - draft, queue, submissionのうちひとつを指定することができます。それぞれの状態にあるポストのリストを作成することができます。
詳細なサンプルを、Marco.orgやthe demo blogでご覧になれます。Firefoxのような今時のブラウザはXMLをきれいに構造化して表示してくれるでしょう。
JSON output
/api/readの代わりに/api/read/jsonを取得に使うと、 アウトプットはJSONとしてJavascriptの変数に割り当てられます。上記に述べたポスト取得用のパラメータはすべて使うことができます。また、追加としてcallbackを使えます。
例:
<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()関数のようなものになります。
Authenticated read
/api/readでプライベートのポストを取得するためには、アカウント認証からemailとpasswordのパラメータを取得する必要があります。これによってDashboardを取得できます。詳しくは/api/writeで後述します。
<post>ノードの中で private=”True” とXMLで指定された場合にプライベートなポストが可視になります。
Dashboardを読む: /api/dashboard
http://www.tumblr.com/api/dashboard に対してAuthenticated readでしたようにポストを読むことができます。使用できるパラメータは以下の通りです。
- email - アカウントのメールアドレス
- password - アカウントのパスワード
- start, num, type, filter(オプション) - /api/readと同じです。startの最大値は250です。
アウトプットはXML形式です。
Dashboardをキャッシュに大量に読み込むことがあるでしょう。リクエストは10秒ごとにしか実行できないことに注意してください。
もし限度を超えた大量の読み込みを行った場合、503エラーが返るかもしれません。あまり読み込みにがっつかないでください。
/api/write
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(オプション) - 以下のうちでひとつを指定することができます。
ポストの作成後にポストの状態を変更したい場合(例えばdraftをpublishedにしたり)、”ポストを編集する“を御覧下さい。いくつかの追加パラメータを指定することで、ポストを変更することができます。
Note : もしすでに存在するdraftやqueueのポストをpublishedに変更する場合などは、初めて状態をpublishedにしたときにIDが割り当てられます。
- send-to-twitter (オプション、投稿後にこの属性を変更することはできません) - TwitterとTumblrの連携を設定しているときに、Twitterに投稿するかどうかを以下のパラメータを用いて指定することができます。
このパラメータが設定されていない場合、TumblrのCustomizeスクリーンで”Send my Tumblr posts to Twitter“にチェックが入っているかどうかでTwitterに投稿されるかどうかが判定されます。
ポストのタイプ
有効なポストのタイプを、それらがサポートするパラメータと共に示します。
- regular - 以下のうちのどちらかが必要
- title
- body(HTMLが使用できる)
- photo - sourceかdataのどちらかを使用します。どちらも使用した場合、souceが優先されます。
- quote
- quote
- source (オプション)
- link
- conversation
- title (オプション)
- conversation
- video - embedとdataのどちらかを利用してください。どちらも利用することはできません。
- audio
ファイルのアップロードについて
上記に述べたような特定のパラメータを使用して、データをアップロードできます。アップロードの方式には、以下の二つの方式があります。
- multipart/form-data method。この方式はWebからデータをアップロードするときによく用いられる方式です。最大のサイズは、
- videoは50MB
- photoは10MB
- audioは10MB
オーバーヘッドの少ない方式ですので、こちらの方式をオススメします。
返り値
各種のリクエストに対して、標準的なHTTPのステータス値を返します。
- 201 Created - 成功です。作成されたポストのIDが返ってきます。
- 403 Forbidden - メールアドレスかパスワードが間違っています。
- 400 Bad Request - 少なくとも1つのエラーが発生しています。エラーはプレーンテキストで返ります。
PHPのサンプルコード
<?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を整数型で。
- type, private, format - これらの値は無視されます。省略してください。これらの値はポストの作成時に決めた値から変更することはできません。
- tags, generator, date - これらの値はオプションです。もし指定されていたら、もとの値を上書きします。省略された場合、これらの値は変更されません。
ポストの削除
ポストを編集するためには、 /api/write の認証済みのポストを作成してください。しかしポストは http://www.tumblr.com/api/delete に投げる必要があります。次のPOSTパラメータを付加してください。
- post-id - 削除したいポストのIDを整数型で。
すべてのコンテンツにかんするパラメータは無視されます。認証用のパラメータとポストのIDのみが必要です。
/api/authenticate
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
iPhoneアプリでユーザのDashboardが表示したい場合、Tumblrは既にiPhoneに最適化されたウェブサイトを表示することができます。http://www.tumblr.com/iphone
もしTumblrの外部にユーザのログイン情報を格納して、そこからログインしたいという場合、 http://www.tumblr.com/login にログインのHTTP POSTを投げることで実現できます。以下のパラメータが必要です。
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のログインシステム
ほとんどのアプリケーションで、ポストの作成、編集、読み込みを行うために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 のシステムは告知なく変更されることがあります。
変更
— Tumblr APIの使い方を勝手に和訳したもの - Coro-1729 (via netclip) (via funebot) (via plasticdreams) (via kuboji) (via skamio) (via yoichi13) (via petapeta) (via manmo)
１９７０年
ﾏｽｺﾞﾐ「静岡には大地震がくる！！さあこの防災グッズを買いましょう！！」
静岡「ふええ」
１９８０年
諸外国「静岡県は危険な土地だ 近寄ってはならない」
静岡「そ、そんなこと」
青森「ギャアアアアアアアアア！！！！！」
静岡「！」
１９９０年
ﾏｽｺﾞﾐ「静岡には大地震がくる！！さあこの防災グッズを買いましょう！！」
静岡「新開発された鉄筋をおすすめしていま
兵庫「ウワアアアアアアアアアアア！！！！」
静岡「 」ｶﾞｸｶﾞｸ
２０００年
ﾏｽｺﾞﾐ「静岡には大地震がくる！！さあこの防災グッズを買いましょう！！」
静岡「非常食を県民のみなさんにくばってきましｔ
新潟「ウウオアアアッー！！！！！」
静岡「ふぁ・・・」
２０１１年
静岡「最近、私は共同の地下シェルターの計画をですｎ
ＮＺ「アアアアアアアアアアアア！！！！！！」
静岡「ひええ」
静岡「海岸沿いの勾配、町全体の排水機関を強化したんです。これで諸国のような轍は踏みませ
宮城「ホ、ホアアッー！！！！」
静岡「あっ」
