GraphAPIを調べる時のFacebook公式ドキュメントの歩き方
これさえ覚えればFacebookのGraphAPIも怖くない、ということでFacebookの公式ドキュメントの歩き方をまとめます。(2013/12/04 現在)
公式ドキュメント
GraphAPIの公式ドキュメントは下記のURLです。
https://developers.facebook.com/docs/graph-api/reference/
とにもかくにもアクセスしましょう。
GraphAPIの設計方針
GraphAPIの設計方針はとてもシンプルです。
公式ドキュメントの一番最初に書いてある様に、Facebookではデータを全てObjectと捉えています。
そのObjectには一つ一つ固有のIDがあります。
AlbumというObjectにはalbum-idが。
EventというObjectにはevent-idという感じです。
なので、データのアクセスの仕方もとてもシンプルです。
このobject-idにアクセスするだけです。
/{object-id}
facebookは、リクエストに含まれるobject-idがどのobjectなのかを自動で判別してレスポンスを返してくれるため、送る側は、どのobjectなのかという点を気にする必要はありません。
対象をはっきりさせる
GraphAPIを調べるとき、自分がどのObjectに対して操作をしたいのか、ということをはっきりさせることが大事です。
Userに対して何かをしたいのか。それともAlbumに対して何かをしたいのか。
今、自分がしたいことの対象は何かを見極めてください。
例えば...
UserがAlbumを作成する
これは、あくまでもUserの処理なので、対象はUserになります。
UserがAlbumに写真をアップロードする
こちらの場合は先ほどと似ていますが、実際に操作をしたいのはAlbumであり、Userではありません。
なので、対象はAlbumになります。
各Objectのドキュメントを見てみる
というわけで、わかりやすいAlbumのドキュメントを見てみます。
https://developers.facebook.com/docs/reference/api/album/
各Objectのドキュメントは大きく分けると3つの構成で書かれています。
- Fields
- Connections
- POSTなどのAPI
Fields
FieldsはそのObjectのプロパティを表しています。
例えば、AlbumのFieldsを見てみると、idの他にnameやdescriptionなどが書いてあります。
これが、AlbumというObjectから取得できるデータです。
Albumのnameプロパティはもちろんアルバム名です。
Connections
ConnectionsはそのObjectから、さらに別のObjectを辿るURLを表しています。
Albumからは、photosやcommentsなどが辿れます。
これはつまり、下記の様なURLでデータを辿ることができるということです。
/{album-id}/photos
Albumのphotosを要求しているので、もちろんアルバム内の画像を取得できます。
Albumのcommentsを要求すると、そのアルバムに投稿されたコメントが取得できます。
connectionsはこの様に、Objectから辿れることができるデータを表します。
POSTなどのAPI
それ以降に書かれている内容は、基本的にGET以外のAPIになります。
下記はAlbumに写真を投稿するときのリファレンスです。
You can add photos to an album by issuing an HTTP POST request to ALBUM_ID/photos with the publish_stream permissions and the following parameters.
ALBUM_ID/photosにPOSTでアクセスしろと書いてあります。
sourceやmessageの部分は、リクエストに必要なパラメータ。
一番下のidの部分は、レスポンスで返ってくる値です。
ちなみに...
写真を投稿して返ってくるIDというのは、もちろん写真のobject-id(photo-id)です。
まとめ
基本的にはこれだけです。
GraphAPIはとてもよくできているので、そこまでややこしいことはありません。
いくつかのポイントさえ覚えてしまえば、ドキュメントを調べるのも簡単にできますよ!