Aikの技術日記

技術的な進捗とか成果とかを細々と投稿するブログです。時々雑記も。

トップ > その他 > PocketAPI使ってみた-Part1 - 概要とユーザー認証編

PocketAPI使ってみた-Part1 - 概要とユーザー認証編

その他 Part1

はじめに

こんにちは、筆者です。

突然の話とはなりますが、だーいぶ前に投稿したこちらの記事:
aik0aaat.hatenadiary.jp

…にて紹介しました「inoreader + Pocket」での情報収拾方法を、筆者はまだまだ利用しておりまして。
ストック型の情報収拾方法が筆者的に合うのか…技術系や趣味のイラスト系、はては宇宙学や医学など…。
様々な最新情報やトレンド情報、果ては面白情報などいろんな情報を収拾しています。

ただ、こんなに多方向に情報を集めていると、ストック用のPocket内部のアーカイブがすごいことになってまして。
そもそもPocket使ってたのは「面白いと思った知識や貴重な情報を、後から見返しやすいように」するためのはず…。

なんとかPocket内部の情報を整理したいなと思っていると、なんとPocketは公式がAPIを提供してくれていることがわかり。
このAPIを経由すれば、Pocket内部の情報取得はもちろん「タグ付け」とか「読んでない記事の一覧を出したり」とかいろんなことができそうな予感が…！

…というわけで、Pocket　APIをちょっと触ってみようかなと。
今回の記事では「Pocket APIの概要」やAPIを触るための第一段階「API認証を通す」ところまでやっていこうかなと！

それではいきましょー！！

Pocket APIの概要

Pocket APIはその名の通り、Pocket公式が提供してくれているAPIサービスです。
公式ドキュメントは下記に:

getpocket.com

現状のAPIは「v3」という形で提供されており、下記の3つの機能が使えます:

  • Add: 特定の1つの記事をPocketに追加する、タグ付けも可能
  • Modify: Pocket上にあるユーザーのデータなどを変更可能
  • Retrieve: Pocket上にあるユーザーのデータなどを取得可能

また、これとは別に「Authentication」…認証に関するAPIもあります。
Pocket APIを実際にユーザーに使わせるために必要なAPIですね。

また、公式から様々なユースケースを想定した「Getting Started」記事も公開してくれています。
iOS/MacアプリやAndroid、Windowsアプリ、Webからの使用を想定した記事が公開されています。
※本記事では特に断りない限り、Webでの使用を想定した内容となっております

APIを使うには

Pocket APIを使うには、大きく分けて2つのことが必要です:

  1. Pocket APIアプリケーショントークン(コンシューマーキー)の取得
  2. アプリケーション使用ユーザーのAPIアクセストークンの取得

1の方はPocketのDeveloperドキュメントから行うことができます。
2の方は、1で作成したアプリケーショントークンを用いて自力で取得せねばなりません。
((ぶっちゃけ2はOAuth認証をやってるだけです

Pocket APIアプリケーショントークンの取得

Pocket APIアプリケーショントークンの取得は、下記のページから行うことができます:
Pocket: Log In

アプリケーション名やアプリケーションの説明、Permission(Add/Modify/Retrieveのどの権限があるかを選択)、そしてどのプラットフォームを選ぶかを選択し「CREATE APPLICATION」ボタンを押します。
CREATEボタンを押せばすぐに作成できるため、恐らく内容の審査はな以下と思われますので…。
TwitterのAPIほど、各項目を厳格に書く必要はないかと思います。

※作成時の注意事項

  • Permissionの項目はアプリケーション作成後に変更ができないため、ある程度慎重に選んだ方がいいかもです
  • アプリケーションの名前にはちょっとしたガイドラインがあるそうです:
    • 目的は「Pocketのアプリケーションではなく、作成者自身のアプリケーションであることを示すため」
    • 例えば「Pocket」や「Read It Later」という名称をアプリケーション名に含めることは不可能だそうで…
    • 迷ったときは「TwitterのAPIを使用したアプリケーションの名前(TweetDeckやTweetbotなど)を参考にするといいとのこと
    • 詳しくは→Pocket Developer Program: FAQ: Application Names

作成後はMy Appsというページに登録したアプリケーションが表示されます。

"アプリケーション作成後のMy Apps"
こんな感じ

ここまでくれば取得は完了です。
Pocket APIにて度々要求されるアプリケーショントークン…もとい「コンシューマーキー」を使う際は、上記のCONSUMER KEYという欄を使いましょう。

なお公式側では、iOSやMacアプリ、Androidなど複数のプラットフォームにてPocket APIを使用する際は「1プラットフォームごとにアプリケーショントークンを取得する」ことを推奨しています。
※参考記事: Pocket Developer Program: Pocket Authentication API: Documentationの「Best Practices」の章
マルチプラットフォーム型のアプリを作る際は、面倒かもですが各々のPocket APIを発行しといた方がいいかもです。

アプリケーション使用ユーザーのAPIアクセストークンの取得

お次はユーザー側のアクセストークンの取得です。
これには「Pocket Authentication API」というOAuth2.0を用いたAPIを使います。
getpocket.com

このAPIには下記のような色々制約があります:

  • HTTPS経由で実行すること
  • POSTリクエストのみ
  • Content-Typeヘッダーは下記のみ許可:
    • application/x-www-form-urlencoded(デフォルト値)
    • application/json
  • X-Acceptヘッダー(応答を受信する形式)は下記のみ許可:
    • application/x-www-form-urlencoded(デフォルト値)
    • application/json

これらに注意しつつ、APIを叩いていきましょう。
具体的なフローは下記の通り:

  1. OAuth認証のリクエストトークンを取得
    • URL: https://getpocket.com/v3/oauth/request
    • パラメータ:
      • consumer_key: アプリケーションアクセストークン(コンシューマーキー)
      • redirect_uri: 認証プロセスが完了したときに呼び出されるURL
    • 返却値:
  2. Pocketへリダイレクトして認証を続行
    • URL: https://getpocket.com/auth/authorize?request_token=[1.で取得したcode値]&redirect_uri=[自分のURL]
    • 認証が完了するとredirect_uriで指定したURLにリダイレクトされる
  3. ユーザーのアクセストークンを取得
    • URL: https://getpocket.com/v3/oauth/authorize
    • パラメータ:
      • consumer_key: アプリケーションアクセストークン(コンシューマーキー)
      • code: 1.で取得したcode値
    • 返却値:
      • access_token: ユーザーのアクセストークン
      • username: ユーザー名

これでユーザーのアクセストークンが取得完了です。

ちなみに筆者は、REST APIクライアント「Talend API Tester - Free Edition」を使って上記APIを叩きました。
※リダイレクトとかは手動でURLを打ち込んでいきました
chrome.google.com

こちらのAPIクライアントは仕事でも使っているものですが、

  • ローカル環境下で使用可能
  • GETやPOSTリクエストはもちろん、RequestHeaderも自由にいじることが可能
  • 作成したAPIをエクスポート可能
  • もちろん既存APIのインポートも可能(Swaggerからも可能)

…といった特徴を持つなかなかの優れモノ。
せっかくなので、筆者が作ったPocket API認証用のAPI群をインポートできるjsonファイルを下記においておきます。
TalendApiTester_PocketApi_ExportData.json

なお、公式からPocket Objective-C SDKなるものが公開されており…。
iOSやMacアプリを構築する際は、このSDKを用いれば上記にある面倒なことをすっ飛ばせてアクセストークンを取得できるそうです！
iOSやMacアプリでPocket APIを使う方はぜひこちらを|дﾟ*)つ

余談その1: Pocket APIの回数制限について

Pocket APIを叩ける回数には制限があり、下記のような数値に決まっております:

  • 各ユーザー1時間あたり320コール
    • 1分あたり平均約5.3コール
  • 各アプリケーション1時間あたり10000コール
    • 1分あたり平均約167コール

ちなみに、1分あたり平均5コールAPIを呼ぶアプリケーションを作ると…アクティブユーザーを33人程度にまで抑えないといけません。かなりシビアですね…。

また、この制限を無視し続けているとアプリケーショントークンが無効化されることもあるそうです…。
じゃあアプリケーション作成者が「1時間あたりのコール数を管理してなきゃいけないか」というと、そうでもなく。
実はPocket APIの応答ヘッダーには「ユーザー」と「アプリケーショントークン」両方に対するレート制限のステータス値も一緒に返ってきます。

  • X-Limit-User-Limit: ユーザーごとに適用される現在のレート制限
  • X-Limit-User-Remaining: ユーザーのレート制限に達する前に残っているコールの数
  • X-Limit-User-Reset: ユーザーのレート制限がリセットされるまでの秒数
  • X-Limit-Key-Limit: アプリケーショントークンごとに適用される現在のレート制限
  • X-Limit-Key-Remaining: アプリケーショントークンがレート制限に達する前に残っているコールの数
  • X-Limit-Key-Reset: アプリケーショントークンのレート制限がリセットされるまでの秒数

中規模程度のアプリケーションを作るときは、上記の応答ヘッダー値をちゃんと見るようにした方が無難かと。
Pocket APIの回数制限について、詳しくはこちらを参照に…: Pocket Developer Program: FAQ: Rate Limits

余談その2: ブログ等に配置可能なアイコン設置について

APIとはあまり関係ないですが…。
Pocket APIのドキュメントを漁ってると、ブログ等に配置可能な「Pocketへ記事を追加するアイコン設置方法」に関する記事があったのでちょいとまとめてみました。
Pocket for Publishers: Pocket Button

アイコンはどうも3種類の見た目のものがあるようで…。

※貼り付けに使用しているコードはこちら↓

<!--1つ目のボタン-->
<a data-pocket-label="pocket" data-pocket-count="none" class="pocket-btn" data-lang="ja"></a>
<script type="text/javascript">!function(d,i){if(!d.getElementById(i)){var j=d.createElement("script");j.id=i;j.src="https://widgets.getpocket.com/v1/j/btn.js?v=1";var w=d.getElementById(i);d.body.appendChild(j);}}(document,"pocket-btn-js");</script>
<!--2つ目のボタン-->
<a data-pocket-label="pocket" data-pocket-count="horizontal" class="pocket-btn" data-lang="ja"></a>
<script type="text/javascript">!function(d,i){if(!d.getElementById(i)){var j=d.createElement("script");j.id=i;j.src="https://widgets.getpocket.com/v1/j/btn.js?v=1";var w=d.getElementById(i);d.body.appendChild(j);}}(document,"pocket-btn-js");</script>
<!--3つ目のボタン-->
<a data-pocket-label="pocket" data-pocket-count="vertical" class="pocket-btn" data-lang="ja"></a>
<script type="text/javascript">!function(d,i){if(!d.getElementById(i)){var j=d.createElement("script");j.id=i;j.src="https://widgets.getpocket.com/v1/j/btn.js?v=1";var w=d.getElementById(i);d.body.appendChild(j);}}(document,"pocket-btn-js");</script>

data-pocket-count属性の値によって見た目を変えられるっぽいです。
また、独自にPocketへの追加リンクも貼れそうです…。
「公式が提供してくれているボタンではなく、独自にPocket追加ボタンを作りたい！」となったときに参考にしてみるのもいいのかもです。
https://getpocket.com/publisher/button_docs

おわりに

今回はとりあえず認証までをやってみました。
Talend API Testerのおかげで、ここまでやるのがニコ動片目に見ながらできる程度に簡単にできました。いい時代だぁ…。

また、Pocket APIを使うときに何か困ったことになった際は、こちらのFAQページが参考になるかもです。
Pocket公式が提供されているFAQなので…きっと正確度も高いでしょう。
Pocket Developer FAQ - Pocket Support

ちなみに、企業としてPocket APIを使ってみたい場合にはこちらの記事も参考になるかもです。
Pocketsに関するセキュリティレポート?的な情報がまとめられています。
Pocket Security Overview - Pocket Support

お次はPocket APIの中心となる下記の機能に手を出してみようかなと:

  • 保存されている記事の取得
  • 保存されている記事へアクション

それでは|дﾟ*)