instagram APIを読む Real time Photo Updates編

Instagram Real-Time Photo Updates

リアルタイムの通知を受け取れるinstagram APIの内容まとめ。

OVERVIEW

• instagramに投稿された新しい写真の即時通知
• シンプルなweb hooksの使用

SUBSCRIPTIONS

• 4種類のobject type
  • Users
    • ユーザが新しい写真を投稿した時に通知を受信
  • Tags
    • 新しい写真に、選択したタグが付けられた時に通知を受信
  • Locations
    • 新しい写真が投稿されて、特定の場所のタグが付けられた時に通知を受信
  • Geographies
    • 任意の場所で新しい写真が投稿された時に通知を受信

PROCESS

REGISTER A CLIENT

• client_idとclient_secretを取得するために登録が必要

CREATE A CALLBACK URL

• callback URLはGETとPOSTをサポートしていなければならない
• subscriptionを追加すると、URLの存在を検証するためにGETリクエストが送られる
• 新しいデータがあると、callback URLにPOSTでデータを送信

CREATE A SUBSCRIPTION

• subscriptionのエンドポイントにPOSTを送信

curl -F 'client_id=CLIENT-ID' \
     -F 'client_secret=CLIENT-SECRET' \
     -F 'object=user' \
     -F 'aspect=media' \
     -F 'verify_token=myVerifyToken' \
     -F 'callback_url=http://YOUR-CALLBACK/URL' \
     https://api.instagram.com/v1/subscriptions/

• callback_urlと取得したclient_idとclient_secretを置き換えてこのコマンドを発行してもエラーになる. "Challenge Verification Failed"
  • PubSubHububのchallenge flowにより新しい登録を検証
• 新しい登録をするため上記の情報をPOSTすると、下記のパラメータがGETリクエストで送信される
  • hub.mode
    • "subscription"が設定される
  • hub.challenge
    • ランダムな文字列が設定される
    • 登録を検証するためにエコーバックする
  • hub.verify_token
    • 登録のリクエストで渡されたverify_tokenが設定される
    • 複数の登録リクエストを区別するのに使用

http://your-callback.com/url/?hub.mode=subscribe&hub.challenge=15f7d1a91c1f40f8a748fd134752feb3&hub.verify_token=myVerifyToken

• hub.challengeパラメータだけをGETで返送

15f7d1a91c1f40f8a748fd134752feb3

• このリクエストと登録が成功すると、JSONレスポンスが返ってくる

{
    "meta": {
        "code": 200
    }, 
    "data": {
        "object": "user", 
        "type": "subscription", 
        "id": "1", 
        "aspect": "media", 
        "callback_url": "http://your-callback.com/url/"
    }
}

USER SUBSCRIPTIONS

• client_idとclient_secretの他に2つのパラメータが登録に必要
  • object
    • この場合は"user"
  • aspect
    • この場合は"media"
    • 現在は"media"のみサポート
• アプリケーションに登録したすべてのユーザに対する登録で、特定のユーザの登録ではない

TAG SUBSCRIPTIONS

curl -F 'client_id=CLIENT-ID' \
     -F 'client_secret=CLIENT-SECRET' \
     -F 'object=tag' \
     -F 'aspect=media' \
     -F 'object_id=nofilter' \
     -F 'callback_url=http://YOUR-CALLBACK/URL' \
     https://api.instagram.com/v1/subscriptions/

• object_idに登録したいtagを指定（この場合はnofilter）
• user subscriptionsと異なり一つだけ指定

LOCATION SUBSCRIPTIONS

• objectには"location"、object_idには登録したい場所のID
  • この例の場所は東京の渋谷

curl -F 'client_id=CLIENT-ID' \
     -F 'client_secret=CLIENT-SECRET' \
     -F 'object=location' \
     -F 'aspect=media' \
     -F 'object_id=1257285' \
     -F 'callback_url=http://YOUR-CALLBACK/URL' \
     https://api.instagram.com/v1/subscriptions/

GEOGRAPHY SUBSCRIPTIONS

• location subscriptionsよりも広い範囲（街や大きな公園のような）の登録
• 中心の緯度経度と半径を指定（最大半径は5000m）

curl -F 'client_id=CLIENT-ID' \
     -F 'client_secret=CLIENT-SECRET' \
     -F 'object=geography' \
     -F 'aspect=media' \
     -F 'lat=35.657872' \
     -F 'lng=139.70232' \
     -F 'radius=1000' \
     -F 'callback_url=http://YOUR-CALLBACK/URL' \
     https://api.instagram.com/v1/subscriptions/

• 次のようにアクセス出来る
  • このアクセスはreal timeアクセスをする時に使われることを想定しているので最近のものだけ

https://api.instagram.com/v1/geographies/{geography id}/media/recent?client_id=CLIENT-ID

RECEIVING UPDATES

• 更新があったら登録されたURLにPOSTが送信される

[
    {
        "subscription_id": "1",
        "object": "user",
        "object_id": "1234",
        "changed_aspect": "media",
        "time": 1297286541
    },
    {
        "subscription_id": "2",
        "object": "tag",
        "object_id": "nofilter",
        "changed_aspect": "media",
        "time": 1297286541
    },
    ...
]

• ペイロードに含まれる複数の更新内容を適切に処理できる必要がある
  • 多くは1つだけ含まれるが
• 更新データはペイロードには含まれない
  • 処理方法はアプリケーション次第
• ペイロードの検証に"X-Hub-Signature"ヘッダを使うことが出来る
  • SHA-1ダイジェスト

LIST YOUR SUBSCRIPTIONS

• 現在の登録内容を見る方法
  • /subscriptions エンドポイントにGETリクエスト

https://api.instagram.com/v1/subscriptions?client_secret=CLIENT-SECRET&client_id=CLIENT-ID

{
    "meta": {
        "code": 200
    }, 
    "data": [
        {
            "id": "1", 
            "type": "subscription", 
            "object": "user", 
            "aspect": "media", 
            "callback_url": "http://your-callback.com/url/"
        },
        {
            "id": "2", 
            "type": "subscription", 
            "object": "location", 
            "object_id": "2345",
            "aspect": "media", 
            "callback_url": "http://your-callback.com/url/"
        }
    ]
}

DELETE SUBSCRIPTIONS

• DELETEリクエストをエンドポイントに送信する
  • object typeかsubscription IDをパラメータとして付加
    • "object"か"id"をそれぞれ指定
• すべて削除するときは"object=all"

curl -X DELETE https://api.instagram.com/v1/subscriptions?client_secret=CLIENT-SECRET&object=all&client_id=CLIENT-ID

• 特定の登録を削除

curl -X DELETE https://api.instagram.com/v1/subscriptions?client_secret=CLIENT-SECRET&id=1&client_id=CLIENT-ID

• 特定のobject typeをすべて削除

curl -X DELETE https://api.instagram.com/v1/subscriptions?client_secret=CLIENT-SECRET&object=tag&client_id=CLIENT-ID