Graph APIの和訳です。Facebook上のデータへのアクセスで最も良く使うGraph API全般についての解説が書かれています。まず「Open Graphに触れる 1：基本」で全体の流れを把握して読むことをオススメします。


以下、2012年4月30日 12:06更新分までの本文です。
Facebookの中核をなすのはソーシャルグラフで、人々や人々が周りの物事に対して持つコネクション（繋がり）を示します。このAPIは以下の３点を提供します
  • ソーシャルグラフへの、シンプルで一貫性のあるアクセス
  • 統一されたフォーマットのオブジェクト(人物、写真、イベント、ページ)
  • それらの間のconnection(交友関係、いいね！、写真のタグ付け)

ソーシャルグラフ上の全てのオブジェクトには固有IDが与えられていて、https://graph.facebook.com/IDにリクエストする事 でオブジェクトの持つ要素へアクセスできます。たとえば、Facebook Platformの公式ページのIDは19292868552なので、https://graph.facebook.com/19292868552へ リクエストすると以下のようにオブジェクトの要素にアクセスできます。

{
   "name": "Facebook Platform",
   "type": "page",
   "website": "http://developers.facebook.com",
   "username": "platform",
   "founded": "May 2007",
   "company_overview": "Facebook Platform enables anyone to build...",
   "mission": "To make the web more open and social.",
   "products": "Facebook Application Programming Interface (API)...",
   "fan_count": 449921,
   "id": 19292868552,
   "category": "Technology"
}
代替手段として、usernameが設定されている人やページに対してはusernameをidとしてアクセスできます。上記ページのusername は"platform"なので、https://graph.facebook.com/platformが期待通りの結果を返します。全てのレスポンス はJSONオブジェクトで返されます。
Facebook内の全オブジェクトは同じ形式でアクセスする事ができます。
  • ユーザ: https://graph.facebook.com/btaylor (Bret Taylor)
  • ページ: https://graph.facebook.com/cocacola (Coca-Cola page)
  • イベント: https://graph.facebook.com/251906384206 (Facebook Developer Garage Austin)
  • グループ: https://graph.facebook.com/195466193802264 (Facebook Developers group)
  • アプリケーション: https://graph.facebook.com/2439131959 (the Graffiti app)
  • ステータス メッセージ: https://graph.facebook.com/367501354973 (A status message from Bret)
  • 写真: https://graph.facebook.com/98423808305 (A photo from the Coca-Cola page)
  • 写真アルバム: https://graph.facebook.com/99394368305 (Coca-Cola's wall photos)
  • プロフィール画像: http://graph.facebook.com/go.hagiwara/ (your profile picture)
  • 動画: https://graph.facebook.com/614004947048 (A Facebook tech talk on Tornado)
  • ノート: https://graph.facebook.com/122788341354 (Note announcing Facebook for iPhone 3.0)
  • チェックイン: https://graph.facebook.com/414866888308 (Check-in at a pizzeria)
Facebookのソーシャルグラフ上にある全てのオブジェクトは、互いに"関連性"で繋がっています。Bret TaylorはCoca-Colaページのファンで、Bret TaylorとArjun Bankerは友達です。これらの関連性を、私たちのAPIではコネクション（connection）と呼びます。https://graph.facebook.com /ID/CONNECTION_TYPEというURL構成を使うことで、オブジェクト間のコネクションを確かめる事ができます。人物やページがサ ポートしているコネクションは以下の通りです。
  • 友達: https://graph.facebook.com/me/friends?access_token=...
  • ニュースフィード: https://graph.facebook.com/me/home?access_token=...
  • プロフィールフィード (Wall): https://graph.facebook.com/me/feed?access_token=...
  • Like: https://graph.facebook.com/me/likes?access_token=...
  • ビデオ: https://graph.facebook.com/me/movies?access_token=...
  • 音楽: https://graph.facebook.com/me/music?access_token=...
  • 本: https://graph.facebook.com/me/books?access_token=...
  • ノート: https://graph.facebook.com/me/notes?access_token=...
  • パーミッション: https://graph.facebook.com/me/permissions?access_token=...
  • 写真タグ: https://graph.facebook.com/me/photos?access_token=...
  • 写真アルバム: https://graph.facebook.com/me/albums?access_token=...
  • ビデオタグ: https://graph.facebook.com/me/videos?access_token=...
  • ビデオ投稿: https://graph.facebook.com/me/videos/uploaded?access_token=...
  • イベント: https://graph.facebook.com/me/events?access_token=...
  • グループ: https://graph.facebook.com/me/groups?access_token=...
  • チェックイン: https://graph.facebook.com/me/checkins?access_token=...
  • 位置情報付きのオブジェクト: https://graph.facebook.com/me/locations?access_token=...
それぞれ異なるタイプのオブジェクトは、異なるコネクションをサポートしています。たとえば、Facebook Developer Garage at SXSW（ID:#331218348435）に参加する人々のリストを、https://graph.facebook.com /331218348435/attending?access_token=....から得る事ができます。
それぞれのオブジェクトのタイプやサポートされるコネクションのタイプは、各オブジェクトのドキュメントで詳しく解説しています。

Authorization

Graph APIを使うと、オブジェクトについて公開されている情報へアクセスするのはとても簡単です。たとえば、https://graph.facebook.com/btaylor (Bret Taylor) へアクセスすると、Bretに関する全ての公開情報を得られます。ユーザのファーストネーム、ラストネーム、プロフィール画像などは公開されています。
ユー ザに関して上記以外の追加情報を得たい場合は、まずパーミッションを得る必要があります。高レベルになると、対象ユーザのアクセストークンを取得する必要もあります。ユーザのアクセストークンを取得したら、下記のようにGraph APIへのリクエストにアクセストークンを含める事によって、ユーザに代わって情報へアクセスできます。
https://graph.facebook.com/220439?access_token=...
たとえば、https://graph.facebook.com/btaylor?access_token=... (Bret Taylor)はBret Taylorに関する追加情報を返します。
Graph APIはOAuth2.0を認証に使います。Authenticationに目を通して、どのようにユーザにパーミッションを求め、アクセストークンを取得するのか理解してください。
特にパーミッションを指定せずにユーザのアクセストークンを得ると、そのユーザがFacebook内で全体公開している情報へアクセスできるようになります。ユーザに関する特定の情報（たとえば emailアドレスや職歴）が必要となる場合は、該当する項目を得るのに必要となる追加のパーミッションを取得する必要があります。それぞれのオブジェクトのドキュメントに、各プロパティやコネクションへアクセスするのに必要となるパーミッションの詳しい情報が書かれています。

Page Login

ページ管理者からmanage_pagesというパーミッションを得る事で、そのページの代理としてアクセスする事ができます。
ユー ザがアプリに対してmanage_pagesパーミッションを与えると、ユーザオブジェクトのaccountsコネクション（そのユーザが管理するページ一覧:https://graph.facebook.com/ID/accounts?access_token=....）からユーザが管理する全ページの一覧と、各ページのアクセストークンが得られます。詳しい方法についてはこちらをご覧ください。

App Login

ログイン中のユーザを必要としない管理系の問い合わせ（たとえば統計情報やテストユーザなど）をするには、アプリケーション用のアクセストークンを得る必要があります。アプリケーションのアクセストークンの取得方法についてはこちらをご覧下さい。

Reading

Graph APIを使うと、Facebookのソーシャルグラフが持つ各要素とコネクションを取得する事が可能になります。APIを使って特定のフィールド のみ取得したり、オブジェクトの写真を取得したり、オブジェクトのメタデータをを取得する事も可能ですし、何かしらの変更に対してリアルタイムに取得する 事も出来ます。

Selection

デフォルトでは、クエリを投たときにオブジェクトの要素が返されます。取得したいフィールドやコネクションを指定するには、fieldsパラメータを用います。例えば、https://graph.facebook.com /bgolub?fields=id,name,pictureというURLは、id/name/pictureの値しか返しません。
idsというパラメータを使うと、一回のクエリで複数のオブジェクトを扱う事もできます。例えば、https://graph.facebook.com?ids=arjun,vernalは、両方のプロフィール情報を一緒に返します。
ids パラメータはURLも指定できます。これは、任意のURLに対するIDを見つける時に便利です。例えば、 https://graph.facebook.com/?ids=http://www.imdb.com/title/tt0117500/のように 使います。
また、ログイン中のユーザを指すmeというIDも準備されています。https://graph.facebook.com/meは、ログインユーザのプロフィール情報を返します。
ユーザオブジェクトの/homeや/postsコネクションから投稿内容を取得する際には、with=locationを指定することで位置情報付きの投稿のみを取得できます。 https://graph.facebook.com/me/home?with=location&access_token=...

Pictures

オブジェクトのプロフィール画像を表示するには、オブジェクトのURLの末尾に/pictureというサフィックスを付けます。たとえば、以下のようにして自身のプロフィール画像を表示します。
<img src="https://graph.facebook.com/Oklahomer/picture"/>
ソーシャルグラフ上の全てのオブジェクトに対して同じURLパターンが有効です。
  • 人物: http://graph.facebook.com/go.hagiwara/picture
  • イベント: http://graph.facebook.com/331218348435/picture
  • グループ: http://graph.facebook.com/69048030774/picture
  • ページ: http://graph.facebook.com/DoloresPark/picture
  • アプリケーション: http://graph.facebook.com/2318966938/picture
  • 写真アルバム: http://graph.facebook.com/platform/picture
type を指定すると画像のサイズを指定できます。サポートしているtypeはsquare (50x50)、small (横50pixels、高さは可変)、large（横およそ200px、高さは可変）の３種類で、http://graph.facebook.com /go.hagiwara/picture?type=largeのように指定します。
セキュアコネクション越しに画像を取得したい場合は、return_ssl_resources=1を指定します。
https://graph.facebook.com/go.hagiwara/picture?return_ssl_resources=1

Paging

コネクションへアクセスする際、フィルタリングやページングするのに便利なパラメータがあります。下記の2つです。
  • limit, offset: https://graph.facebook.com/me/likes?limit=3
  • until, since (unixタイムスタンプもしくは、strtotime関数で扱える形式): https://graph.facebook.com/search?until=yesterday&q=orange

Dates

すべてのdateフィールドは、ISO-8601形式の文字列で返されます。オプションでdate_formatパラメータを渡してフォーマットを変更する事も可能です。そのときに指定できるフォーマットはphpのdate関数で扱える形式のみです。たとえば、 http://graph.facebook.com/platform/feed?date_format=UはPlatformページのフィードを返しますが、dateフィールドはunixタイムスタンプ形式になります。

Introspection

Graph APIはオブジェクトのメタ情報取得をサポートしていて、あらかじめオブジェクトのタイプが分からなくとも、そのオブジェクトが持つ全てのコネクションを知ることができます。この情報を得るには、metadata=1をオブジェクトのURLに足してください。返されるJSONオブジェ クトはmetadataプロパティを持っていて、そのオブジェクトが持っている全てのコネクションのリストが含まれています。たとえば、 Developer Garageイベントの持っている全コネクションを得るには、https://graph.facebook.com /331218348435?metadata=1にアクセスします。すると、以下のような結果が得られます。
{
   "name": "Facebook Developer Garage Austin - SXSW Edition",
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/331218348435/feed",
         "picture": "https://graph.facebook.com/331218348435/picture",
         "invited": "https://graph.facebook.com/331218348435/invited",
         "attending": "https://graph.facebook.com/331218348435/attending",
         "maybe": "https://graph.facebook.com/331218348435/maybe",
         "noreply": "https://graph.facebook.com/331218348435/noreply",
         "declined": "https://graph.facebook.com/331218348435/declined"
      }
   }
}
この機能は、ユーザが繋がりを持っている対象を見つける上で、便利で拡張性のある手段です。

Real-Time updates

Real-time updatesは、ユーザの更新情報をリアルタイムに取得することを可能にします。これを利用していると、いちいち Facebookサーバへ問い合わせずともデータを最新の状態に保てるため、アプリケーションの信頼性やユーザ体験の質を上げる事が出来ます。

Searching

https://graph.facebook.com/searchへアクセスすると、ソーシャルグラフ上で公開されている全てのオブジェクトを検索する事ができます。形式は以下の通りです。
https://graph.facebook.com/search?q=QUERY&type=OBJECT_TYPE
以下のオブジェクトタイプをサポートしています。
  • 公開された投稿: https://graph.facebook.com/search?q=watermelon&type=post
  • 人物: https://graph.facebook.com/search?q=mark&type=user
  • ページ: https://graph.facebook.com/search?q=platform&type=page
  • イベント: https://graph.facebook.com/search?q=conference&type=event
  • グループ: https://graph.facebook.com/search?q=programming&type=group
  • 場所: https://graph.facebook.com/search?q=coffee&type=place
    centerパラメータ（緯度経度）とdistanceパラメータを使って詳細に検索することも可能です。
    https://graph.facebook.com/search?q=coffee&place&center=37.76,-122.427&distance=1000
  • チェックイン: https://graph.facebook.com/search?type=checkin（このリクエストは、ユーザもしくはユーザの友だちが最後にチェックインした場所、または、ユーザもしくはユーザの友だちが最後にタグ付けされた場所を返します。今のところ、qパラメータはサポートしていません。）
  • 位置情報付きのオブジェクト: 以下の方法で、位置情報の紐づいたオブジェクトを検索することができます。返されるのは、ユーザもしくはユーザの友だちが投稿したオブジェクト、またはユーザもしくはユーザの友だちがタグ付けされたオブジェクトです。得るパーミッションによって動作の違いがありますので、FQLのlocation_postテーブルのドキュメントを参照してください。
    • 位置を基準にしてオブジェクトを検索するには、type=locationを指定してcenterパラメータとdistanceパラメータを渡します。https://graph.facebook.com/search?type=location&center=37.76,-122.427&distance=1000
    • 特定の場所に紐づくオブジェクトを検索するには、type=locationを指定してplaceパラメータを渡します。例えばFacebook HQであれば以下のようにします。
      https://graph.facebook.com/search?type=location&place=166793820034304
先述したときと同様、fieldsパラメータを指定することで、返されるフィールドを限定することもできます。例えば、イベントの名前だけを取得するには以下のようにします。
・https://graph.facebook.com/search?fields=name&q=conference&type=event
イベントのidやstart_timeなどのフィールドは常に返されます。
homeコネクションにqパラメータを追加する事でユーザのNews Feedを検索する事も可能ですが、ユーザの友達に限定されます。
・https://graph.facebook.com/me/home?q=facebook

注意：/me/homeで返される情報は古いニュースフィードの内容で、これは既知の問題です。ただし、近いうちに対応する計画はありません。

一般公開された投稿やユーザのニュースフィード上の投稿を検索する場合、since, until, limitパラメータを使用してページングできます。sinceとuntilは両方ともUNIXタイムスタンプが指定できます。過去の投稿へとページングする場合、limitとuntilを指定すべきで、untilには直近のリクエストで返されたオブジェクト配列の最後の一個のcreated_timeフィールド値を指定します。逆の場合はsinceには直近のリクエストで返されたオブジェクト配列の最初の一個のcreated_timeフィールド値を指定します。ニュースフィードの直近1~2週間分の情報しか検索できないことに気をつけてください。

Publishing

アクセストークンを使いつつ適切なコネクションURLに対してHTTP POSTリクエストを送る事で、Facebook graphに投稿する事が可能です。たとえば、https://graph.facebook.com/arjun/feedへPOSTリクエスト を送ると、Arjunのwallに投稿できます。
curl -F 'access_token=...' \
     -F 'message=Hello, Arjun. I like this new API.' \
     https://graph.facebook.com/arjun/feed
各オブジェクトのドキュメントには、より詳細な引数と値についての情報が書かれています。
/comments や/likees connectionを持つオブジェクトに対しては、https://graph.facebook.com/OBJECT_ID/commentsと https://graph.facebook.com/OBJECT_ID/likesをそれぞれ使う事で、コメントしたりいいね！したりできます。
curl -F 'access_token=...' \
     https://graph.facebook.com/313449204401/likes
大部分の投稿はユーザのパーミッションが必要となります。認証ステップでユーザに追加のパーミッションを求める方法については、Authenticationをご覧下さい。
下記のオブジェクトタイプが投稿をサポートしています。
MethodDescriptionArguments
/PROFILE_ID/feed指定したプロフィールのfeed/wallに対して投稿します。message, picture, link, name, capt ion, description, source
/OBJECT_ID/commentsオブジェクトに対してコメントします（/commentsコネクションがある場合のみ）message
/OBJECT_ID/likesオブジェクトをいいね！します。（/likesコネクションがある場合のみ）none
/PROFILE_ID/notes指定したプロフィールにノートを投稿しますmessage, subject
/PROFILE_ID/links指定したプロフィールにlinkを投稿します。link, message, picture, name, caption, description
/PROFILE_ID/eventsイベントを作成しますname, start_time, end_time
/EVENT_ID/attendingイベントへの参加表明をしますなし
/EVENT_ID/maybeイベントへの"もしかしたら参加"を表明しますなし
/EVENT_ID/declinedイベントへの不参加表明をしますなし
/PROFILE_ID/albumsアルバムを作成しますname, message
/ALBUM_ID/photosアルバムに写真を投稿します。message, source (multi part/form-data)
/PROFILE_ID/checkinsページの示す場所に対してチェックインします coordinates, place, message, tags

Deleting

オブジェクトのURLに対してHTTP DELETEリクエストを送信すると、グラフ上のオブジェクトを削除できます。
DELETE https://graph.facebook.com/ID?access_token=... HTTP/1.1
全HTTPメソッドをサポートしていないクライアント（JavaScriptクライアントなど）をサポートするには、代わりに、オブジェクトのURLに対し てmethod=deleteというパラメータを追加してPOSTリクエストを送ります。たとえば、コメントを削除するには https://graph.facebook.com/COMMENT_ID?method=deleteへPOSTリクエストを送信します。(いいね！自体にはIDが無いので)/OBJECT_ID/likesへDELETEリクエストを送ることで、いいね！を削除することが可能です。

Analytics

アプリケーションを登録すると、ユーザ層や、ユーザがどうshareしているかなどの詳細な統計情報をInsightsで得られます。Graph APIは、ここの全データに対してプログラマティックにアクセスできますので、Platformのデータを自前の統計システムに組み込むことも可能です。Insightsのデータをダウンロードするには、まずアプリケーションのアクセストークンを取得します。アクセストークンを取得したら、以下のURLへアクセスしてアプリケーションの統計データをダウンロードできます。
https://graph.facebook.com/app_id/insights?access_token=...
上記URLは、APIを通じて得られる全統計データ（ユーザ数、アクティブユーザ数、その他詳細な情報）を返します。たとえば、アプリケーションのキャンバスページのインプレッション数を得るには、下記へアクセスします。
https://graph.facebook.com/app_id/insights/application_canvas_views/day?access_token=...
sinceとuntilパラメータを使って取得するデータの期間を指定することもできます。どちらのパラメータも、有効なdateフォーマットならほとんどの形式をサポートしています。
https://graph.facebook.com/app_id/insights?access_token=...&since=yesterday
より詳細な情報は、Insightsプロダクト、/insights URL、Insightsのドキュメントをご覧ください。

Concepts

Batch Requests
一度に多くのデータにアクセスしたい場合、もしくは一度に多くのオブジェクトを更新したい場合、都度HTTPリクエストを送信するよりもBatch Requestを使って一度にまとめるのが効率的です。

permissions
Graph APIの各フィールドやコネクションへアクセスするのに必要なパーミッションです。

Real-time Updates
Graph APIは、Facebook上でのオブジェクトの変化をリアルタイムに購読する機能を提供しています。これにより、ポーリングすること無しに更新を知ることができます。データのキャッシュとReal-time Updates APIを併用することで、アプリの信頼性とロード時間向上が期待できます。
（訳注：このドキュメントは和訳していませんが、Facebook Night vol.7 発表内容まとめ 3：Batch RequestとReal-time Update APIで実装方法を紹介しています。）

Objects

  • Achievement(インスタンス)：ゲームアプリ利用ユーザのAchievementインスタンス
  • Album：写真アルバム
  • Application：Facebook Platformに登録されているアプリケーション
  • Checkin：Facebook PlacesかGraph APIを通じて作成されたcheckin
  • Comment：Graph APIのオブジェクトに着いたコメント
  • Domain：Graph API上のウェブサイトドメイン
  • Event：Facebookイベント
  • FriendList：Facebook友達リスト
  • Group：Facebookグループ
  • Insights：アプリケーション、ページ、ドメインの統計情報
  • Link：shareされたリンク
  • Message：Facebook統合メッセージシステムのメッセージ
  • Note：Facebookノート
  • Offer：ページによるオファー
  • Order：Facebookクレジットに紐づくオーダー
  • Page：Facebookページ
  • Photo：アルバム中の個々の写真
  • Post：ユーザやFacebookページのフィード上の個々のエントリー
  • Question：ユーザによるクエスチョン
  • QuestionOption：クエスチョンに対する回答の選択肢
  • Review：アプリケーションのレビュー
  • Status message：ユーザのwall上のステータスメッセージ
  • Thread：メッセージのスレッド
  • User：ユーザのプロフィール
  • Video：個々のビデオ