去年12月以来、FQLのドキュメントはFacebook Platformのソースコードから生成されるようになりました。これにより、従来よりも正確でなおかつ最新の状態が保たれると発表されていますが、それでもドキュメントだけを頼りに開発を進めるのは辛いものです。

ここでは、私がFQLを扱う際の手順と注意している点について、ドキュメントを確かめるところからバグ報告を行うところまで紹介します。

  1. 本家ドキュメントを見る
    • 2種類のID
      • Open Graph上のユニークID
      • テーブル内でのユニークID
    • プロフィール
      • プロフィールID
  2. Graph API Explorerを使う
    • アクセストークン
    • 期待する結果が得られないとき
  3. バグ報告する
    • 報告する
      • APIの不具合を報告する
      • ドキュメントの誤りを報告する
  4. まとめ

1.本家ドキュメントを見る

fql

私自身もFQLドキュメントの和訳を公開していますが、常に更新され続ける情報には追いついていません。和訳を書いたころは、本家ドキュメント自体が古い仕様に基づいていたりもしました。今では本家ドキュメントが最新の状態に保たれているのですから、あくまで和訳はキッカケ程度にして、詳細については本家を参照するのが一番です。本人が言うんですから間違いありません。
ドキュメントを読む際には、いくつか気をつけている点があります。

2種類のID

Open Graph上のユニークID
2e4b0f4ab7a2d9c9ba0ae204e356f146

そもそもOpen Graphが何かというと、Facebookが持つソーシャルグラフをサードパーティの開発者向けに拡張したものです。そこでは、人間、画像、動画、ページ、アルバムなど、ソーシャルグラフを構成する全てのオブジェクトに固有のIDが割り振られています。ここでは他方との区別の為、Open Graph IDと呼ぶことにします。このIDはOpen Graph上で固有なため、 https://graph.facebook.com/ID へアクセスすることで、そのオブジェクトに関する情報を取得することができます。
テーブル内でのユニークID
c64ec031248e7aa081e9312532d846a9

userテーブルにはuid(user id)というカラムが存在します。これはOpen Graph IDなので、先述の通りOpen Graph上で固有のものです。https://graph.facebook.com/UID でユーザ情報を得ることができます。また、albumやphotoテーブルには、aid(album id)やpid(photo id)といったカラムが存在します。user.uidの流れで、これらもOpen Graph IDであるように見えます。事実、user.uidの説明は"The user ID"、album.aidの説明は"The album ID"と書かれているだけなので、扱いが違うようには見えません。
ところが実際には、album.aidやphoto.pidはテーブル内で固有なだけで、Open Graph上で割り振られたユニークIDではありません。そのため、ここで得られたaidを基に https://graph.facebook.com/AID にアクセスしても望む結果は得られません。こういったテーブルには大体、object_idといったカラムが存在し、それらがOpen Graph IDとなっています。
たとえばphotoテーブルの場合、aid, album_object_id, pid, object_idといったカラムが存在します。aidはalbumテーブルのUNIQUE KEYで、albumテーブルに対するクエリ実行で用いることができます。album_object_idは画像が属するアルバムオブジェクトのOpen Graph IDなので、https://graph.facebook.com/ALBUM_OBJECT_IDでアルバムにアクセスできます。同様に、pidはphotoテーブル中のUNIQUE KEYで、object_idはOpen Graph IDです。

プロフィール

プロフィールアイコンやプロフィールページと言われれば、普通はユーザに関係するものを想像すると思いますが、Facebook上では、Facebookページ、イベント、グループ、アプリにも個別のページが与えられます。それらのページではプロフィール画像を設定することもできますし、ウォール投稿したり画像や動画を投稿することもできます。そのため、それらもまとめてprofile(プロフィール)と呼ばれています。ドキュメント中でprofileという語が出てきた場合には、ユーザオブジェクトだけでなく、これらのOpen Graphオブジェクトも対象となることに気をつけてください。
プロフィールID
画像、動画、アルバムなどは何かしらのプロフィールに属します。ユーザが投稿した画像であればユーザプロフィールに属しますし、Facebookページが投稿した画像であればFacebookページプロフィールに属します。属するプロフィールのIDを返すカラムの名前が、テーブルによって違いがあるので注意してください。album.owner, comment.fromid, event.creator, event_member.uid, group.creator, status.uid, stream.source_id, stream_tag.actor_id, page_milestone.owner_idなどです。いずれも該当オブジェクトが紐づくプロフィールIDを返すカラムですが、ownerやuidなど呼び名が統一されていません。
ポイントとしては、uid(user id)というカラム名の場合はユーザのOpen Graph IDを指しているので、ユーザ以外のプロフィール(イベントやグループ)に属することはありません。逆に、ownerやowner_idという名称の場合は、ユーザ以外のプロフィールにも属しうるといえます。また、group.creatorやevent.creatorの場合は、あくまで作成したプロフィールのIDであって、管理者とは限らないことが分かります。(owner,uid,creatorを使い分けるのは分かりますが、ownerとowner_idはどちらかに統一して欲しい。。。)

2.Graph API Explorerを使う

explorer2
ドキュメントを読んで仕様を理解したら、まずはGraph API Explorerで試してみるのが一番です。この開発ツールでは、実際にAPIを利用して返される値を確かめることができます。

アクセストークン

graph_api_explorer
キャプチャ右上の赤枠部分のセレクトボックスでは、Graph API Explorerというアプリと、自分が開発者として関わっているアプリを選択することができます。ここでアプリを選択し、「Get Access Token」をクリックしてアクセストークンを生成し、そのアクセストークンを用いてFQLクエリを発行することになります。
このとき、いきなり自分のアプリを選択することはせず、まずはGraph API Explorerを選択してアクセストークンを生成するようにしています。APIの仕様は常に変更の対象で、変更の際には告知から90日間の移行期間が設けられています。この移行期間中は、アプリの設定画面で移行設定を行うことが可能です。そのため、同じクエリを発行していても、アプリごとの設定によって返る値が変わり得ます。こうなってくるとややこしいので、まずはGraph API Explorerのアクセストークンで最新の仕様に従ってクエリを実行し、そのあとに自分のアプリを選択し、そのアクセストークンを生成するようにしています。ステップが増えて面倒な気もしますが、期待通りの結果が得られない場合に、アプリの問題なのかFacebook側の問題なのかを切り分けるのが楽になります。

期待する結果が得られないとき


f1cd81cbe5c99cc28944abc5e757d2a4

このキャプチャは4/9に遭遇した不具合で、content_ageを含むクエリでエラーが返されるというものです。ドキュメントに従っているものの、どうしてもエラーが返されてしまいます。content_ageを除いて実行すると仕様に従った値が返されました。こうした場合にはバグ報告します。

3.バグ報告する

FQLのドキュメントを見つついろいろなクエリを試していると、ちょこちょこ不具合を見つけることがあります。直近1ヶ月の間に見つけて報告したFQL関連のものは以下の6件です。
  1. FQL place.search_type returns empty string
  2. FQL place.content_age column returns error
  3. FQL page table's budget_recs is returning error
  4. description for content and content_html column is different from its implementation and is misleading
  5. Sample query uses a column that does not exist
  6. FQL link table's comment_info.comment_order is unclear
1~3と5はFQLの不具合で、これらはアサインされ、ものによっては既にFIXEDになっています。
4,6はドキュメントの不備を報告したものです。完全に不具合という場合でないと修正対象とならないらしく、「型がENUMとなっているけど、どういう値が返りうるのか明記されてないよ(他のドキュメントページでは通常、明記されています)」とか「contentとcontent_htmlのカラムの説明が間違ってて誤解を招くよ」という報告をした結果、「Thank you」というコメントでCloseされています。
いきなりバグ報告だと敷居が高い、不具合なのか自信が無いという場合には、まずFacebook API Developers JAPANというグループに投稿してみるのが良いかもしれません。

報告する

APIの不具合を報告する
まずBugsに行きます。ここには開発者から報告されたバグが一覧で表示されていて、タグや検索によって絞り込むことができます。ここにはバグ報告フォームへのリンクがありません。検索バーに適当な文字列を入れて、出てくる候補の一番下にあるCreate a new bug reportをクリックすれば遷移します。
もしくは直接File a Bug Reportへ行って登録できます。
989bd7cc22bc140f0fa3ea566d273de9
概要
まずは、タイトル、概要、どの分野の不具合かを示すタグ、非公開(confidential)にするかを入力します。
アプリ情報
どのアプリでそれを再現しうるのかAppsに入力します。自分の関係しているアプリ名を入れると補完されますが、Graph API Explorer上で試していて、なおかつGraph API Explorerのアクセストークンを使って再現していた場合、何を入れるか迷ってしまいます。そんなときは、とりあえず何かしら自分のアプリを入れておくという方法もあります。
Related IDsには、関連するOpen GraphオブジェクトのIDを入力します。クエリ中で特定のオブジェクトを指定して再現するのであれば、それを入れます。
Access Tokensには、不具合を再現できるアクセストークンを入れます。Graph API Explorerで試していたなら、Explorerページ上に表示されているものを入れれば大丈夫でしょう。
再現方法
Steps to Reproduceには再現方法を登録します。以下のように書いておけば伝わります。
1. Visit Graph API Explorer.
2. Type in a query like "SELECT ......"
3. Submit
Expected Behaviorには期待する結果、Actual Behaviorには実際の結果を入力します。Actual Behaviorは返されたエラーを貼付けておけば大丈夫でしょう。見られたくない情報まで含まないように気をつけてください。
必要であれば、Attachmentsでキャプチャを添付します。
以上のステップが終わったらCreateで登録します。これで自分が登録したバグ一覧に表示され、ステータスの変化が分かるようになります。
ドキュメントの誤りを報告する
0cb8ddb7d041d7420e3802fe11cc128e

ドキュメントページ右下の「Report Documentation Bug」をクリックします。すると該当するドキュメントページのパスが補完された状態で、報告用フォームが開きます。ここに要約と詳しい説明を書いて登録します。ファイルを追加することもできますので、不備がある部分のキャプチャを撮っておいてアップロードすると説明が楽かもしれません。登録するとBugs自分が登録したバグ一覧でステータスが分かるようになります。
以前は「Report Documentation Bug」をクリックするとフォームがポップアップで開くというもので、登録後のステータス変化について何のフィードバックも無かったのですが、今ではAPIの不具合と同様にBugsに登録されます。他のユーザにも見えますし、ステータスの変化も分かるので、とても便利になりました。

4.まとめ

以上が、私がFQLを扱う上で気をつけている点です。仕様変更が多かったり不具合がちょこちょこあるということがよく言われますが、ドキュメントを確かめつつ試し、不具合があれば報告まで行うことが、イライラを減らし、他の開発者の助けにもなると思います。文句を言う前にバグ報告までしっかり行いましょう。