読者です 読者をやめる 読者になる 読者になる

GraphAPIを調べる時のFacebook公式ドキュメントの歩き方

これさえ覚えればFacebookのGraphAPIも怖くない、ということでFacebookの公式ドキュメントの歩き方をまとめます。(2013/12/04 現在)

公式ドキュメント

GraphAPIの公式ドキュメントは下記のURLです。

https://developers.facebook.com/docs/graph-api/reference/

とにもかくにもアクセスしましょう。

GraphAPIの設計方針

GraphAPIの設計方針はとてもシンプルです。

f:id:w6500:20131204191407p:plain

公式ドキュメントの一番最初に書いてある様に、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つの構成で書かれています。

  1. Fields
  2. Connections
  3. POSTなどのAPI

Fields

FieldsはそのObjectのプロパティを表しています。
例えば、AlbumのFieldsを見てみると、idの他にnameやdescriptionなどが書いてあります。
これが、AlbumというObjectから取得できるデータです。
Albumのnameプロパティはもちろんアルバム名です。

f:id:w6500:20131204194141p:plain

Connections

ConnectionsはそのObjectから、さらに別のObjectを辿るURLを表しています。
Albumからは、photosやcommentsなどが辿れます。
これはつまり、下記の様なURLでデータを辿ることができるということです。

/{album-id}/photos

Albumのphotosを要求しているので、もちろんアルバム内の画像を取得できます。
Albumのcommentsを要求すると、そのアルバムに投稿されたコメントが取得できます。

connectionsはこの様に、Objectから辿れることができるデータを表します。

f:id:w6500:20131204194535p:plain

POSTなどのAPI

それ以降に書かれている内容は、基本的にGET以外のAPIになります。
下記はAlbumに写真を投稿するときのリファレンスです。

f:id:w6500:20131204194955p:plain

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はとてもよくできているので、そこまでややこしいことはありません。
いくつかのポイントさえ覚えてしまえば、ドキュメントを調べるのも簡単にできますよ!