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

• 2014.06.24(Tue) 07:00
• WEB制作

後で読みたい記事をストックできるwebサービスのpocket。「あとでよむ」系のサービスとしては、日本で最大手と言ってもいいですよね。ブログに付けるソーシャルボタンは、これが定番になっています。

そのpocketが提供するAPIを利用して、webサービスを作ったり、ブログにちょっとしたサブ機能を加えてみませんか？これからpocketのAPIを始める全ての人の助けになれたらと思い、その使い方をまとめてみました。

目次

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

pocketのAPIを登録するには、まず「アプリケーションの登録」を行なう必要があります。「アプリケーションっていうとなんだか難しそう…」と思うかもしれませんが、なんてことはありません。PHPでプログラムを作るなら、「〜.php」がそのアプリケーションにあたります。例えば次のプログラムだって立派な(web)アプリケーションです。

<?php
	echo "私は立派です。";

「アプリケーション登録」とは、ざっくり言えば「このPHPであなたのところのAPIを使わせて下さい」と伝える作業です。

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

なお、APIを利用するには、前提としてpocketのアカウントを所有している必要があります。もし、まだの方は、pocketでアカウントを作成するか、またはGoogleのアカウントで代用することが可能です。

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

それではアプリケーションの登録を行なっていきましょう。登録するには、下記のリンクにアクセスして下さい。まだの場合は最初にログインが求められます。

My Applications

アクセスすると、「My Applications」というページに移動します。ここに、登録したアプリの一覧が表示されて、後から情報を編集したり、削除したりできます。まだ何も登録してないので空白ですよね。何はともあれ、まずはアプリケーションを登録してみましょう。「CREATE AN APPLICATION」をクリックして下さい。

Create an Application

それではアプリの情報を登録しましょう。最初は色々と機能を試すためのお試し登録でいいと思います。よろしければ上記のサンプル画像をそのまま真似して下さい。画像はクリックすると拡大して見ることができます。

1-3登録する項目の説明

登録するアプリ情報の、各項目を説明していきます。不安な方は一度、目を通してみて下さい。

名前と概要

一番上から、まずアプリの名前と概要を入力します。例えば、人気サービスのTwilogだったら、名前が「Twilog」、概要は「Twitterをブログ形式で表示するwebサービス」となります。あなたが作成しようとしているサービスに合わせた情報を入力しましょう。ちなみに(生半可な)英語で入力しているのは、単純に日本語だと文字化けを起こしてしまうからです。

パーミッション(アプリの権限)

続いてパーミッションを設定します。パーミッションとは、「そのアプリがどんな権限を持っているか」です。Addは「アイテムの追加」、Modifyは「ストックしているアイテムの情報変更(タグの削除など)」、Retrieveは「ストックしているアイテムの読み取り」の権限をそれぞれ表します。

例えば、「ユーザーが今までにpocketしてきたアイテム(記事)をランダムで10個表示するサービス」だったら、権限は「アイテムの読み取り」だけで十分なので、Retrieveだけにチェックを付けて下さい。例えば、「ユーザーのタグを一括で削除するwebサービス」だったらRetrieveに加えてModifyにチェックを付ける必要がありますね。

まずは「機能を試すためのアプリ」なので、全部の権限にチェックを入れておきましょう。

ちょっと寄り道して…、誰もが利用しているTwitterを例にとってみると分かりやすいかもしれません。上記の画像はTwilogのアプリ認証画面です。赤枠で囲んである部分がパーミッションにあたります。これのpocket版だと思って下さい。

プラットフォーム

最後はプラットフォームの選択です。iPhoneアプリやAndroidアプリ、デスクトップアプリなど様々な種類がありますが、今回はインターネットブラウザ(web)で起動するお手軽なアプリを作ってみましょう。Webにチェックを入れて下さい。

全ての項目に問題がなければ、「I accept the Terms of Service(利用規約に同意しますか？)」にチェックを入れて、「CREATE APPLICATION」をクリックすれば登録完了です。

1-4コンシューマーキーを確認する

無事、アプリケーションの登録に成功すると、先ほどのMy Applicationsのページに遷移し、登録したアプリが一覧に加わっているのを確認できますね！アプリ名の右にあるCONSUMER KEYを保存(メモ)して下さい。サンプルでは29123-af261164b5dc63e823fc922dの部分です。画像はクリックすると拡大することができます。

これは、pocket側が、APIを使っているのがあなたのプログラムだと識別するためのキーとなります。他人に知られないように、管理しておきましょう。

2コンシューマーキーを使ってOAuth認証をする

それでは、早速、アプリ認証を行なって「アクセストークン」を取得してみましょう。pocketはOAuth2.0という認証形式を採用しています。公式ドキュメントは、下記のページにあります。

ドキュメントを読むよりも、何度かプログラムを起動し、体験して流れを掴む方が、圧倒的に分かりやすいと思います。その後、確認の意味で読むのがお勧めです。今は読まずに進んでしまって大丈夫です。

2-1pocketのアプリ認証の手順

ざっくりとした内容なんですが…、pocketのアプリ認証の手順は下記のような感じです。

下記ページに、pocketのアプリ認証の公式ドキュメントがあります。次項で紹介するサンプルプログラムは、このページの手順に沿っています。興味があったら、見比べてみて下さい。

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

下記が、先ほど紹介した3つの手順を実行するOAuth認証のサンプルプログラムです。$consumer_keyと$redirect_uriを設定してから、アクセスしてみて下さい！

<?php
//アプリ登録で取得したコンシューマーキー
$consumer_key = '29123-af261164b5dc63e823fc922d';

//このプログラムのURL
$redirect_uri = 'http://syncer.jp/test.php';

//セッションスタート
session_start();

//アプリ認証から帰ってきた時([return=1]があるアクセス)の場合はアクセストークンを取得
//[手順3] ユーザーがアプリを許可して、アプリがアクセストークンを受け取る、の部分
if(isset($_GET['return']) && is_string($_GET['return']) && $_GET['return'] == "1"){

	//セッションにリクエストトークンがない場合は不正と判断してエラー
	if(!isset($_SESSION['code']) || empty($_SESSION['code'])){ error_pk_syncer('セッションが上手く機能してないか、手動で[return=1]を付けてアクセスしてます…。'); }

	//セッションにCSRF対策用の[state]がない場合は不正と判断してエラー
	if(!isset($_SESSION['state']) || empty($_SESSION['state'])){ error_pk_syncer('セッションが上手く機能してないかもしれません。'); }

	//リクエストトークンをアクセストークンと交換する
	$data = @file_get_contents(
		'https://getpocket.com/v3/oauth/authorize',
		false,
		stream_context_create(
			array('http' => array(
				'method' => 'POST',
				'content' => http_build_query(array(
					'consumer_key' => $consumer_key,
					'code' => $_SESSION['code'],
				)),
			))
		)
	);

	//関数[get_query_syncer]を使って、GETパラメータ形式の文字列を配列に変換
	$query = get_query_syncer($data);

	//CSRF対策
	if(!isset($query['state']) || empty($query['state']) || $query['state'] != $_SESSION['state']){ error_pk_syncer('セッションに保存してあるstateと、返ってきたstateの値が違います…。'); }

	//アクセストークンが取得できない場合はエラー
	if(!isset($query['access_token']) || empty($query['access_token'])){ error_pk_syncer('アクセストークンを取得できませんでした…。'); }

	//アクセストークンを変数に格納
	$access_token = $query['access_token'];

	//セッション終了
	session_finish_pk_syncer();

	//アクセストークンをブラウザに出力
	echo $header."あなた({$query['username']})のアクセストークンは{$access_token}です！";

//[return=1]がないアクセス(初回アクセス)の場合
//[手順1] pocketからリクエストトークンを取得する、の部分
}else{

	//CSRF対策
	session_regenerate_id(true);
	$state = sha1(uniqid(mt_rand(),true));
	$_SESSION['state'] = $state;

	//リダイレクトURLにパラメータを追加
	$redirect_uri .= "?return=1";

	//リクエストトークンを取得
	$data = @file_get_contents(
		'https://getpocket.com/v3/oauth/request',
		false,
		stream_context_create(
			array('http' => array(
				'method' => 'POST',
				'content' => http_build_query(array(
					'consumer_key' => $consumer_key,
					'redirect_uri' => $redirect_uri,
					'state' => $state,
				)),
			))
		)
	);

	//関数[get_query_syncer]を使って、GETパラメータ形式の文字列を配列に変換
	$query = get_query_syncer($data);

	//リクエストトークンを取得できなければエラー
	if(!isset($query['code']) || empty($query['code'])){ error_pk_syncer('リクエストトークンが取得できませんでした。多分コンシューマーキーの設定が間違っています。'); }

	//セッションに保存したstateの値と、返って来たstateの値が違ったらエラー
	if(!isset($query['state']) || empty($query['state']) || $_SESSION['state'] != $query['state']){ error_pk_syncer('セッションが上手く機能してないかもしれません…。'); }

	//セッションにリクエストトークンの値を格納しておく
	$_SESSION['code'] = $query['code'];

	//ユーザーをアプリ認証画面へアクセス(リダイレクト)させる
	//[手順2] ユーザーがそのリクエストトークンを持って、pocketの「アプリ認証画面」にアクセスする、の部分
	header("Location: https://getpocket.com/auth/authorize?request_token={$query['code']}&redirect_uri={$redirect_uri}");
}

//文字化けさせないための最低限のヘッダー
$header = '<!DOCTYPE html><html><head><meta charset="utf-8"></head><body>';

//エラー処理をする関数
function error_pk_syncer($message){
	session_finish_pk_syncer();
	echo $header.$message;
	exit;
}

//セッションを終了する関数
function session_finish_pk_syncer(){
	$_SESSION = array();
	session_destroy();
}

//GETパラメータ形式の文字列(例：a=b&c=d...)を配列(例：$query['a']=b、$query['c']=d...)に変換する関数
function get_query_syncer($data){
	$ary = explode("&",$data);
	foreach($ary as $items){
		$item = explode("=",$items);
		$query[$item[0]] = $item[1];
	}
	return $query;
}

2-3サンプルプログラムを利用したアプリ認証のイメージ

サンプルプログラムを利用した、アプリ認証の流れは次の通りです。確認しながら、少しずつ進んでみて下さい。

アプリ認証画面

プログラムにアクセスすると、アプリの認証画面に移動するので、「認可」をクリックして下さい。左側には、アプリ登録の際にしたパーミッションの設定が反映されています。画像はクリックすると拡大できます。

アクセストークンを確認する

「認可」をクリックすると、ブラウザにアクセストークンが表示されます。このアクセストークンを利用して、アプリ側はユーザーのデータに、設定したパーミッションのレベルに応じてアクセス(情報を読み取ったり、書き込んだり)することが可能になります。実際にwebサービスを作る場合は、このアクセストークンをデータベースなどに保存して管理することになります。

3ユーザーデータを読み込んでみよう

コンシューマーキーとアクセストークンを取得したので、ここからは実際に簡単なプログラムを一緒に作って、APIを利用していきましょう。まずはパーミッションで言うRetrieve(読み取り)の権限を利用してみます。Retrieveに関する公式ドキュメントは下記のページで確認できます。

3-1Retrieveのリクエスト方法

Retrieve権限を利用するためには、下記のURLにPOSTメソッドでリクエストを送ります。

指定できるパラメータ

どんなアイテム(pocketした記事)を、どれだけ読み込むかを、下記のパラメータで指定することができます。[]内が、指定するパラメータの値となります。

取得できるJSONデータ

リクエストに成功すると、下記のJSONデータを取得することができます。アイテムはlistプロパティに配列形式で格納されています。サンプルの赤で囲った部分が1つ分のアイテムデータです。主要なデータには青文字でコメントを入れています。アイテムIDは主に「Modifyの権限」で利用することになります。

{
  "status": 1,
  "complete": 1,
  "list": {
    "549631528": {
      "item_id": "549631528", //アイテムID
      "resolved_id": "549631528",
      "given_url": "http://www.yahoo.co.jp",
      "given_title": "",
      "favorite": "0", //1ならお気に入り状態
      "status": "0", //0=未読、1=期読
      "time_added": "1392739451", //pocketした日(UNIX TIMESTAMP形式)
      "time_updated": "1395591387",
      "time_read": "0",
      "time_favorited": "0",
      "sort_id": 0,
      "resolved_title": "ページタイトル", //ページタイトル
      "resolved_url": "http://www.yahoo.co.jp", //ページURL
      "excerpt": "ページのdescription", //ページの概要
      "is_article": "1", //1なら記事
      "is_index": "0",
      "has_video": "0", //1なら動画が含まれる
      "has_image": "1", //1なら画像が含まれる
      "word_count": "559",
    },
    ...
  }
  "since": 1396892671
}

3-2pocketのアイテムを読み取るサンプルプログラム

以上を踏まえたサンプルプログラムが下記です。$consumer_key、$access_tokenを設定してアクセスするだけで起動します。パラメータ部分を連想配列形式で指定して、色々と試してみて下さいね！

<?php
//設定項目
$consumer_key = "";	//コンシューマーキー
$access_token = "";	//アクセストークン

//パラメーター
$params = array(
	"state" => "unread",	//未読の記事のみ
	"count" => "10",	//記事10件
	"sort" => "newest",	//新しい順
	"since" => strtotime('2013/1/1'),	//2013/1/1以降
	"detailType" => "complete",	//詳しいデータ
);

//パラメーターにコンシューマーキーとアクセストークンを追加
$params = array_merge($params,array("consumer_key" => $consumer_key,"access_token" => $access_token,));

//アイテムデータをJSON形式で取得する
$json = @file_get_contents(
	"https://getpocket.com/v3/get",
	false,stream_context_create(array('http' => array(
		'method' => 'POST',
		'content' => http_build_query($params),
	)))
);

//JSONデータをオブジェクト形式に変換する
$obj = json_decode($json);

//個々のアイテムを出力する
foreach($obj->list as $item){
	//アイテムのID
	$id = $item->item_id;

	//アイテムのタイトル
	$title = $item->resolved_title;

	//アイテムのURL
	$url = $item->resolved_url;

	//お気に入りにしているか？
	$fav = ($item->favorite == 1) ? '★' : '';

	//pocketした日付(ついでに整形)
	$date = date('Y/m/d H:i',$item->time_added);

	//ブラウザに出力
	echo "<p>アイテムID：{$id}<br/><a href=\"{$url}\">{$fav}{$title}</a>({$date}にpocket)</p>";
}

プログラムの実行結果

サンプルプログラムを実行すると、これまでにpocketしたアイテムのデータが出力されます。一度プログラムが正常に起動するのを確認したら、リクエストするパラメータを変更したりして、感覚を掴んでみて下さいね。画像はクリックで拡大できます。

特定のタグで検索する

例えば、タグでアイテムを検索したい場合、パラメータを次のように変更します。hatebumanというタグを付けたアイテムだけが出力されます。

//パラメーター
$params = array(
	"state" => "all", //未読・既読を指定しない
	"tag" => "hatebuman",
);

特定のキーワードで検索する

例えば、キーワードでアイテムを検索したい場合は、パラメータを次のように変更して下さい。「はてブマン」というタグを付けたアイテムだけが出力されます。ちなみに、タグやキーワードは複数指定ができません。

//パラメーター
$params = array(
	"state" => "all", //未読・既読を指定しない
	"search" => "はてブマン",
);

お気に入りにしたアイテムのみを検索する

お気に入りにしたアイテムのみを検索したい場合は、パラメータを下記のように変更して下さいね！

//パラメーター
$params = array(
	"state" => "all", //未読・既読を指定しない
	"favorite" => 1,
);

アイテム総数を取得

例えば、「そのユーザーがこれまでにpocketした総アイテム数」を表示させたい場合は、下記のようにデータを取得します。サンプルの29行目に挿入して下さい。正確には「このリクエストで取得したアイテム数」なので、countパラメータは指定しないで下さい。サンプルだと9行目で10と指定してます。

//全アイテム数
$all = count((array)$obj->list);

//全アイテム数を出力
echo "
総アイテム数：{$all}
";

3-3Retrieveを使ったwebサービスのアイデア

Retrieveを使えばどんな機能を実現できるか？そのアイデアを紹介します。

今までのアイテムをランダムで表示

ユーザーが今までにpocketしたアイテムの中から、ランダムで10件だけ表示するwebサービス、「ランダムpocket君(仮)」というプログラムを作ってみましょう。それには、まずサンプルのパラメータ部分を次のように変更します。

//パラメータ (全ての記事を指定)
$params = array(
	"state" => "all",
);

そして、サンプルの26行目(アイテムデータを取得して)以降を、次のように書き換えてみて下さい。json_decode()の第2引数にtrueを指定すると、JSONデータをオブジェクトではなく、連想配列形式に変換することができます。

//JSONデータをオブジェクトではなく、連想配列形式に変換する
$array = json_decode($json,true);

//アイテムリストの配列を変数に格納
$itemlist = $array['list'];

//アイテム数を調べる
$itemcount = count($itemlist);

//アイテム個数が15件以下の場合はエラー
if(15 > $itemcount){
	echo 'もっとpocketしてから来て下さい!!';
	exit;
}

//アイテム配列の中から、ランダムで10個のキーを取得
$keylist = array_rand($itemlist,10);

//選ばれたキーのアイテムを出力する
foreach($keylist as $item){
	//アイテムのID
	$id = $itemlist[$item]['item_id'];

	//アイテムのタイトル
	$title = $itemlist[$item]['resolved_title'];

	//アイテムのURL
	$url = $itemlist[$item]['resolved_url'];
 
	//お気に入りにしているか？
	$fav = ($itemlist[$item]['favorite']== 1) ? '★' : '';
 
	//pocketした日付(ついでに整形)
	$date = date('Y/m/d H:i',$itemlist[$item]['time_added']);
 
	//ブラウザに出力
	echo "<p>アイテムID：{$id}<br/><a href=\"{$url}\">{$fav}{$title}</a>({$date}にpocket)</p>";
}

このように更新するごとに、アイテムが10件、ランダムで表示されると思います。実際にはアイテム数が500個、1000個、5000個…と多くなるとそれだけ処理に負荷がかかるので、1日ごとに1回だけランダムでアイテムを抽出する、といったような仕組み作りが必要だと思います。

4アイテムを追加してみよう

前章では、ユーザーがpocketしたアイテムを読み込む方法を紹介しました。今回は、PHPプログラムを通して、ユーザーのリストにアイテムを追加してみましょう。パーミッションでいうAdd(書き込み)の権限を利用します。公式ドキュメントは下記ページをご参考下さい。

4-1Addのリクエスト方法

Add権限を利用してアイテムを追加するには、下記のURLにPOSTメソッドでリクエストを送ります。

指定できるパラメータ

アイテム追加のリクエストを送る際は、下記のパラメータを送信することができます。Addの場合、一度に1つのアイテムしか追加することができません。一度に複数のアイテムを追加したい場合は、後述の「Modifyの権限」を利用することになります。

取得できるJSONデータ

リクエストが成功すると、下記のJSONデータを取得することができます。アイテムを追加するのが目的なら、「JSONデータを取得する必要はないんじゃないか？」と思うかもしれませんが、成功判定や、結果表示をする場合に便利ですね。主要なデータに青文字で説明コメントを付けてあります。

{
  "item": {
    "item_id": "23564995", //アイテムのID
    "normal_url": "https://google.co.jp",
    "resolved_id": "23564995",
    "extended_item_id": "23564995",
    "resolved_url": "https://www.google.co.jp/", //アイテムのURL
    "domain_id": "1565",
    "origin_domain_id": "1565",
    "response_code": "200",
    "mime_type": "text/html",
    "content_length": "11832",
    "encoding": "shift_jis",
    "date_resolved": "2014-04-06 05:07:26", //アイテムの追加日
    "date_published": "0000-00-00 00:00:00",
    "title": "Google", //アイテムのタイトル
    "excerpt": "Googleは検索をするためのページです。", //アイテムの概要
    "word_count": "33",
    "innerdomain_redirect": "0",
    "login_required": "0",
    "has_image": "0",
    "has_video": "0",
    "is_index": "1",
    "is_article": "0",
    "used_fallback": "1",
    "resolved_normal_url": "http://google.co.jp",
    "given_url": "https://google.co.jp/"
  },
  "status": 1 //1ならリクエスト成功
}

4-2pocketにアイテムを追加するサンプルプログラム

以上を踏まえたサンプルプログラムが下記です。$consumer_key、$access_tokenを設定してアクセスするだけで起動します。起動後、自分のリストに指定したアイテム(URL)が加わっているかを確認してみて下さいね。

<?php
//設定項目
$consumer_key = "";	//コンシューマーキー
$access_token = "";	//アクセストークン

//パラメーター
$params = array(
	"url" => "http://syncer.jp/pocket-api-matome", //追加するURL
	"tags" => "test,すぐ消す", //アイテムに付けるタグ
);

//パラメーターにコンシューマーキーとアクセストークンを追加
$params = array_merge($params,array("consumer_key" => $consumer_key,"access_token" => $access_token,));

//アイテムを追加するリクエストをPOSTメソッドで送る
$json = @file_get_contents(
	"https://getpocket.com/v3/add",
	false,stream_context_create(array('http' => array(
		'method' => 'POST',
		'content' => http_build_query($params),
	)))
);

//JSONデータをオブジェクト形式に変換する
$obj = json_decode($json);

//成功判定
if(!isset($obj->status) || !$obj->status){
	echo '追加に失敗しました…。';
	exit;
}

//アイテムのID
$id = $obj->item->item_id;

//アイテムのタイトル
$title = $obj->item->title;

//アイテムのURL
$url = $obj->item->resolved_url;

//pocketした日付
$date = $obj->item->date_resolved;

//ブラウザに出力
echo "<p>アイテムリストに{$title}を追加しました！<br>URL：{$url}</p>";

4-3Addを使ったwebサービスのアイデア

Addを使えば、webサービス内に、オリジナルの「あとで読む」ボタンを設置することが可能ですが、それだけでは普通ですよね…。次のような機能が、例えばブログにあったら面白いんじゃないでしょうか？

最新記事をpocketに届ける配達機能

RSSをpocketで実現します。「私のブログの新着記事をpocketで受け取る」というボタンを設置しておき、希望のユーザーにアプリ認証をしてもらい、アクセストークンをデータベースに保存しておきます。後は、ブログを更新する度に、またはcronを利用して定期的に、認証をしているユーザー全員のpocketに新着記事をアイテムとして追加するという仕組みです。

pocketを活用しているユーザーならば、わざわざ記事にアクセスしないで、pocketに自動的に新着記事が追加されるので大変便利ですよね。ブログ側も新着記事を発行する度に、登録人数分だけpocketのカウントが増えるし、記事が届いたユーザーが訪問してくれることでPVを確保することができちゃいます。

1章の「OAuth認証」と、この3章の「Add(アイテムの追加)」を利用すれば、実現できますよね。よろしければ、独自のpocket宅配便を、ブログやwebサイトに設置してみて下さい。

5アイテムを変更してみよう

Retrieve(アイテムの読み込み)、Add(アイテムの追加)と、紹介してきました。最後は、pocketのAPIの中でも、一番強力な権限、Modify権限でAPIを利用してみましょう！公式ドキュメントは下記のページにあります。

5-1Modifyのリクエスト方法

Modify権限を利用してアイテムを変更するには、下記のURLにPOSTメソッドでリクエストを送ります。

指定できるパラメータ

このModify権限のリクエストには、ちょっとクセがあります。少しずつ説明していきますね。まず、基本となるリクエストパラメータは次の3つです。

actionsで指定できるパラメータ

actionsには、アイテムを変更するために用意された様々なアクションを、JSON形式で指定することができます。1つのアクションには複数のパラメータがあり、それらをセットで1まとめにしてJSONにする必要があるんです。言葉で言っても分からないのでサンプルを…。

例えば、「IDが999999のアイテムを既読状態にする」を実行するには、actionsの値に次のようにJSONデータを文字列で指定します。分かりやすいように、プロパティを赤文字に、データを青文字にしています。

[{
  "action":"archive",
  "item_id":"999999",
  "time":"1403449200"
}]

actionのarchiveが「既読にするアクション」を表していて、item_idでアイテムのIDを、timeで変更の記録時間を指定しているわけです。これらを上記のような1まとめのJSONデータにして、actionsパラメータに指定する形になります。

Modifyでは1度に複数のアクションを指定することができて、その場合は次のように指定します。IDが999999(赤)と、888888(青)の記事を1回のリクエストで既読状態にする場合のサンプルです。

[{
  "action":"archive",
  "item_id":"999999",
  "time":"1403449200"
},
{
  "action":"archive",
  "item_id":"888888",
  "time":"1403449200"
}]

[]の中に、,(カンマ)で区切った2つのJSONデータを含める形です。さて、これらのJSONデータは、いちいち文字列として書き出すのは大変なので、PHPの場合だったら、json_encode()という関数で配列から変換するのが便利です。例えば、上記のサンプルの場合、次のようになります。

//多次元の連想配列を用意する
$action = array(	//2つの配列を覆う配列が[〜]の部分

	array(	//999999を既読にするアクション
		'action' => 'archive',
		'item_id' => '999999',
		'time' => '1403449200',
	),
	array(	//888888を既読にするアクション
		'action' => 'archive',
		'item_id' => '888888',
		'time' => '1403449200',
	),

);

//多次元の連想配列をJSONデータに変換する
$json = json_encode($action);

このようにして、先ほどサンプルで紹介したJSONデータを作成することができます。これなら、PHPに標準で備わっている配列の追加や削除といった処理をした後、最後にjson_encode()でJSONデータに変換すればいいだけだから簡単ですよね！

5-2actionsに指定できるパラメータ

それでは、Modifyのactionsに指定できるパラメータを紹介していきます。Addでは1回のリクエストにつき、1つしかできなかった「アイテムの追加」が、Modifyの場合は1度に何件でも指定することができます。

例えば、pocketのID:999999のアイテムの、hatebumanというタグをfunassyiに変換するには、次のようにactionsのパラメータを作成します。

//多次元の連想配列を用意する
$action = array(
	array(
		'action' => 'tag_rename',
		'item_id' => '999999',
		'old_tag' => 'hatebuman',
		'new_tag' => 'funassyi',
	),
);

//多次元の連想配列をJSONデータに変換する
$json = json_encode($action);

はたまた、pocketのID:888888のアイテムの既読状態を未読状態に直すには、次のようにactionsのパラメータを作成します。

//多次元の連想配列を用意する
$action = array(
	array(
		'action' => 'readd',
		'item_id' => '999999',
	),
);

//多次元の連想配列をJSONデータに変換する
$json = json_encode($action);

もちろん、2つのアクションを同時に指定することも可能です。配列の中身を随時、増やせばいいだけですねー。

//多次元の連想配列を用意する
$action = array(
	array(
		'action' => 'tag_rename',
		'item_id' => '999999',
		'old_tag' => 'hatebuman',
		'new_tag' => 'funassyi',
	),
	array(
		'action' => 'readd',
		'item_id' => '999999',
	),
);

//多次元の連想配列をJSONデータに変換する
$json = json_encode($action);

5-3pocketにアイテムを追加するサンプルプログラム

以上を踏まえたサンプルプログラムを用意しました。$consumer_key、$access_tokenを設定してアクセスしてみて下さい。起動すると、このサイトの3つのページがpocketに追加されるはずです。その後、不要でしたら削除して下さい…。

<?php
//設定項目
$consumer_key = "";	//コンシューマーキー
$access_token = "";	//アクセストークン

//多次元の連想配列を用意する
$action = array(
	array(
		'action' => 'add',
		'url' => 'http://syncer.jp/jquery-to-top-button',
	),
	array(
		'action' => 'add',
		'url' => 'http://syncer.jp/hatebu-api-matome',
	),
	array(
		'action' => 'add',
		'url' => 'http://syncer.jp/web-logo-page',
	),
);
 
//作成した連想配列をJSON形式に変換
$json = json_encode($action);
 
//アイテム変更のリクエストをPOSTメソッドで送る
$result = @file_get_contents(
	"https://getpocket.com/v3/send",
	false,stream_context_create(array('http' => array(
		'method' => 'POST',
		'content' => http_build_query(array(
			"actions" => $json,
			"consumer_key" => $consumer_key,
			"access_token" => $access_token,
		)),
	)))
);

//返ってきたJSONデータをオブジェクト形式に変換
$obj = json_decode($result);

//成功判定
if(!isset($obj->status) || !$obj->status){
	echo '追加に失敗しました…。';
	exit;
}

//結果を出力
echo 'リクエストに成功しました！';

「Retrieveの権限」でアイテムを読み込むことで、アイテムIDを取得できます。この「アイテムID」を利用して、「追加」以外のModifyの権限のアクションを試してみて下さいね！

6pocketのAPI周りの情報いろいろ

使用制限やエラーコードなど、pocketのAPIを利用する上で役に立つ、関連情報を紹介します。

6-1レートリミット(使用制限)について

現在、pocketのAPIには、下記の通りレートリミット(使用制限)が定められています。通常の使用では超えることのない回数ですが、意識はしておきましょう。

レートリミットの内容

例えば、あなたが作ったアプリに、AさんとBさんというユーザーがいて、彼らは1時間につき320回ずつしか、あなたのアプリを通してAPIを利用できません。が、あなたのアプリの方は合計10,000回、APIを利用することができるため、AさんとBさんがフルで使っても、残り9,360回、APIを利用(提供)することができるわけです。

仮にレートリミットを超えた場合、最初の使用から1時間後の時点になるまで、APIを利用することができなくなります。

レートリミットの確認方法

レートリミットはAPIリクエストを送った際のレスポンスヘッダーの中に含まれています。PHPで説明すると、リクエストを送った後、自動的に配列の$http_response_headerに、次のように格納されます。配列のうち、キーの10〜15番目(赤文字)に含まれているのがレートリミットの情報です。

Array
(
  [0] => HTTP/1.1 200 OK
  [1] => Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
  [2] => Content-Type: application/json
  [3] => Date: Wed, 09 Apr 2014 19:33:16 GMT
  [4] => Expires: Thu, 19 Nov 1981 08:52:00 GMT
  [5] => P3P: policyref="/w3c/p3p.xml", CP="ALL CURa ADMa DEVa OUR IND UNI COM NAV INT STA PRE"
  [6] => Pragma: no-cache
  [7] => Server: Apache
  [8] => Set-Cookie: PHPSESSID=albs58d2mbul4c7d77idd91ib5; path=/
  [9] => Status: 200 OK
  [10] => X-Limit-Key-Limit: 10000
  [11] => X-Limit-Key-Remaining: 9995
  [12] => X-Limit-Key-Reset: 3540
  [13] => X-Limit-User-Limit: 320
  [14] => X-Limit-User-Remaining: 315
  [15] => X-Limit-User-Reset: 3540
  [16] => X-Source: Pocket
  [17] => Content-Length: 1253
  [18] => Connection: Close
)

例えばRetrieveのサンプルプログラムだったら、26行目にecho $http_response_header[11];を加えて起動してみて下さい。X-Limit-Key-Remaining: 9995が表示されるはずです。

レスポンスヘッダーの各キーの説明

6-2ステータスコードについて

レスポンスヘッダーの1つ目のキー(0番)にはステータスコードの情報が格納されています。ステータスコードは、APIリクエストが成功したのか、また、エラーだったのなら何がいけなかったのか、を判断する情報となります。例えば下記、200だったら「リクエストは成功」です。

Array
(
  [0] => HTTP/1.1 200 OK
  ...
)

pocket APIのステータスコードの詳細は、下記の公式ドキュメントで確認することができます。APIのリクエストが上手くいかない場合は、エラーになる原因を、ステータスコードをヒントに探しましょう。

ステータスコードの一覧

7pocketのAPIを利用して制作されたwebサービスの事例いろいろ

最後に、pocketのAPIを利用して制作されたwebサービスを紹介します。「何かを作りたくなる！」と、制作欲求を刺激される素晴らしい作品ばかりです！

7-1RandomPocket

現在は閉鎖されています。pocketに入れたアイテムの中から、未読の記事をランダムで表示してくれるwebサービスです。「”あとで読む”は”一生読まない”説」を主張する私としては、こういった振り返る「きっかけ」を提供してくれるwebサービスは物凄く素晴らしいと思いました。

7-2RocketSS

登録したRSSの新着記事を、自動でpocketに送ってくれるwebサービスです。pocketユーザーは、これがあれば、RSSと「おさらば」できちゃいますね。

7-3Lisgo

こちらはiPhoneアプリです。Lisgoはpocketに登録してあるアイテムを、音声で読み上げてくれるサービスです。「読む」って行為はそれだけに時間を使わなければならず、多くの場合「やらず終い」になりますが、音声で読み上げてくれるなら、他の何かをやりながら「ついでに」記事を消化していけます。素晴らしいアイデアだと思います。

7-4Pinpockit

pocketに登録してあるアイテムを、Pinterest風に表示するwebサービスです。「より見やすく」だとか、「〜風に」だとか、見栄えを変えるだけでも立派なサービスになりますよね！

7-5IFTTT

pocketのAPIを利用したwebサービスとして「IFTTT」も忘れてはいけませんよね。「pocketしたら○○をする」「○○をしたらpocketする」といった、「他のwebサービスとの連携」をサポートするために、APIを利用するのも有用ですねー。そういえば、はてブをするとpocketしてくれる連携サービスってないんですね…。

8はてブをするとpocketしてくれるPHPプログラム

…ということで、ひょんなことから、「はてブ」と「pocket」を連携する簡単なPHPプログラムを作成してみました！レンタルサーバーなど利用していてサーバー環境のある人は、よろしかったら使ってみて下さい。

「はてなブックマーク」でブックマークをすると、Web Hook経由で、このプログラムにリクエストが送られて、このプログラムがpocketのアイテムに「はてブしたURL」を追加する、という仕組みです。

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

はてなブックマークのWeb Hookについては、下記の記事の第9章をご参考下さい。上記図のように、「ブックマークの追加/更新/削除」にチェックを入れて下さいね。

8-2PHPプログラム

下記のプログラムを、hatebu-pocket.phpとして、サーバー上に設置して下さい。URLはWeb Hookの設定と合わせて下さいね！なお、pocketのアプリのパーミッションはAddのみで大丈夫です。

<?php
//はてブで、設定したweb hookのキー
$webhook = '3OC0RB3W8C6W5RPM';

//pocketアプリのコンシューマーキー
$consumer_key = '';

//pocketのアクセストークン
$access_token = '';

//タグを付けておきたい場合に指定(複数の場合は半角カンマで区切る)
$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(!$url = (string)$obj->item[0]->link) exit;

//pocketに追加する
file_get_contents(
	"https://getpocket.com/v3/add",
	false,stream_context_create(array('http' => array(
		'method' => 'POST',
		'content' => http_build_query(array(
			"url" => $url,
			"tags" => $tags,
			"consumer_key" => $consumer_key,
			"access_token" => $access_token
		))
	)))
);

8-3使用イメージ

はてブをしたページが、自動的にpocketに追加されるようになります。指定したタグもちゃんと反映されていますね。「これで”はてブ”に対応してないIFTTTなんか要らない！」は言い過ぎでしょうか…？

APIって本当に面白いですよね。この記事が、ほんの少しでも、みなさんのWebサービスの制作欲を刺激することになったら幸いです。読んでいただけた方、ありがとうございました！

この記事へのコメント

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

コメントを書き込む

• コメント
• ログイン

お名前 :

• Twitterでログイン(認証)する
• Facebookでログイン(認証)する
• はてなでログイン(認証)する

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

現在、1件のコメントがあります。

あらゆ
2014.06.24 07:17

はてブに続いて、pocket版を作成してみました！ 自分もまだまだ分からないことばかりですが、こうやってまとめていくことで、勉強になります。 もし不明な点などありましたら、このコメント欄で気軽に教えて下さい。