Tumblr APIでwebサービスを作りたい全ての人に向けて書きました

2014.07.02(Wed) 08:00
WEB制作

ブログ、メディアミックスとして多くの人、企業に愛されているTumblr。今回は、この「Tumblr APIの使い方」をまとめて、日本語マニュアルを作ってみました。TumblrのAPIで作ったwebサービスって、なかなか見かけませんが、このAPIの豊富な機能を利用すれば、何か面白いものが作れるんじゃないでしょうか？

「APIがよく分からない…」という方でも、「動く面白さ」を体験してもらえるよう、コピペで使える簡単なサンプルコードを用意しています。読み進めながら一緒に実行すれば、必ず動かせるはずです。ぜひ、この機会にTumblrのAPIで何か始めてみてはいかがでしょうか!?

1アプリケーションを登録する

TumblrのAPIを利用するために、まずは「アプリケーションの登録」を行なう必要があります。それによって、APIの利用に必要なコンシューマーキー、シークレットキーを取得しましょう。

1-1アカウントを取得する

アプリケーションを登録するには、Tumblrのユーザーアカウントが必要です。まだ持っていない方は、下記のページから取得して下さい。ブログなど既に持っている方は、そのIDをそのまま利用できます！

1-2アプリケーションを登録する

アカウントを取得したら、早速アプリケーションを登録しちゃいましょう。下記のページにアクセスして下さい。まだの場合は、ログイン画面に移動するので、Tumblrのアカウントでログインして下さいね！

Applications

「Applications」の画面に移動しました。ここは登録したアプリケーションを管理するターミナルとなるページですのでブックマークしておきましょう。アプリの一覧が表示されるはずですが、1件も登録していないので、まだ何もありません。「+アプリを登録する」をクリックして、アプリの登録を始めましょう！

Register your application

アプリの情報をフォームに入力します。今の段階では、APIのテスト用に利用するだけなので、上記サンプルのように、大まかな内容でかまいません。1点だけ、「Default callback URL」には、後ほど「アプリ認証」を行なうために作成するPHPプログラムの設置先となるURLを入力して下さい。問題がなければ「Register」というボタンをクリックします。

1-3コンシューマーキー、シークレットキーを確認する

登録が完了すると、アプリ一覧の画面に戻ります。登録したアプリが一覧に加わっているのを確認できると思います。アプリ名の下に小さく表示されている「OAuth Consumer Key」と、さらにその下の「Show secret key」をクリックすると表示される「Secret Key」が目的の2つのキーです。誰にも知られないように管理(メモ)して下さい。

2コンシューマーキー、シークレットキーを使ってOAuth認証をする

前章ではアプリ登録を通して、APIの利用に必要なコンシューマーキー、シークレットキーを取得しました。続いて、ユーザーのデータを読み込んだり、書き込んだりするために必要な「アクセストークン」「アクセストークンシークレット」を取得しましょう！これらを取得するには、アプリ認証を行なう必要があります。

2-1Tumblrのアプリ認証について

Tumblrのアプリ認証に関しては、下記ページの公式ドキュメントをご参考下さい。

Tumblrのアプリ認証は、OAuth1.0という規格を採用しています。Twitterやはてなと同じ形式です。これに関しては、既に、より簡易なOAuth2.0が登場するなどしていて、これから増えていくものでもないので、厳密に学ぶ必要性は低いと思います。興味のある方は2つ目のリンクをご参考下さい。

2-2TumblrでOAuth認証をするPHPのサンプルプログラム

OAuth1.0認証を利用して、Tumblrでアプリ認証を行なうためのサンプルプログラムを紹介します。

OAuth1.0認証を通したリクエストをするための関数

まず、下記はOAuth1.0認証方式でAPIリクエストを行なうための関数です。この2つの関数をいつでも読み込めるように、PHPプログラム内に配置しておいて下さい。

$consumer_key、$secret_key、$callback_urlをそれぞれ設定して下さい。$callback_urlはアプリ登録の際に設定した「Default callback URL」と一致させる必要があります！

//OAuthリクエスト用の関数
function tumblr_oauth($request_url,$method,$parameters){
	$consumer_key = '';		//コンシューマーキー
	$secret_key = '';	 //シークレットキー
	$callback_url = '';		//このプログラムのURL
	
	global $http_response_header;
	$oauth_parameters = array(
		'oauth_callback' => $callback_url,
		'oauth_consumer_key' => $consumer_key,
		'oauth_nonce' => microtime(),
		'oauth_signature_method' => 'HMAC-SHA1',
		'oauth_timestamp' => time(),
		'oauth_version' => '1.0'
	);
	if(isset($parameters['oauth_token'])){$oauth_parameters['oauth_token'] = $parameters['oauth_token'];unset($parameters['oauth_token'],$oauth_parameters['oauth_callback']);}
	if(isset($parameters['oauth_token_secret'])){$oauth_token_secret = $parameters['oauth_token_secret'];unset($parameters['oauth_token_secret']);}else{$oauth_token_secret = '';}
	if(isset($parameters['oauth_verifier'])){$oauth_parameters['oauth_verifier'] = $parameters['oauth_verifier'];unset($parameters['oauth_verifier']);}
	$tail = ($method === 'GET') ? '?'.http_build_query($parameters,'','&',PHP_QUERY_RFC3986) : '';
	$all_parameters = array_merge($oauth_parameters,$parameters);
	ksort($all_parameters);
	$base_string = implode('&',array(rawurlencode($method),rawurlencode($request_url),rawurlencode(http_build_query($all_parameters,'','&',PHP_QUERY_RFC3986))));
	$key = implode('&',array(rawurlencode($secret_key),rawurlencode($oauth_token_secret)));
	$oauth_parameters['oauth_signature'] = base64_encode(hash_hmac('sha1', $base_string, $key, true));
	$data = array('http'=>array('method' => $method,'header' => array('Authorization: OAuth '.http_build_query($oauth_parameters,'',',',PHP_QUERY_RFC3986),),));
	if($method !== 'GET') $data['http']['content'] = http_build_query($parameters);
	$data = @file_get_contents($request_url.$tail,false,stream_context_create($data));
 
	return $data ? $data : false;
}

//GETクエリ形式の文字列を配列に変換する関数
function get_query($data){
	$ary = explode("&",$data);
	foreach($ary as $items){
		$item = explode("=",$items);
		$query[$item[0]] = $item[1];
	}
	return $query;
}

アプリ認証を行なうためのプログラム

前項で紹介した関数を利用して、アプリ認証を行なうためのサンプルプログラムが、下記です。これを、アプリ登録の時に「Default callback URL」に設定したのと同じPHPファイル名で保存して下さい。くどいのですが、先ほど紹介した2つの関数を読み込めるように、同じファイル内にコピーするなり、別ファイルにしてrequireで読み込むなりしておいて下さい。

<?php
//セッションスタート
session_start();
 
//アクセストークンを取得
if(isset($_GET['oauth_token']) && is_string($_GET['oauth_token']) && !empty($_GET['oauth_token']) && isset($_GET['oauth_verifier']) && is_string($_GET['oauth_verifier']) && !empty($_GET['oauth_verifier'])){
 
	//アクセストークンをリクエストする
	$query = get_query(tumblr_oauth('http://www.tumblr.com/oauth/access_token','POST',array('oauth_token'=>$_GET['oauth_token'],'oauth_token_secret'=>$_SESSION['oauth_token_secret'],'oauth_verifier' => $_GET['oauth_verifier'])));
 
	//セッション終了
	$_SESSION = array();
	session_destroy();
 
	//エラー判定
	if(!$query){
		echo 'アクセストークンの取得に失敗しました…。';
		exit;
	}

	//情報の整理
	$token = $query['oauth_token'];
	$secret = $query['oauth_token_secret'];
 
	//出力する
	echo "あなたのアクセストークンは{$token}で
アクセストークンシークレットは{$secret}です！";
	exit;
}
 
//リクエストトークンの取得
if(!$query = get_query(tumblr_oauth('http://www.tumblr.com/oauth/request_token','POST',array()))){
	echo 'リクエストトークンの取得に失敗しました…。もしかしたら「$consumer_key」「$secret_key」「$callback_url」の設定が違っているかもしれません…。';
	exit;
}
 
//セッションに保存
session_regenerate_id(true);
$_SESSION['oauth_token_secret'] = $query['oauth_token_secret'];
 
//認証画面へリダイレクト
header('Location: http://www.tumblr.com/oauth/authorize?oauth_token='.$query['oauth_token']);
exit;

2-3Tumblrのアプリ認証のイメージ

サンプルプログラムを起動した際のアプリ認証の流れを紹介します。正常に動いているかの確認にご利用下さい。一緒に進んでいきましょう。

アプリの許可

まず、上記のように、アプリがユーザーのデータにアクセスしてもいいか確認する画面が現れます。アプリ登録の際に設定したEメールやアイコンはここで、ユーザーに公開されます。問題がなければ、ユーザーはここで「許可」をクリックします。

アクセストークン、アクセストークンシークレットの発行

許可をすると、発行された「アクセストークン」「アクセストークンシークレット」がブラウザに出力されます。今回はAPIのテストを行なうのが目的なので、ブラウザに出力していますが、不特定多数のユーザー向けにwebサービスを制作する場合は、この「アクセストークン」「アクセストークンシークレット」をデータベースに保存するなどのシステム作りも必要になってきますねー。

2-4関数[tumblr_oauth()]の使い方

サンプルで紹介した関数、tumblr_oauth()は、Tumblrの各APIで「OAuth1.0認証を通したリクエスト」を行なうのに利用できます。次のように引数を指定して関数を呼び出して下さい。なお、パラメータには必ず、oauth_token(アクセストークン)とoauth_token_secret(アクセストークンシークレット)を加えて下さいね。

tumblr_oauth(
	第1引数：{リクエストURL},
	第2引数：{リクエストメソッド},
	第3引数：{パラメータ(連想配列)}
)

3色々なユーザーデータを取得してみよう！

TumblrのAPIは種類が多岐に渡っていて、とても全てを紹介できる量ではないのですが…、この章からは少しずつ、APIの使い方を紹介していきます。まずは、ユーザーデータを取得してみましょう！ユーザーデータの取得についての公式ドキュメントは下記ページをご覧下さい。

3-1ユーザープロフィールを取得する

まずはユーザープロフィールを取得してみます。プロフィールデータを取得するためには、下記URLに、GETメソッドでリクエストを送ります。OAuth認証を通す必要があるので、前章で紹介したtumblr_oauth()を利用することになります。指定するオプションパラメータはありません。

[GET] https://api.tumblr.com/v2/user/info

取得できるJSONデータ

ユーザーデータAPIでは下記のJSONデータを取得できます。Tumblrは1ユーザーが複数のブログを所有することができます。blogs内に、所有している各ブログのデータが配列形式で格納されています。主要なデータには青文字でコメントを付けてあります！

{
  "meta": {
    "status": 200, //ステータスコード
    "msg": "OK"
  },
  "response": {
    "user": {
      "name": "arayutw", //ID
      "likes": 3, //スキをした回数
      "following": 3, //フォロー数
      "default_post_format": "html",
      "blogs": [
        {
          "name": "arayutw", //ブログID
          "url": "http://arayutw.tumblr.com/", //ブログURL
          "followers": 1, //フォロワー数
          "primary": true, //主ブログか？
          "title": "おためしブログ", //ブログ名
          "description": "テストで作ったブログです！", //ブログ説明文
          "admin": true,
          "updated": 1404128526, //最終更新時刻
          "posts": 6, //投稿数(リブログ含む)
          "messages": 0, //メッセージ数
          "queue": 0, //予約記事数
          "drafts": 0, //下書き記事数
          "share_likes": true,
          "ask": false, //質問を受付中か？
          "tweet": "N", //Twitterと連携しているか？
          "facebook": "N", //Facebookと連携しているか？
          "facebook_opengraph_enabled": "N",
          "type": "public"
        },
        {
          "name": "subblog", //サブブログのID
          ...
        },
        ...
      ]
    }
  }
}

ユーザーデータを取得するPHPのサンプルプログラム

以上を踏まえた、ユーザーデータを取得するためのサンプルプログラムが、下記の通りです。6行目でtumblr_oauth()を利用しているので、この関数を読み込めるようにしておいて下さい。取得した「アクセストークン」「アクセストークンシークレット」を$access_token、$access_token_secretにセットして、プログラムを起動してみましょう！

//アクセストークンとアクセストークンシークレット
$access_token = 'gClZEXQRZ08cqC3Hpp96o0aE6fCFOVjoowaVl3UacCsLeIobM6';
$access_token_secret = '3oamseb0xFaWzGWekIg3n0dMUl6w0N8kdrQvFnBPwrB1pVYTfA';
      
//JSONデータを取得し、オブジェクト形式に変換する
$json = tumblr_oauth('https://api.tumblr.com/v2/user/info','GET',array('oauth_token'=>$access_token,'oauth_token_secret'=>$access_token_secret));
$obj = json_decode($json);

//ユーザー名・スキをした回数・フォロー数
$name = $obj->response->user->name;
$likes = $obj->response->user->likes;
$follow = $obj->response->user->following;

//出力
echo "<h1>{$name}さんの情報</h1><p>スキをした回数：{$likes}回<br/>フォロー数：{$follow}ブログ</p>";

//個々の所有ブログの情報を読み込む
foreach($obj->response->user->blogs as $item){
	//ブログ名・ブログURL・フォロワー数・最終更新時刻(ついでに整形)・投稿数
	$blog_name = $item->title;
	$blog_url = $item->url;
	$blog_follower = $item->followers;
	$blog_updated = date('Y/m/d H:i',$item->updated);
	$blog_posts = $item->posts;

	//出力
	echo "<h2>{$blog_name}</h2><p>フォロワー数：{$blog_follower}人<br/>最終更新時刻：{$blog_updated}<br/>投稿数：{$blog_posts}</p>";
}

プログラムの実行結果

プログラムを実行すると、上記の通り、APIを通してユーザーデータを取得し、ブラウザに表示することができます。サンプルを見ると、如何に私がTumblrをやっていないのかが分かってしまいますね…。

3-2全体の型となるPHPサンプルプログラム

プロフィールの他にも、ユーザーに関する様々なデータを取得することができるので、ここからは、それらを紹介していきます。その前に…、型となるサンプルプログラムを紹介します。これから紹介していくサンプルリクエストを、7〜9行目の部分と差し替えて、使い分けてみて下さい！

「ブログホスト」の$hostは「予約記事」「下書き記事」「寄稿記事」の取得で利用します。対象ブログのURLのホスト部分を指定して下さい。例えば、私のブログ(http://arayutw.tumblr.com/)の場合は、arayutw.tumblr.comの部分になります。

//アクセストークン、アクセストークンシークレット・ブログホスト
$access_token = '';
$access_token_secret = '';
$host = 'arayutw.tumblr.com';

//JSONデータを取得
$json = tumblr_oauth(
	...
);

//JSONデータをブラウザに出力
echo '<pre>';
echo json_encode(json_decode($json),JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
echo '</pre>';

3-3ダッシュボードの記事一覧を取得する [dashboard]

ユーザーのホーム画面に表示されている記事一覧を取得します。Twitterでいうタイムラインのことですねー。リクエストURLは下記の通りです。

[GET] https://api.tumblr.com/v2/user/dashboard

下記のオプション・パラメータを指定することで、取得する記事を絞り込むことができます。

パラメータ	説明
limit	取得件数 - [初期値] 20 - [最大値] 20
offset	オフセット(取得開始位置) - [初期値] 0
type	取得する投稿タイプ - [初期値] 全て - [text] テキスト - [quote] 引用 - [photo] 画像 - [link] リンク - [chat] チャット - [audio] 音声 - [video] 動画 - [answer] アンサー
since_id	記事IDを指定すると、それ以降に投稿された記事のみを取得
reblog_info	リブログの情報を取得するかを[true / false]で指定 - [初期値] false ※真偽値ではなく、文字列として指定(引用符で囲む)
notes_info	Notes(履歴)の情報を取得するかを[true / false]で指定 - [初期値] false ※真偽値ではなく、文字列として指定(引用符で囲む)

「Notes」って何？

Noteとは、各記事のフッターにある「リアクション」のデータです。誰がスキをしたとか、リブログしたとか、ああいったデータを指します。

サンプルリクエスト

tumblr_oauth()を利用したリクエストサンプルです。7〜8行目では、オプション・パラメータを使って、画像タイプの投稿(type=photo)を5件だけ(limit=5)と指定しています。

$json = tumblr_oauth(
	'https://api.tumblr.com/v2/user/dashboard',
	'GET',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'type'=>'photo',
		'limit'=>5,
	)
);

取得できるJSONデータ

postsプロパティの中に、配列形式で「各記事のJSONデータ」が含まれている形になります。記事のJSONデータの構造については、その内容が膨大なことから、1つの章を設けて詳しく解説しています。「記事のJSONデータについて」をご参考下さい。

{
 "meta": {
  "status": 200, //ステータスコード
  "msg": "OK"
 },
 "response": {
  "posts": [ //記事のJSONデータ(配列)
   {
    "blog_name": "arayutest",
    ...
   },
   ...
  ]
 }
}

3-4予約状態の記事一覧を取得する [queue]

予約設定している記事一覧を取得することができます。「キュー」と言われているものです。下記のURLに、GETメソッドでリクエストを送ります。

[GET] https://api.tumblr.com/v2/blog/{ブログホスト}/posts/queue

下記のオプション・パラメータを指定することで、取得する記事を絞り込むことができます。

パラメータ	説明
limit	取得件数 - [初期値] 20 - [最大値] 20
offset	オフセット(取得開始位置) - [初期値] 0
filter	フィルタリング - [初期値] raw - [text] プレインテキストで取得 - [raw] HTMLを反映して取得

サンプルリクエスト

下記が予約状態の記事一覧を取得するリクエストのサンプルです。$hostを設定して下さいね。

$json = tumblr_oauth(
	'https://api.tumblr.com/v2/blog/{$host}/posts/queue',
	'GET',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
	)
);

取得できるJSONデータについて

「ダッシュボードの記事一覧を取得した時のJSONデータ」と全く同じ構造です。

3-5ドラフト(下書き)状態の記事一覧を取得する [draft]

ドラフト(下書き)状態の記事一覧を取得することができます。下記のURLに、GETメソッドでリクエストを送って下さい。

[GET] https://api.tumblr.com/v2/blog/{ブログホスト}/posts/draft

下記のオプション・パラメータを指定することで、取得する記事を絞り込むことができます。予約状態の記事を取得した時と違い、ページングにはoffsetではなく、before_idというパラメータを利用するのでご注意下さい。この違いは、ちょっと謎仕様ですよね…。

パラメータ	説明
before_id	このIDよりも、後にある記事のみを取得
filter	フィルタリング - [初期値] raw - [text] プレインテキストで取得 - [raw] HTMLを反映して取得

サンプルリクエスト

下記が下書き状態の記事一覧を取得するリクエストのサンプルです。$hostを設定して下さいね。

$json = tumblr_oauth(
	'https://api.tumblr.com/v2/blog/{$host}/posts/queue',
	'GET',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
	)
);

取得できるJSONデータについて

「ダッシュボードの記事一覧を取得した時のJSONデータ」と全く同じ構造です。

3-6ゲスト投稿の記事一覧を取得する [submission]

ブログにゲストが寄稿した記事一覧を取得することができます。それには、下記のURLにGETメソッドでリクエストを送って下さい。

[GET] https://api.tumblr.com/v2/blog/{ブログホスト}/posts/submission

指定できるパラメータです。「予約状態の記事」を取得した時とは違って、limitを指定することができない点にご注意下さい。「予約」「下書き」「寄稿」で、パラメータが違うのは、最初のうちはちょっと混乱しそうですねー。

パラメータ	説明
offset	オフセット(取得開始位置) - [初期値] 0
filter	フィルタリング - [初期値] raw - [text] プレインテキストで取得 - [raw] HTMLを反映して取得

サンプルリクエスト

こちらが、寄稿の記事一覧を取得するリクエストのサンプルです。$hostを設定して下さいね。

$json = tumblr_oauth(
	'https://api.tumblr.com/v2/blog/{$host}/posts/submission',
	'GET',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
	)
);

取得できるJSONデータについて

「ダッシュボードの記事一覧を取得した時のJSONデータ」と全く同じ構造です。

3-7スキを付けた記事一覧を取得する [likes]

下記URLにGETメソッドのリクエストを送ることで、ユーザーがスキを付けた記事の一覧を取得することができます。

[GET] https://api.tumblr.com/v2/user/likes

下記のオプション・パラメータを指定することで、取得する記事を絞り込むことができます。

パラメータ	説明
limit	取得件数 - [初期値] 20 - [最大値] 20
offset	オフセット(取得開始位置) - [初期値] 0

サンプルリクエスト

tumblr_oauth()を利用したリクエストサンプルです。7行目では、オプションパラメータを使って5件だけ取得しています。

$json = tumblr_oauth(
	'https://api.tumblr.com/v2/user/likes',
	'GET',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'limit'=>5,
	)
);

取得できるJSONデータ

取得できるJSONデータの構造は、ダッシュボードのものとほとんど変わりません。postsではなく、liked_postsプロパティに、各記事のJSONデータが含まれている点にご注意下さい。また、スキをしている総数を表すliked_countプロパティが存在します。各記事のJSONデータの構造に関しては、「記事のJSONデータについて」の章をご参考下さい。

{
 "meta": {
  ...
 },
 "response": {
  "liked_posts": [ //記事のJSONデータ(配列)
   ...
  ]
  "liked_count": 4 //スキをした回数
 }
}

3-8フォローしているブログ一覧を取得する [following]

そのユーザー(アクセストークンの持ち主)がフォローしているブログの一覧を取得することができます。下記のURLにGETメソッドでリクエストを送ります。

[GET] https://api.tumblr.com/v2/user/following

パラメータについて

下記のオプション・パラメータを指定することで、取得する記事を絞り込むことができます。

パラメータ	説明
limit	取得件数 - [初期値] 20 - [最大値] 20
offset	オフセット(取得開始位置) - [初期値] 0

サンプルリクエスト

tumblr_oauth()を利用したリクエストサンプルです。7〜8行目では、オプションパラメータを使って11〜20件目(2ページ目)を取得しています。

$json = tumblr_oauth(
	'https://api.tumblr.com/v2/user/following',
	'GET',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'limit'=>10,
		'offset'=>10,
	)
);

取得できるJSONデータ

下記のJSONデータを取得できます。blogsプロパティに、フォローしているブログのJSONデータが配列形式で含まれる形です。

{
 "meta": {
  "status": 200, //ステータスコード
  "msg": "OK"
 },
 "response": {
  "total_blogs": 2, //フォローしてるブログ数
  "blogs": [
   {
    "name": "nihongo", //ブログID
    "title": "Tumblr Nihongo", //ブログ名
    "description": "Tumblrスタッフが送る公式ブログフィードです。", //ブログ概要
    "url": "http://nihongo.tumblr.com/", //ブログURL
    "updated": 1403823643 //ブログ最終更新時刻
   },
   ...
  ]
 }
}

4ブログデータを取得してみよう！

前章までは「ユーザー」に関するデータを取得しました。この章では、「ブログ」に関するデータを取得する方法について、紹介します。

4-1ブログのプロフィールを取得する

まずはブログのプロフィールを取得してみましょう。下記のURLにGETメソッドでリクエストします。「ブログホスト」は、http://arayutw.tumblr.com/の赤文字部分です。

[GET] https://api.tumblr.com/v2/blog/{ブログホスト}/info?api_key={コンシューマーキー}

取得できるJSONデータ

blogプロパティに、ブログのプロフィールデータが格納されています。

{
 "meta": {
  "status": 200, //ステータスコード
  "msg": "OK"
 },
 "response": {
  "blog": {
   "title": "あらゆ on Tumblr", //ブログ名
   "name": "arayutw", //ブログID
   "posts": 7, //総投稿数
   "url": "http://arayutw.tumblr.com/", //ブログURL
   "updated": 1404158106, //最終更新時刻
   "description": "", //ブログ概要
   "ask": false, //質問を受け付けるか？
   "ask_page_title": "Ask me anything",
   "ask_anon": false,
   "is_nsfw": false, //成人コンテンツか？
   "share_likes": true,
   "likes": 6
  }
 }
}

サンプルプログラム

以上を踏まえたサンプルプログラムです。$api_keyには、アプリ登録の際に取得した「コンシューマーキー」をセットして下さい！

<?php
//コンシューマーキーとブログホスト
$api_key = '';
$host = 'arayutw.tumblr.com';

//JSONデータを取得し、オブジェクトに変換
$json = @file_get_contents("https://api.tumblr.com/v2/blog/{$host}/info?api_key={$api_key}");
$obj = json_decode($json);

//ブログID・ブログ名・ブログURL・最終更新(ついでに整形)・獲得スキ数
$id = $obj->response->name;
$name = $obj->response->title;
$url = $obj->response->url;
$updated = date('Y/m/d H:i',$obj->response->updated);
$likes = $obj->response->likes;

//出力
echo "
{$name}
ID：{$id}
URL：{$url}
最終更新：{$updated}
スキ数：{$likes}
";

プログラムの実行結果

プログラムを実行すると、簡易ではありますが、指定したブログのプロフィールがブラウザに表示されます！

4-2ブログのアバターを取得する

ブログのアバター(プロフィールアイコン)の画像URLを取得する方法を紹介します。アバターは下記のURLを組み立てることで、呼び出すことができます。サイズは16、24、30、40、48、64、96、128、512の中から選択でき、省略すると64となります。

[GET] https://api.tumblr.com/v2/blog/{ブログホスト}/avatar{/サイズ}

例えば、私のブログのアイコン(128x128)は下記の通り、呼び出すことができます。リンクをクリックしてアクセスしてみて下さいね。

https://api.tumblr.com/v2/blog/arayutw.tumblr.com/avatar/128 [リンク]

これは、実際にTumblrのAPIを利用して、アバター画像を表示しているサンプルです。このように、imgタグでそのまま利用することも可能です！

4-3ブログのフォロワーデータを取得する

そのブログをフォローしている人たちを取得することができます。このAPIを利用するには、OAuth認証が必要となります。

[GET] https://api.tumblr.com/v2/blog/{ブログホスト}/followers

下記のオプション・パラメータを指定することで、取得するフォロワーデータを絞り込むことができます。

パラメータ	説明
limit	取得件数 - [初期値] 20 - [最大値] 20
offset	オフセット(取得開始位置) - [初期値] 0

取得できるJSONデータ

usersプロパティに、フォロワー(ファン)のプロフィールデータが配列形式で格納されています。

{
 "meta": {
  "status": 200, //ステータスコード
  "msg": "OK"
 },
 "response": {
  "total_users": 1, //総フォロワー数
  "users": [
   {
    "name": "arayutest", //ユーザーID
    "url": "http://arayutest.tumblr.com/", //ユーザーの主ブログURL
    "updated": 1404128526, //最終更新時刻
    "following": true //自分がフォローしてるか
   },
   ...
  ]
 }
}

サンプルリクエスト

フォロワー情報を取得するサンプルプログラムが下記です。

<?php
//アクセストークン、アクセストークンシークレット・ブログホスト
$access_token = '';
$access_token_secret = '';
$host = 'arayutw.tumblr.com';

//JSONデータを取得
$json = tumblr_oauth(
	"https://api.tumblr.com/v2/blog/{$host}/followers",
	'POST',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'limit'=>5,
	)
);

//オブジェクト形式に変換
$obj = json_decode($json);

//出力
echo "<h1>フォロワー({$obj->response->total_users}人)</h1>";

//個々のユーザーデータを読み込む
foreach($obj->response->users as $item){
	//ユーザーID・ブログURL・最終更新時刻(ついでに整形)
	$id = $item->name;
	$url = $item->url;
	$updated = date('Y/m/d H:i',$item->updated);

	//出力
	echo "<p>ID：{$id}<br/>URL：{$url}<br/>最終更新：{$updated}</p>";
}

プログラムの実行結果

プログラムを起動すると、このように、指定したブログをフォローしているユーザー(ファン)の一覧データを取得することができます。

4-4ブログの記事一覧を取得する

そのブログに投稿した記事一覧を取得することができます！そのためには、下記のURLに、GETメソッドでリクエストを送って下さい。

[GET] https://api.tumblr.com/v2/blog/{ブログホスト}/posts{/投稿タイプ}

下記のパラメータを指定することで、取得する記事を絞り込むことができます。

パラメータ	説明
api_key	[必須] コンシューマーキー
type	投稿タイプ(URL部分で指定) - [初期値] 全て - [text] テキスト - [quote] 引用 - [link] リンク - [answer] アンサー - [video] ビデオ - [audio] 音声 - [photo] 写真 - [chat] チャット
id	記事ID ※この記事IDが存在しなければ、リクエストエラー
tag	タグ名
limit	取得件数 - [初期値] 20 - [最大値] 20
offset	オフセット(取得開始位置) - [初期値] 0
reblog_info	リブログの情報を取得するかを[true / false]で指定 - [初期値] false ※真偽値ではなく、文字列として指定(引用符で囲む)
notes_info	Notes(履歴)の情報を取得するかを[true / false]で指定 - [初期値] false ※真偽値ではなく、文字列として指定(引用符で囲む)
filter	フィルタリング - [初期値] raw - [text] プレインテキストで取得 - [raw] HTMLを反映して取得

取得できるJSONデータ

下記のJSONデータを取得することができます。blogプロパティには「ブログのプロフィールを取得する」で取得したものと同じJSONデータが、postsプロパティには「記事のJSONデータについて」で解説しているJSONデータが配列形式で格納されています。

{
 "meta": {
  "status": 200, //ステータスコード
  "msg": "OK"
 },
 "response": {
  "blog": { //ブログプロフィールデータ
   ...
  },
  "posts": [ //ブログ記事データ(配列形式)
   {
    ...
   },
   ...
  ],
  "total_posts": 7 //総投稿数(リブログ含む)
 }
}

サンプルリクエスト

以上を踏まえた、記事一覧を取得するサンプルプログラムを用意しました。取得したJSONデータをブラウザに出力します。

<?php
//アクセストークン、アクセストークンシークレット・ブログホスト・投稿タイプ
$access_token = '';
$access_token_secret = '';
$host = 'arayutw.tumblr.com';
$type = ''; //指定する場合は最初に[/]を付ける 例：'/text'

//JSONデータを取得
$json = tumblr_oauth(
	"https://api.tumblr.com/v2/blog/{$host}/posts",
	'GET',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'limit'=>5,
	)
);

//JSONデータをブラウザに出力
echo '<pre>';
echo json_encode(json_decode($json),JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
echo '</pre>';

5ブログにスキを付けたり、フォローしたりしてみよう！

この章では、APIを経由して、記事にスキを付けたり外したり、また、ブログをフォローしたり外したりするAPIを紹介します。Tumblrの機能をwebサービスに本格的に取り込むには、こういった機能が必要になってきそうですねー。

5-1フォローとアンフォロー

まずはフォローとアンフォローをするためのAPIを紹介します。それぞれ、指定のURLにPOSTメソッドでAPIリクエストを送ります。

フォローする場合

[POST] https://api.tumblr.com/v2/user/follow

アンフォローする場合

[POST] https://api.tumblr.com/v2/user/unfollow

パラメータについて

パラメータには、フォロー(アンフォロー)するブログのURLを指定します。

パラメータ	説明
url	[必須] 指定ブログのURL

サンプルリクエスト

以上を踏まえたサンプルリクエストが下記の通りです。サンプルブログには、私のTumblrを用意したので、フォロー→アンフォローと試してみて下さい。8行目のリクエストURLを変えて下さいね！

<?php
//アクセストークン、アクセストークンシークレット
$access_token = '';
$access_token_secret = '';
 
//JSONデータを取得
$json = tumblr_oauth(
	'https://api.tumblr.com/v2/user/follow',
	'POST',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'url'=>'http://arayutest.tumblr.com/',
	)
);
 
//JSONデータをブラウザに出力
echo '<pre>';
echo json_encode(json_decode($json),JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
echo '</pre>';

取得できるJSONデータ

リクエストに成功すると、下記のJSONデータを取得します。ステータスコードで成功判定をして下さい。存在しないブログURLを指定するなどして、リクエストに失敗すると、nullが返ります。同じブログを連続(重複)でフォローしても、失敗にはなりません。

{
 "meta": {
  "status": 200, //ステータスコード
  "msg": "OK"
 },
 "response": [

 ]
}

5-2スキとアンライク

続いて、特定の記事にスキを付けたり外したりしてみましょう。このリクエストには、指定記事の「ID」とリブログキーが必要です！

スキする場合

[POST] https://api.tumblr.com/v2/user/like

アンライクする場合

[POST] https://api.tumblr.com/v2/user/unlike

パラメータについて

パラメータには、スキ(アンライク)する記事の、IDとリブログキーを指定します。

パラメータ	説明
id	[必須] 指定記事のID
reblog_key	[必須] 指定記事のリブログキー

サンプルリクエスト

以上を踏まえたサンプルリクエストが下記の通りです。サンプル記事には、こちらの投稿を用意したので、この記事をスキしたり、キライしたりしてみて下さい。8行目のリクエストURLを変えて下さいね！

<?php
//アクセストークン、アクセストークンシークレット
$access_token = '';
$access_token_secret = '';
 
//JSONデータを取得
$json = tumblr_oauth(
	'https://api.tumblr.com/v2/user/unlike',
	'POST',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'id'=>'90380091184',
		'reblog_key'=>'e43ysAS4',
	)
);
 
//JSONデータをブラウザに出力
echo '';
echo json_encode(json_decode($json),JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
echo '';

取得できるJSONデータ

リクエストに成功すると、下記のJSONデータを取得します。フォロー(アンフォロー)の時と同じく、ステータスコードで成功判定をして下さい。存在しないID、リブログキーを指定するなどして、リクエストに失敗すると、nullが返ります。また、注意点として、同じ記事に連続でスキのリクエストを送ると、スキのカウントだけが上がり続けます。

{
 "meta": {
  "status": 200, //ステータスコード
  "msg": "OK"
 },
 "response": [

 ]
}

6タグ検索をしてみよう！

Tumblrの記事の中から、特定のタグが付いたものを検索することができます。

6-1タグ検索のリクエスト方法

タグ検索をするには、下記のURLにGETメソッドでリクエストを送ります。

[GET] https://api.tumblr.com/v2/tagged

パラメータについて

下記が指定できるパラメータです。

パラメータ	説明
tag	[必須] 検索するタグ
before	UNIX TIMESTAMPを指定すると、それより過去の記事のみを取得
limit	取得件数 - [初期値] 20 - [最大値] 20
filter	フィルタリング - [初期値] raw - [text] プレインテキストで取得 - [raw] HTMLを反映して取得

コンシューマーキーの認証でリクエスト

このAPIは、OAuth認証とは別に、アプリ登録で取得したコンシューマーキーの認証でリクエストを送ることができます。コンシューマーキーで認証する場合は、下記のURLアドレスから取得することが可能です！

[GET] https://api.tumblr.com/v2/tagged?api_key={コンシューマーキー}

取得できるJSONデータ

取得できるJSONデータは下記の通りです。responseの中に、各記事のJSONデータが配列形式で格納されています。各記事のJSONデータに関しては、「記事のJSONデータについて」の章で詳しく解説しています。

{
 "meta": {
  "status": 200,
  "msg": "OK"
 },
 "response": [
  ...
 ]
}

6-2サンプルプログラム

以上を踏まえて作成したPHPプログラムが下記です。まずは$api_keyだけを設定して起動してみて下さい。正常に動いたら、今度はパラメータを変更するなどして、色々なタグ検索を試してみて下さいね！

<?php
//コンシューマーキー
$api_key = 'u1iNM3IPudoCsCJDPHCPG0S160O5jS8qRn3GqwDbqOgyQskm0M';

//パラメータを指定
$parameters = array(
	'api_key'=>$api_key,
	'tag'=>'gif',
	'limit'=>2,
);

//リクエストURL
$request_url = 'https://api.tumblr.com/v2/tagged?'.http_build_query($parameters);

//JSONデータを取得
$json = @file_get_contents($request_url);
 
//JSONデータをブラウザに出力
echo "<p>リクエストURL：{$request_url}</p>";
echo '<pre>';
echo json_encode(json_decode($json),JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
echo '</pre>';

7ブログに記事を投稿(削除)してみよう！

最後に、ブログに記事を投稿したり削除してみましょう。記事の投稿種類としては、「新規投稿」「既存記事の編集」「リブログ」の3種類があります。それぞれの投稿について、簡単に見ていきます。

7-1新規投稿

記事を新しく投稿するには、下記のURLにPOSTメソッドでリクエストを送ります。OAuth認証が必要です。

[POST] https://api.tumblr.com/v2/blog/{ブログホスト}/post

基本的なパラメータ

Tumblrにはテキスト投稿、画像投稿、引用投稿など、様々な投稿タイプが存在します。下記のパラメータは、「全ての投稿タイプ」で共通して使用できるパラメータです。投稿タイプごとに指定できるパラメータは、次項から紹介していきます。

プロパティ	説明
type	投稿タイプ(URL部分で指定) - [初期値] text - [text] テキスト - [quote] 引用 - [link] リンク - [video] ビデオ - [audio] 音声 - [photo] 写真 - [chat] チャット
state	投稿ステータス - [初期値] published - [published] 公開 - [queued] 予約 - [draft] 下書き - [private] プライベート
tags	タグ名を指定 ※複数の場合は半角カンマで区切る
tweet	Twitterにシェアする場合のコメント ※「off」とだけ指定すると、Twitterへのシェアを強制的に中止する ※"[URL]"という文字列は、記事のパーマリンクURLに変換される
date	「予約投稿」の場合に、投稿時間を指定 [例] 2011-07-11 20:24:14 GMT ※GMT基準のため、+9時間する必要がある
format	フォーマットを指定 - [初期値] HTML - [html] HTML - [markdown] MarkDown
slug	パーマリンクの後部に付くスラッグを指定 ※複数記事に、同じスラッグを指定できる [例] ...com/post/90380091184/sample-post [リンク]

テキスト投稿 [type:text]

テキスト投稿の場合、本文のbodyプロパティで、HTMLを利用することが可能です。

プロパティ	説明
title	タイトル ※HTMLはエスケープされる
body	[必須] 本文テキスト ※HTMLは反映される

	'title'=>'サンプルタイトル',
	'body'=>'<p><em><strong></strong></em><em>test</em>です。</p>',

画像投稿 [type:photo]

画像の投稿は、とても簡単です。sourceに画像のURLを指定するだけで、画像記事を投稿することが可能です。

プロパティ	説明
caption	キャプション ※HTMLは反映される
link	メディアの関連URL ※記事の画像をクリックした時にジャンプする
source	[どちらか必須] 記事に掲載する画像ファイルのURL
data	[どちらか必須] メディアの、URLエンコードされたバイナリデータを配列形式で指定 ※最大10MB

	'caption'=>'<p><em><strong></strong></em><em>test</em>です。</p>',
	'link'=>'http://syncer.jp/',
	'source'=>'https://api.tumblr.com/v2/blog/arayutw.tumblr.com/avatar/128',

引用投稿 [type:quote]

引用の投稿は、引用テキストのHTMLが反映されない点にご注意下さい。

プロパティ	説明
quote	[必須] 引用テキスト ※HTMLはエスケープされる
url	引用元のURL

	'quote'=>'持ってるだけで、歩数や距離、消費カロリーなんかを計算してくれる次世代健康管理アプリの「Moves」。',
	'url'=>'http://syncer.jp/moves-api-matome',

リンク投稿 [type:link]

リンクの投稿は、URLのみが必須となっています。

プロパティ	説明
title	リンクのタイトル ※HTMLはエスケープされる
url	[必須] リンクのURL
description	URLについての説明文 ※HTMLは反映される

	'title'=>'Moves APIでwebサービスを作りたい全ての人に向けて書きました',
	'url'=>'http://syncer.jp/moves-api-matome',
	'description'=>'<p><em><strong></strong></em><em>test</em>です。</p>',

チャット投稿 [type:chat]

チャットは、conversationにログを指定してリクエストして下さい。名前部分と発言部分を:で分けることによって、Tumblrが:より前をラベル(発言者名)と認識します。発言は改行で分けて下さいね！

プロパティ	説明
title	チャットのタイトル ※HTMLはエスケープされる
conversation	[必須] チャット本文 ※HTMLはエスケープされる

	'title'=>'はてブマンとふなっしーの会話',
	'conversation'=>'はてブマン:こんにちはブク
ふなっしー:こんにちはなっしー
はてブマン:こんばんはブク
ふなっしー:こんばんはなっしー',

音声投稿 [type:audio]

音声は、画像と同様、音声ファイルのURLをexternal_urlに指定することで投稿できます。例えばSoundCloudの場合は、ファイルではなく「コンテンツページのURL」を指定することも可能です。

プロパティ	説明
caption	音声のキャプション ※HTMLは反映される
external_url	[どちらか必須] 記事に掲載する音声ファイルのURL
data	[どちらか必須] メディアの、URLエンコードされたバイナリデータを指定 ※最大100MB

	'caption'=>'<p><em><strong></strong></em><em>test</em>です。</p>',
	'external_url'=>'http://syncer.jp/hello.m4a',

動画投稿 [type:video]

動画の場合は、YoutubeやVimeoといった動画投稿サイトの埋め込み用HTMLコードをそのまま指定することで、記事で動画を公開することができます。Tumblr APIって素敵ですね…。

プロパティ	説明
caption	動画のキャプション ※HTMLは反映される
embed	[どちらか必須] 埋め込み用HTMLコード
data	[どちらか必須] メディアの、URLエンコードされたバイナリデータを指定 ※最大100MB

	'caption'=>'<p><em><strong></strong></em><em>test</em>です。</p>',
	'embed'=>'<iframe width="560" height="315" src="//www.youtube.com/embed/xLNULFuEKxc" frameborder="0" allowfullscreen></iframe>',

取得できるJSONデータについて

「新規投稿」のAPIリクエストが成功した時に取得できるJSONデータです。「新規投稿」の場合は、ステータスコード201が返却されます。また、responseの中のidプロパティには、記事IDが格納されています。

{
  "meta": {
    "status": 201, //ステータスコード
    "msg": "Created"
  },
  "response": {
	"id": 90440196914 //投稿した記事のID
  }
}

サンプルリクエスト

Tumblrで新規投稿をするためのPHPサンプルプログラムです。$access_token、$access_token_secretをセットし、20行目に上記で紹介したサンプルパラメータを挿入して起動してみて下さいね。一度投稿が成功したら、さらにパラメータを変更して、色々と試してみて下さいね！

「こちら」で紹介している、関数のtumblr_oauth()を読み込むのと、あとは指定したパラメータと14行目のtypeを合わせるのを忘れないようにどうぞ…。

<?php
//アクセストークン、アクセストークンシークレット・ブログホスト
$access_token = '';
$access_token_secret = '';
$host = 'arayutw.tumblr.com';

//JSONデータを取得
$json = tumblr_oauth(
  "https://api.tumblr.com/v2/blog/{$host}/post",
  'POST',
  array(
    'oauth_token'=>$access_token,
    'oauth_token_secret'=>$access_token_secret,
    'type'=>'text',
    'state'=>'published',
    'tags'=>'タグ1,タグ2',
    'tweet'=>'Tumblr APIを利用したシェアのテストです。→[URL]',
    'format'=>'html',
    'slug'=>'test',

  )
);
  
//JSONデータをブラウザに出力
echo '';
echo json_encode(json_decode($json),JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
echo '';

7-2既存記事の編集

一度投稿した記事を編集するには、下記のURLにPOSTメソッドでリクエストします。

[POST] https://api.tumblr.com/v2/blog/{ブログホスト}/post/edit

パラメータについて

パラメータは、「新規投稿」と全く一緒です。一点だけ、編集対象の記事IDを示すidを、新たに加えて下さい。

パラメータ	説明
id	[必須] 記事ID

取得できるJSONデータについて

下記がリクエストで取得できるJSONデータです。「新規投稿」の場合と違い、ステータスコードは200となりますのでご注意下さい。

{
  "meta": {
    "status": 200, //ステータスコード
    "msg": "OK"
  },
  "response": {
    "id": 90440196914 //編集した記事のID
  }
}

7-3リブログ

続いて、お気に入りの記事をリブログしてみましょう。それには、下記のURLにPOSTメソッドでリクエストします。

[POST] https://api.tumblr.com/v2/blog/{ブログホスト}/post/reblog

パラメータについて

パラメータは、リブログ対象記事の「ID」と「リブログキー」を指定します。なお、コメントを付ける場合はcommentプロパティで指定します。

パラメータ	説明
id	[必須] 記事ID
reblog_key	[必須] 記事のリブログキー
comment	リブログに付けるコメント

サンプルリクエスト

下記がリブログをするためのPHPサンプルプログラムです。$access_token、$access_token_secretをセットして下さい。サンプルのid、reblog_keyには、私の投稿を設定してありますので、気軽にお試し下さい。

<?php
//アクセストークン、アクセストークンシークレット・ブログホスト
$access_token = '';
$access_token_secret = '';
$host = 'arayutw.tumblr.com';

//JSONデータを取得
$json = tumblr_oauth(
	"https://api.tumblr.com/v2/blog/{$host}/post/reblog",
	'POST',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'id'=>'90380091184',
		'reblog_key'=>'e43ysAS4',
		'comment'=>'リブログしましたー。',
	)
);
  
//JSONデータをブラウザに出力
echo '<pre>';
echo json_encode(json_decode($json),JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
echo '</pre>';

取得できるJSONデータについて

リクエストが成功した時に取得できるJSONデータです。「新規投稿」の場合と同様、ステータスコードで201が返却されます。idプロパティには、リブログで作成した新しい記事のIDが格納されています。

{
  "meta": {
    "status": 201, //ステータスコード
    "msg": "Created"
  },
  "response": {
    "id": 90446413924 //リブログで投稿した記事のID
  }
}

7-4記事の削除

記事を削除することが可能です。そのためには、下記のURLにPOSTメソッドでリクエストを送って下さい！

[POST] https://api.tumblr.com/v2/blog/{ブログホスト}/post/delete

パラメータについて

パラメータには、削除対象の記事を示すidを、指定して下さい。

パラメータ	説明
id	[必須] 記事ID

取得できるJSONデータについて

下記がリクエストで取得できるJSONデータです。ステータスコードは「既存記事の編集」と同じく、200が返ってきます。

{
  "meta": {
    "status": 200, //ステータスコード
    "msg": "OK"
  },
  "response": {
    "id": 90440196914 //削除した記事のID
  }
}

サンプルリクエスト

記事を削除するためのサンプルプログラムを用意しました。$access_token、$access_token_secret、$host、idを設定してから、プログラムを起動してみて下さい！

<?php
//アクセストークン、アクセストークンシークレット・ブログホスト
$access_token = '';
$access_token_secret = '';
$host = 'arayutw.tumblr.com';
 
//JSONデータを取得
$json = tumblr_oauth(
  "https://api.tumblr.com/v2/blog/{$host}/post/delete",
  'POST',
  array(
    'oauth_token'=>$access_token,
    'oauth_token_secret'=>$access_token_secret,
    'id'=>'90440196914',
  )
);
   
//JSONデータをブラウザに出力
echo '<pre>';
echo json_encode(json_decode($json),JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
echo '</pre>';

8記事のJSONデータについて

記事のJSONデータの項目は多岐に渡ります。加えて、テキスト投稿、画像投稿など、投稿タイプによって、含まれるプロパティの種類も違います。この章では、記事のjSONデータの構造、各プロパティについて、紹介していきます。

8-1JSONデータの構造

1つの記事のJSONデータは、次のような構造になっています。

{
 "blog_name": "arayutest", //ブログ名
 "id": 90345602112, //記事ID
 "post_url": "http://arayutest.tumblr.com/...", //記事のパーマリンク
 "slug": "1022-p-a-href-http-ww...", //パーマリンクのスラッグ
 "type": "photo", //記事タイプ
 "date": "2014-06-30 11:42:06 GMT", //記事の投稿日(GMT基準なので9時間の時差)
 "timestamp": 1404128526, //記事の投稿日
 "state": "published", //記事のステータス
 "format": "html", //記事のフォーマット
 "reblog_key": "eJGxcsjb", //リブログキー
 "tags": [ //記事のタグ(配列形式)
  "タグ1",
  "タグ2"
 ],
 "short_url": "http://tmblr.co/ZXWa6n1K917n0", //記事の短縮URL
 "followed": true,
 "highlighted": [

 ],
 "liked": true,
 "note_count": 356, //Notesの数
 "link_url": "http://www.sephora.com/th...", //画像の引用元リンク
 "image_permalink": "http://arayute...", //画像のパーマリンク
 "notes": [ //リアクション(Notes)の一覧(配列形式)
  {
   "timestamp": "1404245974", //リアクション日時
   "blog_name": "arayutest", //ユーザーID
   "blog_url": "http://arayutest.tumblr.com/", //ユーザーの主ブログURL
   "post_id": "90484637102", //リブログした記事のID
   "type": "reblog" //リブログをした
  },
  {
   ...
   "type": "like" //スキをした
  },
  {
   ...
   "type": "posted" //投稿した(投稿者自身)
  }
 ],
 "reblogged_from_id": "89681336342", //リブログ元の記事ID
 "reblogged_from_url": "http://nih...", //リブログ元の記事パーマリンク
 "reblogged_from_name": "nihongo", //リブログ元のブログID
 "reblogged_from_title": "Tumblr Nihongo", //リブログ元のブログ名
 "reblogged_root_id": "88359543029", //オリジナルの記事ID
 "reblogged_root_url": "http://fum3...", //オリジナルの記事パーマリンク
 "reblogged_root_name": "fum3", //オリジナルのブログID
 "reblogged_root_title": "yururinooheso", //オリジナルのブログ名
 "can_reply": false
}

リアクションとリブログのデータについて

赤色を付けている、notes(リアクション)、reblog...(リブログ)のプロパティは、それぞれデフォルトでは含まれていません。オプションパラメータのnotes_info、reblog_infoでtrueを指定することで、JSONデータに追加されます。

8-2共通のプロパティ

1つ1つのプロパティを見ていきましょう。まずは全ての投稿タイプで共通して含まれているプロパティです。

プロパティ	説明
blog_name	ブログID
id	記事ID
post_url	パーマリンク
type	投稿タイプ - [text] テキスト - [quote] 引用 - [photo] 画像 - [link] リンク - [chat] チャット - [audio] 音声 - [video] 動画 - [answer] アンサー
timestamp	投稿日(UNIX TIMESTAMP)
date	投稿日(GMT形式) ※日本時間から-9時間の時差がある
format	投稿フォーマット - [html] HTML - [markdown] MARKDOWN
reblog_key	リブログキー
tags	タグ(配列形式)
bookmarklet	ブックマークレット形式の投稿か？ - [true] ブックマークレット形式の投稿 ※違う場合は、プロパティ自体が存在しない
mobile	モバイル、Eメール形式の投稿か？ - [true] モバイル、Eメール形式の投稿 ※違う場合は、プロパティ自体が存在しない
source_url	引用元URL ※投稿に引用元URLが含まれていない場合、プロパティ自体が存在しない
source_title	引用元タイトル ※投稿に引用元タイトルが含まれていない場合、プロパティ自体が存在しない
liked	自分がスキを付けているか？ ※OAuth認証以外のリクエストの場合、プロパティ自体が存在しない
state	投稿ステータス - [published] 公開済み - [queued] 予約状態 - [draft] 下書き - [private] プライベート
total_posts	総投稿数

8-3テキスト投稿のプロパティ [type:text]

テキストタイプの投稿のJSONデータに含まれるプロパティです。

プロパティ

プロパティ	説明
title	タイトル
body	本文(HTML反映)

JSONデータのサンプル

{
 "meta": {
  ...
 },
 "response": {
  "posts": [
   {
    "blog_name": "arayutest",
    ...
    "title": "サンプルタイトル",
    "body": "<p>これは本文です。HTMLが<strong>反映</strong>されます。</p>",
    ...
   }
  ]
 }
}

8-4画像投稿のプロパティ [type:photo]

画像タイプの投稿のJSONデータに含まれるプロパティです。画像投稿の場合、各種サイズのデータを配列形式で含んだalt_sizesと、オリジナルサイズのデータを含んだoriginal_sizeプロパティが存在します。

プロパティ

プロパティ	説明
caption	画像のキャプション(HTML反映)
alt_sizes	サイズ別のデータ(配列形式)
original_size	オリジナルサイズのデータ

JSONデータのサンプル

{
 "meta": {
  ...
 },
 "response": {
  "posts": [
   {
    "blog_name": "arayutest",
    ...
    "photos": [
     {
      "caption": "", //画像のキャプション(HTML反映)
      "alt_sizes": [ //各サイズの画像データ(配列形式)
       {
        "width": 640, //画像の幅
        "height": 640, //画像の高さ
        "url": "http://37.media.tumb..." //640x640画像のパーマリンク
       },
       {
        "width": 500,
        "height": 500,
        "url": "http://37.media.tumb..." //500x500画像のパーマリンク
       },
       ... //以下、400、250、100、75と続く
      ],
      "original_size": { //オリジナルサイズの画像データ
       "width": 640,
       "height": 640,
       "url": "http://37.media.tum..." //オリジナルサイズのパーマリンク
      }
     }
    ],
    ...
   }
  ]
 }
}

8-5引用投稿のプロパティ [type:quote]

引用タイプの投稿のJSONデータに含まれるプロパティです。

プロパティ

プロパティ	説明
text	引用したテキスト
source	出典欄に入力したテキスト(HTML反映)

JSONデータのサンプル

{
 "meta": {
  ...
 },
 "response": {
  "posts": [
   {
    "blog_name": "arayutest",
    ...
    "text": "我が輩は猫である",
    "source": "<a href="http://example.com/">夏目漱石のHP</a>",
    ...
   }
  ]
 }
}

8-6リンク投稿のプロパティ [type:link]

リンクタイプの投稿のJSONデータに含まれるプロパティです。

プロパティ

プロパティ	説明
title	リンクのタイトル
url	リンクのURL
description	リンクの説明文(HTML反映)

JSONデータのサンプル

{
 "meta": {
  ...
 },
 "response": {
  "posts": [
   {
    "blog_name": "arayutest",
    ...
    "title": "我が輩は猫である",
    "url": "http://example.com/",
    "description": "<p>この文章はまさに<strong>名文</strong>である。</p>",
    ...
   }
  ]
 }
}

8-7チャット投稿のプロパティ [type:chat]

チャットタイプの投稿のJSONデータに含まれるプロパティです。Tumblrはチャットログを改行ごとに分けて解析し、dialogueプロパティに配列形式で格納しています。

プロパティ

プロパティ	説明
title	投稿のタイトル
body	その時点でのチャットログ(HTML反映)
dialogue	チャットの各発言データ(配列形式)

JSONデータのサンプル

{
 "meta": {
  ...
 },
 "response": {
  "posts": [
   {
    "blog_name": "arayutest",
    ...
    "title": null, //タイトル
    "body": "Arayu: Hello,My Friend! //チャット本文(HTML反映)
     [draft] Hatebuman: I'm not your friend.
     Arayu: Oh, No...
    "dialogue": [ //チャットの各発言データ(配列形式)
     {
        "label": "Arayu:", //発言者のラベル
        "name": "Arayu", //発言者のユーザーID
        "phrase": "Hello,My Friend! [draft]", //発言データ(HTML反映)
     },
     {
        "label": "Hatebuman:",
        "name": "Hatebuman",
        "phrase":"I'm not your friend."
     },
     ...
   ]
    ...
   }
  ]
 }
}

8-8音声投稿のプロパティ [type:audio]

音声タイプの投稿のJSONデータに含まれるプロパティです。SoundCloudなどから音声ファイルを引っ張ってきた時に、曲名やアルバム名など多数のプロパティが含まれる場合があります。

プロパティ

プロパティ	説明
caption	音声のキャプション(HTML反映)
player	埋め込み用のHTMLタグ
plays	音声の長さ(秒)
album_art	音声イメージのHTMLタグ ※投稿に音声イメージが含まれていない場合、プロパティ自体が存在しない
artist	アーティスト名 ※投稿にアーティスト名が含まれていない場合、プロパティ自体が存在しない
album	曲のアルバム名 ※投稿にアルバム名が含まれていない場合、プロパティ自体が存在しない
track_name	曲名 ※投稿に曲名が含まれていない場合、プロパティ自体が存在しない
track_number	曲番号 ※投稿に曲番号が含まれていない場合、プロパティ自体が存在しない
year	曲の発表年 ※投稿に発表年が含まれていない場合、プロパティ自体が存在しない
is_external	外部のファイルか - [true] 外部ファイル(URLを貼った場合) ※投稿が外部ファイルじゃない場合、プロパティ自体が存在しない
audio_type	音声タイプ [例] SoundCloudのURL(外部ファイル)を貼った場合は「soundcloud」になる ※投稿が外部ファイルじゃない場合、プロパティ自体が存在しない

JSONデータのサンプル

{
 "meta": {
  ...
 },
 "response": {
  "posts": [
   {
    "blog_name": "arayutest",
    ...
    "source_url": "http://soundcloud.c...", //ソースのURL(ページ)
    "source_title": "SoundCloud / DJ T.HIROYUKI", //投稿のタイトル
    "track_name": "Mr.Children - シーソーゲーム", //曲名
    "album_art": "https://38.media.tum/tu...", //アートワークの画像URL
    "caption": "<p>最高の曲</p>", //音声のキャプション(HTML反映)
    "player": "<iframe src...</iframe>", //埋め込み用HTMLコード
    "plays": 16025, //音声の秒数
    "audio_url": "http://api.soun...", //ソースのURL(ファイル)
    "is_external": true, //外部ファイルか？
    "audio_type": "soundcloud" //外部ファイルの種類
    ...
   }
  ]
 }
}

8-9動画投稿のプロパティ [type:video]

動画は画像と同様、サイズ別のデータが、配列形式でplayerプロパティに含まれる形になります。

プロパティ

プロパティ	説明
caption	動画のキャプション(HTML反映)
player	動画の各サイズの情報(配列形式)

JSONデータのサンプル

{
 "meta": {
  ...
 },
 "response": {
  "posts": [
   {
    "blog_name": "arayutest",
    ...
    "caption": "<p>最高の動画</p>",
    "player": [
     {
        "width": 250, //動画の幅
        "embed_code": "<object width=...</object>" //埋め込み用HTMLコード
     },
     {
        "width": 400,
        "embed_code": "..."
     },
     {
        "width": 500,
        "embed_code": "..."
     }
    ]
    ...
   }
  ]
 }
}

8-10アンサー投稿のプロパティ [type:answer]

アンサー(回答)タイプの投稿のJSONデータに含まれるプロパティです。question、answerともに、HTMLが反映されています。

プロパティ

プロパティ	説明
asking_name	質問者のブログID
asking_url	質問者のブログURL
question	質問テキスト(HTML反映)
answer	回答テキスト(HTML反映)

JSONデータのサンプル

{
 "meta": {
  ...
 },
 "response": {
  "posts": [
   {
    "blog_name": "arayutest",
    ...
    "asking_name": "arayutw",
    "asking_url": "http://arayutw.tumblr.com",
    "question": "<p>はてブマンは、ふなっしーのライバルなんですか？</p>",
    "answer": "<p>そうブク。</p>",
    ...
   }
  ]
 }
}

9Tumblr APIを利用したアイデア

「TumblrのAPIを上手く利用しているなー」と思っていたのが、プログラミング学習サイト「ドットインストール」の公式ブログです。現在はリニューアルされて内容は変わったのですが、以前は、Twitter上でドットインストールについて言及しているツイートが、Tumblrに引用投稿でアップされていました。

これは恐らくですが、Twitterの検索APIでドットインストール関連のキーワードを含むツイートをピックアップし、それを、今度はTumblr APIを利用して自動的にブログにアップしていたんだと思います。ユーザーの自社サービスに対する感想を、自動で、このように公開するシステムはとても良いアイデアですよね。

9-1はてなブックマークの「ブクマ」を自動でTumblrに投稿する

ということで、ドットインストールの旧公式ブログの発想をお借りして…、IFTTTにチャンネルがない「はてなブックマーク」と「Tumblr」を、連携するプログラムを考えてみました。はてブをすると、自動的に、コメントとスクリーンショットなどがTumblrに投稿されます。

はてなブックマーク側のWeb Hookの設定

このプログラムは、はてなブックマークの「Web Hook」を利用します。「Web Hook」の設定については、下記ページの第9章をご参考下さい。設定の際には「ブックマークの追加/更新/削除」にチェックを入れておいて下さいね！

PHPのサンプルプログラム

はてブをすると自動的にTumblrにシェアする連携システムを実現したのが、下記のサンプルプログラムです。設定項目をセットするのと、関数tumblr_oauth()を読み込むのを忘れないで下さいね！「こちら」にあります。よろしければ試してみて下さい！

<?php
//はてブで、設定したweb hookのキー
$webhook = '8M9000HMZ4NDWHZC';
 
//Tumblrのアクセストークン・アクセストークンシークレット・ブログホスト
$access_token = '';
$access_token_secret = '';
$host = '';

//タグを付けておきたい場合に指定(複数の場合は半角カンマで区切る)
$tags = "はてブ";

//Web Hookによるリクエストを受け取る(ブクマの追加以外は排除)
if(!isset($_POST['status']) || $_POST['status'] != 'add') exit;

//キーが合わなければ終了
if(!isset($_POST['key']) || empty($_POST['key']) || $_POST['key'] != $webhook) exit;
 
//ブックマークしたURLを取得
$obj = simplexml_load_string(@file_get_contents('http://b.hatena.ne.jp/'.$_POST['username'].'/rss?'.time()));
if(!$link = (string)$obj->item[0]->link) exit;
$url = parse_url($link);
$title = '[B!]'.(string)$obj->item[0]->title;
$comment = (isset($obj->item[0]->description)) ? '<p>'.$obj->item[0]->description.'</p>' : '';

//新規投稿する
tumblr_oauth(
	"https://api.tumblr.com/v2/blog/{$host}/post",
	'POST',
	array(
		'oauth_token'=>$access_token,
		'oauth_token_secret'=>$access_token_secret,
		'type'=>'text',
		'state'=>'published',
		'tags'=>$tags,
		'tweet'=>'off',
		'format'=>'html',
		'slug'=>'hatebu',
		'title'=>$title,
		'body'=>$comment.'<p><a href="'.$url.'" target="_blank">'.$url['host'].'</a></p>',
	)
);

プログラムの実行結果

はてブをすると、こんな感じで、Tumblrに自動的にシェアされるようになります。TumblrのAPIを利用すれば、このような自動ブログを簡単に作成することができます。IFTTTではフォローし切れない「細かい調整」だって、実現できることでしょう。Instagramと連携して写真作品を、foursquareと連携して行動ログを、色んな情報を自動で公開するブログができそうですね。

この記事が、Tumblr APIを利用した素晴らしいwebサービスの誕生の助けになれば、嬉しく思います！

この連載の記事一覧

この記事へのコメント

感想、ご指摘などお気軽にお寄せ下さい。「関連記事を書いた」という方はご報告いただければリンクします。

コメントを書き込む

※Twitter、Facebook、はてな、いずれかのアカウントをお持ちの方は、本人認証(ログイン)を行なうことができます。
※本人認証をすることで、書き込みの待ち時間なし、画像アップロード、アイコンなどが利用できます。
※認証時にサービスと連携しますが、名前とアイコン以外の情報を読み込んだり、また書き込みを行なうことはありません。連携で要求する権限は「公開情報の読み取り」のみです。

コメントは、0件です。

「Tumblr API」の関連リンク集

「Tumblr API」でプログラミングする人の役に立ちそうなページをまとめてあります。webサービス作りの参考にしてみて下さい！

リンクの紹介文を見る

Tumblr API v2 日本語訳 Tumblr API v2 日本語訳
Tumblr APIの公式ドキュメントを日本語訳されていらっしゃいます。公式の英語が分かり難い場合は、こちらをチェックしてみましょう。
PythonとOAuthを使ってTumblrに投稿する方法 18th Tech Note
Pythonを利用して、Tumblr APIで投稿する方法が掲載されています。
Tumblr APIで『スキ』した画像を保存してみた鳥小屋.txt
Rubyを利用して、自分がスキをした画像の一覧を取得する方法が掲載されています。これはwebサービスに活かせそうな、素晴らしいアイデアですねー。
Tumblr SDK for iOSの使い方 Qiita
Tumblr SDK for iOSの使い方が掲載されています。
JavaプログラムからTumblrに投稿するメイビンラボ
Javaを利用して、Tumblrに投稿する方法が紹介されています。
tumblrAPIを使って画像、動画、リンク、投稿を一覧表示する方法 – Stronghold
Tumblr APIとjQueryを利用して、Javascriptで記事一覧を出力する方法と、サンプルコードが紹介されています。
Tumblrで最新記事を表示忘れっぽいからメモしていこう
TumblrのAPIを利用して、jQueryで最新記事を取得、出力する方法が解説されています。
tumblr APIを使って、最新Photoデータを取得/表示したい!! 課外活動.com
Tumblr APIを利用して、Javascriptで最新のPhotoデータ(写真)を表示する方法について、解説されています。
素のphp5.4でOAuthする（tumblr編） Softel メモ
TumblrのOAuth認証について、その流れを丁寧に解説されています。
Tumblr API を使ってみた！ Prezi
TumblrのAPIの利用方法が、綺麗なスライドショーで、丁寧に解説されています。
ローコストで動的なサイトへ -Tumblrの記事をwebサイトと連動させる方法- NIPPON DESIGN
Tumblr APIを利用した、ブログパーツ的なものを作る発想と、コードがJavascript(jQuery利用)を例に紹介されています。

記事の更新履歴

記事を公開しました。
2014/07/02 08:00

目次

1アプリケーションを登録する

1-1アカウントを取得する

1-2アプリケーションを登録する

Applications

Register your application

1-3コンシューマーキー、シークレットキーを確認する

2コンシューマーキー、シークレットキーを使ってOAuth認証をする

2-1Tumblrのアプリ認証について

2-2TumblrでOAuth認証をするPHPのサンプルプログラム

OAuth1.0認証を通したリクエストをするための関数

アプリ認証を行なうためのプログラム

2-3Tumblrのアプリ認証のイメージ

アプリの許可

アクセストークン、アクセストークンシークレットの発行

2-4関数[tumblr_oauth()]の使い方

3色々なユーザーデータを取得してみよう！

3-1ユーザープロフィールを取得する

取得できるJSONデータ

ユーザーデータを取得するPHPのサンプルプログラム

プログラムの実行結果

3-2全体の型となるPHPサンプルプログラム

3-3ダッシュボードの記事一覧を取得する [dashboard]

「Notes」って何？

サンプルリクエスト

取得できるJSONデータ

3-4予約状態の記事一覧を取得する [queue]

サンプルリクエスト

取得できるJSONデータについて

3-5ドラフト(下書き)状態の記事一覧を取得する [draft]

サンプルリクエスト

取得できるJSONデータについて

3-6ゲスト投稿の記事一覧を取得する [submission]

サンプルリクエスト

取得できるJSONデータについて

3-7スキを付けた記事一覧を取得する [likes]

サンプルリクエスト

取得できるJSONデータ

3-8フォローしているブログ一覧を取得する [following]

パラメータについて

サンプルリクエスト

取得できるJSONデータ

4ブログデータを取得してみよう！

4-1ブログのプロフィールを取得する

取得できるJSONデータ

サンプルプログラム

{$name}

プログラムの実行結果

4-2ブログのアバターを取得する

4-3ブログのフォロワーデータを取得する

取得できるJSONデータ

サンプルリクエスト

プログラムの実行結果

4-4ブログの記事一覧を取得する

取得できるJSONデータ

サンプルリクエスト

5ブログにスキを付けたり、フォローしたりしてみよう！

5-1フォローとアンフォロー

フォローする場合

アンフォローする場合

パラメータについて

サンプルリクエスト

取得できるJSONデータ

5-2スキとアンライク

スキする場合

アンライクする場合

パラメータについて

サンプルリクエスト

取得できるJSONデータ

6タグ検索をしてみよう！

6-1タグ検索のリクエスト方法

パラメータについて

コンシューマーキーの認証でリクエスト

取得できるJSONデータ

6-2サンプルプログラム

7ブログに記事を投稿(削除)してみよう！

7-1新規投稿

基本的なパラメータ

テキスト投稿 [type:text]

画像投稿 [type:photo]