Documents‎ > ‎Tumblr‎ > ‎

Tumblr APIリファレンス和訳(原文:2011/05/04 20:11:46時点)

この文書は、API | Tumblrを和訳したものです。同ページの2011/05/04 20:11:46時点のものを原文としています。
この文書を、Tumblr Terms of Serviceに準拠した個人的かつ非商用の利用として許諾される範囲として、またTumblrユーザーサポートへの確認のうえで公開しています。

文書名 Tumblr APIリファレンス和訳
原文 API | Tumblr
和訳者 塚本 牧生 <tsukamoto@gmail.com>
ライセンス Tumblr Terms of Serviceに準拠

なお、本ページには対象とした原文(翻訳開始時点)とGoogle翻訳者ツールキットでの和訳に使用した翻訳メモリが参考として添付されています。

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>
        <post type="answer" ... >
            <question>...</question>
            <answer>...</answer>
        </post>
        ...
    </posts>
</tumblr>

デフォルトでは最新の20記事が含まれています。オプションで以下のGETパラメータを渡すことができます:

  • start - 先頭記事番号を指定するオフセット。デフォルトは0です。
  • num - 取得する記事数。デフォルトは20で、最大値は50です。
  • type - 取得する記事のタイプ。未指定または空の場合は、すべてのタイプの記事が返されます。textquotephotolinkchatvideo、またはaudioのいずれかでなければなりません。
  • id - 取得する記事を指定するID。startnum、またはtypeの代わりに使用します。
  • filter - テキストコンテンツに対して実行するフィルタの代替。指定できる値:
    • text - プレーンテキストのみ。HTMLなし。
    • none - 後処理なし。作成者が入力したものがそのまま出力になります。(注:一部の作成者はMarkdown形式で書きますが、このオプションが使用されている時にはHTMLの変換は行われません。)
  • tagged - このタグを持つ記事を、時系列の逆順(最新のものが最初)で取得します。時系列順(古いものを最初)にしたい時はchrono=1オプションを指定します。
  • search - このクエリで記事を検索します。
  • state認証後の読み込みが必要) - draftqueue、またはsubmissionを指定すると、それぞれの状態の記事をリストします。

フィードの詳細な例は、Marco.orgデモブログのRead APIライブを参照してください。FirefoxのようなXMLを見やすく出力するブラウザが推奨されます。

JSON出力

Read APIの呼び出しに、/api/readの代わりに/api/read/jsonを使うことで、出力はJavascript変数名tumblr_api_readにアサインされたJSON形式で送出されます。すべての標準的なRead APIのパラメータを受け取れるのに加え:

  • 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>

参照を簡単にするために、人間が読める形式の配列構造のマップを見たいときは、GETパラメータとしてdebug=1を渡します。出力はのPHPのprint_r()関数のようになります。

認証後の読み込み

/api/readにプライベートな記事を含めるには、/api/readへのPOSTリクエストを使用し、そのブログの参照が許可されているアカウントのemailpasswordをパラメータに含めます(後述の/api/writeを参照してください)。

プライベートな記事は、結果のXML内で、それぞれの<post>ノード上に追加アトリビュートprivate="true"と示されています。

ダッシュボード読み込み:/api/dashboard

ダッシュボードの記事を読むには、http://www.tumblr.com/api/dashboard認証後の読み込みを以下のパラメータとともに実行します:

  • email - アカウントの電子メールアドレスを入力します。
  • password - アカウントのパスワードを入力します。
  • startnumtypefilter(オプション) - 前述の/api/readと同じです。startの最大値は250です。
  • likes(オプション) - 1または0、デフォルトは0。1の場合、likeされている記事はliked="true"アトリビュートを持ちます。
出力は/api/readのような形式のXMLです。

ダッシュボード読み込みは、キャッシュされたコンテンツを返すことがあります。リクエスト頻度は10秒ごとに1回に制限されます。

この頻度を超えているか、サービスの負荷が大きい時は、HTTP 503 レスポンスステータスコードを受取ります。 か、またはレート制限を超えている場合は、サービスの負荷が大きい、応答のHTTP 503ステータスコードを受け取ることがあります。この一時障害をアプリケーションが確実に正しく扱えるようにしてください。

Likeされた記事

likeされた記事を読むには、http://www.tumblr.com/api/likes認証後の読み込みを以下のパラメータとともに実行します:

  • email - アカウントの電子メールアドレスを入力します。
  • password - アカウントのパスワードを入力します。
  • startnumfilter(オプション) - 前述の/api/readと同じです。startの最大値は1000です。
出力は/api/readのような形式のXMLです。

記事のLike、Likeの取り消し

Likeを投稿するには、http://www.tumblr.com/api/likeへのPOSTリクエストを、以下のパラメータを使用して実行します:

  • email - アカウントの電子メールアドレス。
  • password - アカウントのパスワード。
  • post-id - likeする記事のIDの数値。
  • reblog-key - /api/readまたは/api/dashboardが返すXMLで記事に指定されているreblog-keyの値。
Likeを取り消す投稿をするには、代わりにhttp://www.tumblr.com/api/unlikeへ同様のパラメータで同様の操作を行います。どちらの操作も成功時にはHTTP 200ステータスコードを、入力データが不正なときは400、認証または権限の問題があるときは403、あるいは記事が見つからないかreblog-keyの値が不正なときは404を返します。

ページの読み込み:/api/pages

あなたのtumblelogのページを読むには、http://(you).tumblr.com/api/pagesを取得すれば、カスタマイズ画面で「ページへのリンクを表示する」オプションを有効にしたすべてのページを構造化されたXMLのコピーとして取得できます。

「ページへのリンクを表示する」オプションにかかわらずすべてのページを含めるには、認証後の読み込みを同様の方式でhttp://(you).tumblr.com/api/pages実行します。

ページの読み込みはキャッシュされたコンテンツを返すことがあります。リクエスト頻度は10秒ごとに1回に制限されます。

/api/write

Write APIは非常に単純なHTTPのインターフェイスです。記事を作成するには、http://www.tumblr.com/api/writeに以下のパラメータw使用してPOSTリクエストを送ります:

  • email - アカウントの電子メールアドレス。
  • password - アカウントのパスワード。
  • type - 記事のタイプ。
  • (コンテンツのパラメータ) - これらは記事のタイプによって異なります。
  • generator(オプション) - 追跡と統計情報のための、リクエストを作成したアプリケーションの"John's Widget 1.0"のような簡潔な記述。64文字以下でなければなりません。
  • 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。URLフレンドリーな書式が自動的に適用されます。最長は55文字です。
  • state(オプション) - 以下の値のうち一つ:
    • published(デフォルト)
    • draft - tumblelogの下書きフォルダに保存します。
    • submission - 検討のためにtumblelogにのメッセージフォルダに追加します。
    • queue - 数分後または数時間後に自動的に公開されるように、tumblelogのキューに追加します。代わりに将来の特定の時刻に公開されるようにするには、追加パラメータとしてpublish-onにtumblelogのローカルタイムで日時記述を指定します(例えば、publish-on=2010-01-01T13:34:00)。日付形式が理解できない場合は、401エラーが返され、記事は作成されません。

    例えばdraftからpublishedになど、既存の記事の状態を変更するには、編集処理にしたがい、stateパラメータの新しい値を渡します。

    注:もし記事が以前にドラフト、キュー、またはsubmission記事として保存されている場合、published状態を設定した最初のタイミングで新しい記事IDがアサインされます。

  • send-to-twitter(オプション、編集時は無視されます) - もしtumblelogのTwitter連携が有効になっていれば、以下の値のうち一つ:
    • no(デフォルト) - Twitterにこの記事を送信しません。
    • auto - 自動姿勢されたこの記事のサマリをつけてTwitterに送信します。
    • (any other value) - この記事のカスタムメッセージをTwitterに送信します。

    このパラメータが指定されていない場合、カスタマイズ画面で「Tumblrでの投稿をTwitterにも送信」チェックボックスがチェックされていれば、APIが作成した記事はTwitterに送信されます。

記事のタイプ

typeパラメータには適切な値と、各typeがサポートする関連するパラメータがあります。

  • regular - 少なくとも一つが必要:
    • title
    • body (HTMLが許可されている)
  • photo - sourceまたはdataのいずれかが必須ですが、両方は不要です。両方指定されている場合は、sourceが使用されます。
    • source - にコピーする写真のURLを指定します。これはローカルファイルやイントラネット上の場所ではなく、Webアクセス可能なURLであることが必要です。
    • data - 画像ファイルを指定します。後述のファイルのアップロードを参照。
    • caption(オプション、HTMLが許可されている)
    • click-through-url(オプション)
  • quote
    • quote
    • source(オプション、HTMLが許可されている)
  • link
    • name(オプション)
    • url
    • description(オプション、HTMLが許可されている)
  • conversation
    • title(オプション)
    • conversation
  • video - embedまたはdataのいずれかが必須ですが、両方は不要です。
    • embed - 動画を埋め込むための完全なHTMLコードか、あるいはYouTubeの動画ページのURLのいずれか。
    • data - Vimeoにアップロードするビデオファイル。後述のファイルのアップロードを参照。
    • title(オプション) - Vimeoへのアップロードにのみ適用されます。
    • caption(オプション、HTMLが許可されている)
  • audio
    • data - オーディオファイル。MP3またはAIFF形式でなければなりません。後述のファイルのアップロードを参照。
    • externally-hosted-url(オプション、dataを置き換え) - Tumblrにコピーを持ちアップロードされたファイルをホストする代わりに、この外部でホストされたオーディオファイルのURLを使用する記事を作成します。MP3形式でなければなりません。外部ホストファイルにはサイズや時間の制限は課されていません。
    • caption(オプション、HTMLが許可されている)

ファイルのアップロード

dataパラメータが上記で指定されていれば、ファイルのアップロードがで行うことができます。あなたは一般的なエンコードのいずれかの方法を使用することができます:

  • Webフォームのファイルアップロードボックスのようなmultipart/form-data方式。最大サイズ:
    • 動画は50MB
    • 写真は10MB
    • オーディオは10MB
    これはオーバーヘッドがずっと少ないので、こちらが推奨されます。
  • 通常のPOSTメソッドで、ファイルの全バイナリコンテンツを他のPOST変数と同様にURLエンコード。最大サイズ:
    • 動画は5MB
    • 写真は5MB
    • オーディオは5MB

返り値

各リクエストに対して芳醇のHTTPステータスコードと、追加でプレーンテキストのレスポンスを返します。

  • 201 Created - 成功!新しく作成された記事のIDが返されます。
  • 403 Forbidden - あなたの電子メールアドレスまたはパスワードが間違っていました。
  • 400 Bad Request - 記事を保存しようとした際、少なくともひとつのエラーがありました。エラーはプレーンテキストで、1行に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パラメータが正しくエンコードされていることを確認してください。もし質問があれば、どうぞTumblr Supportにお送りください。

記事の編集

記事を編集するには、前述したように/api/writeリクエストを作成し、追加のPOSTパラメータを渡します:

  • post-id - 編集したい記事IDの整数値。

/api/writeにするのと同様のすべてのパラメータを渡し、新しい値を指定しますが、以下の例外があります:

  • typeprivateformat - これらは無視され、省略することができます。これらの値は、記事の作成後に変更することはできません。
  • tagsgeneratordate - これらはオプションです。指定されている場合、新しい値が以前の値を上書きします。省略された場合、値は変更されません。

値を変更しない場合でも、その記事のタイプに対するすべてのパラメータ(例えばtext記事に対してはtitlebody)を渡さなければいけません

記事の削除

記事を削除するには、前述したように/api/writeリクエストを作成しますが、http://www.tumblr.com/api/deleteにPOSTし、追加のPOSTパラメータを渡します:

  • post-id - 削除したい記事IDの整数値。

すべてのコンテンツに関連するパラメータは無視され、省略することができます。認証パラメータとpost-idだけが必須です。

記事のリブログ

記事をリブログするには、http://www.tumblr.com/api/reblogへのHTTP POSTリクエストを作成し、以下のPOSTパラメータを渡します:

  • email - アカウントの電子メールアドレス。
  • password - アカウントのパスワード。
  • post-id - リブログしたい記事IDの整数値。
  • reblog-key - 記事の/api/readXMLデータからのreblog-keyの値。
  • comment(オプション) - リブログに追加するコメント的なテキスト、HTML、またはMarkdown文字列(format参照)。これは、自動的に生成されたりブログされたコンテンツ構成の下に表示されます。2000文字まで(バイトではなく、UTF-8文字として)が許されます。chat記事ではこのフィールドはサポートされておらず、無視されます。
  • as(オプション) - 元の記事と異なる形式でリブログします。textlink、およびquoteがサポートされています。

/api/writeformatgroupパラメータもサポートされています。

/api/authenticate

http://www.tumblr.com/api/authenticateへのPOSTリクエストをemailpasswordパラメータのみで送り、認証情報の確認とユーザーへの制限やブログといったアカウント情報を取得します。

出力はXMLです。<tumblr>ルート要素は、一つの<user>子ノードと、加えてブログメンバーシップごとに一つの<tumblelog>子要素を含みます。

<user>アトリビュート:

  • can-upload-audio:ユーザーが現在MP3オーディオファイルをアップロードできる場合は"1"。
  • can-upload-aiff:ユーザーが現在AIFFオーディオファイルをアップロードできる場合は"1"。
  • can-upload-video:ユーザーが現在ビデオをアップロードできる場合は"1"。ユーザーがTumblr経由でVimeoにログインしている必要があります。
  • max-video-bytes-uploaded:ユーザーの次のビデオアップロードに対する最大のバイト数を示します。ユーザーがTumblr経由でVimeoにログインしている必要があります。

<tumblelog>アトリビュート:

  • title
  • typepublicまたはprivate
  • private-id(プライベートブログのみ):プライベートのブログのID番号。/api/writegroupパラメータにこの値を使用します。
  • name(公開ブログのみ)
  • url(公開ブログのみ)
  • avatar-url(公開ブログのみ)
  • is-primary:ユーザーのプライマリ/デフォルトのブログの時にはyes

include-theme=1パラメータを渡すこともでき、これは以下のサブ要素を<tumblelog>要素に追加します:

  • <description>:カスタマイズ画面からの説明の値。
  • <custom-css>:カスタマイズ画面からのカスタムCSSの値。
  • <theme-source>:カスタマイズ画面からの仕様中のカスタムテーマのカスタムHTMLの値。これは、カスタムテーマのコードをバックアップするためのツールを書くのに便利です。

廃止予定

以下のactionの値は廃止予定で、将来削除されます。

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

これらの機能は、現在のところ/api/authenticateに含まれています。

iPhone

ダッシュボードを表示する必要のあるiPhoneアプリには、Tumblrはhttp://www.tumblr.com/iphoneでiPhoneに最適化されたビューを提供しています。

ユーザーが個別にTumblrにログインしなくて済むようにするためには、ユーザーの認証情報を既に持っているのであれば、http://www.tumblr.com/loginにフォームエンコードされた(form-encoded)パラメータを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];
ċ
TumblrAPI.tmx
(96k)
Makio Tsukamoto,
2011/05/04 11:36
ċ
tumblr_api_20110504_201146.htm
(26k)
Makio Tsukamoto,
2011/05/04 11:36