記載されているdocumentationの和訳と、調べていて分かったノウハウを紹介します。we.ドキュメント全体の目次はこちらFacebook関連情報はFacebookページで共有しています。Platformのソースコードから生成されるようになりました。これにより、従来よりも正確でなおかつ最新の状態が保たれると発表されていますが、それでもドキュメントだけを頼りに開発を進めるのは辛いものです。ここでは、私がFQLを扱う際の手順と注意している点について、ドキュメントを確かめるところからバグ報告を行うところまで紹介します。Explorerを使うアクセストークン期待する結果が得られないときバグ報告する報告するAPIの不具合を報告するドキュメントの誤りを報告するまとめ1.本家ドキュメントを見る私自身もFQLドキュメントの和訳を公開していますが、常に更新され続ける情報には追いついていません。和訳を書いたころは、本家ドキュメント自体が古い仕様に基づいていたりもしました。今では本家ドキュメントが最新の状態に保たれているのですから、あくまで和訳はキッカケ程度にして、詳細については本家を参照するのが一番です。本人が言うんですから間違いありません。ドキュメントを読む際には、いくつか気をつけている点があります。Graphが何かというと、Facebookが持つソーシャルグラフをサードパーティの開発者向けに拡張したものです。ページ、アルバムなど、ソーシャルグラフを構成する全てのオブジェクトに固有のIDが割り振られています。IDと呼ぶことにします。アクセスすることで、そのオブジェクトに関する情報を取得することができます。id)というカラムが存在します。Graph上で固有のものです。ユーザ情報を得ることができます。id)といったカラムが存在します。IDであるように見えます。ID"と書かれているだけなので、扱いが違うようには見えません。Graph上で割り振られたユニークIDではありません。アクセスしても望む結果は得られません。object_idといったカラムが存在します。KEYで、albumテーブルに対するクエリ実行で用いることができます。IDなので、https://graph.facebook.com/ALBUM_OBJECT_IDでアルバムにアクセスできます。プロフィールプロフィールアイコンやプロフィールページと言われれば、普通はユーザに関係するものを想像すると思いますが、Facebook上では、Facebookページ、イベント、グループ、アプリにも個別のページが与えられます。それらのページではプロフィール画像を設定することもできますし、ウォール投稿したり画像や動画を投稿することもできます。そのため、それらもまとめてprofile(プロフィール)と呼ばれています。Graphオブジェクトも対象となることに気をつけてください。プロフィールID画像、動画、アルバムなどは何かしらのプロフィールに属します。ユーザが投稿した画像であればユーザプロフィールに属しますし、Facebookページが投稿した画像であればFacebookページプロフィールに属します。属するプロフィールのIDを返すカラムの名前が、テーブルによって違いがあるので注意してください。page_milestone.owner_idなどです。いずれも該当オブジェクトが紐づくプロフィールIDを返すカラムですが、ownerやuidなど呼び名が統一されていません。IDを指しているので、ユーザ以外のプロフィール(イベントやグループ)に属することはありません。逆に、ownerやowner_idという名称の場合は、ユーザ以外のプロフィールにも属しうるといえます。group.creatorやevent.creatorの場合は、あくまで作成したプロフィールのIDであって、管理者とは限らないことが分かります。(owner,uid,creatorを使い分けるのは分かりますが、ownerとowner_idはどちらかに統一して欲しい。Explorerで試してみるのが一番です。この開発ツールでは、実際にAPIを利用して返される値を確かめることができます。Explorerというアプリと、自分が開発者として関わっているアプリを選択することができます。Token」をクリックしてアクセストークンを生成し、そのアクセストークンを用いてFQLクエリを発行することになります。Explorerを選択してアクセストークンを生成するようにしています。APIの仕様は常に変更の対象で、変更の際には告知から90日間の移行期間が設けられています。この移行期間中は、アプリの設定画面で移行設定を行うことが可能です。そのため、同じクエリを発行していても、アプリごとの設定によって返る値が変わり得ます。Explorerのアクセストークンで最新の仕様に従ってクエリを実行し、そのあとに自分のアプリを選択し、そのアクセストークンを生成するようにしています。ステップが増えて面倒な気もしますが、期待通りの結果が得られない場合に、アプリの問題なのかFacebook側の問題なのかを切り分けるのが楽になります。期待する結果が得られないときこのキャプチャは4/9に遭遇した不具合で、content_ageを含むクエリでエラーが返されるというものです。ドキュメントに従っているものの、どうしてもエラーが返されてしまいます。content_ageを除いて実行すると仕様に従った値が返されました。した場合にはバグ報告します。3.バグ報告するFQLのドキュメントを見つついろいろなクエリを試していると、ちょこちょこ不具合を見つけることがあります。直近1ヶ月の間に見つけて報告したFQL関連のものは以下の6件です。unclear1~3と5はFQLの不具合で、これらはアサインされ、ものによっては既にFIXEDになっています。4,6はドキュメントの不備を報告したものです。you」というコメントでCloseされています。JAPANというグループに投稿してみるのが良いかもしれません。報告するAPIの不具合を報告するまずBugsに行きます。ここには開発者から報告されたバグが一覧で表示されていて、タグや検索によって絞り込むことができます。ここにはバグ報告フォームへのリンクがありません。reportをクリックすれば遷移します。Reportへ行って登録できます。概要まずは、タイトル、概要、どの分野の不具合かを示すタグ、非公開(confidential)にするかを入力します。アプリ情報どのアプリでそれを再現しうるのかAppsに入力します。Explorerのアクセストークンを使って再現していた場合、何を入れるか迷ってしまいます。そんなときは、とりあえず何かしら自分のアプリを入れておくという方法もあります。GraphオブジェクトのIDを入力します。クエリ中で特定のオブジェクトを指定して再現するのであれば、それを入れます。Tokensには、不具合を再現できるアクセストークンを入れます。Explorerで試していたなら、Explorerページ上に表示されているものを入れれば大丈夫でしょう。Reproduceには再現方法を登録します。以下のように書いておけば伝わります。Behaviorには実際の結果を入力します。Behaviorは返されたエラーを貼付けておけば大丈夫でしょう。見られたくない情報まで含まないように気をつけてください。必要であれば、Attachmentsでキャプチャを添付します。以上のステップが終わったらCreateで登録します。これで自分が登録したバグ一覧に表示され、ステータスの変化が分かるようになります。Bug」をクリックします。すると該当するドキュメントページのパスが補完された状態で、報告用フォームが開きます。ここに要約と詳しい説明を書いて登録します。ファイルを追加することもできますので、不備がある部分のキャプチャを撮っておいてアップロードすると説明が楽かもしれません。登録するとBugsの自分が登録したバグ一覧でステータスが分かるようになります。Bug」をクリックするとフォームがポップアップで開くというもので、登録後のステータス変化について何のフィードバックも無かったのですが、今ではAPIの不具合と同様にBugsに登録されます。他のユーザにも見えますし、ステータスの変化も分かるので、とても便利になりました。4.まとめ以上が、私がFQLを扱う上で気をつけている点です。仕様変更が多かったり不具合がちょこちょこあるということがよく言われますが、ドキュメントを確かめつつ試し、不具合があれば報告まで行うことが、イライラを減らし、他の開発者の助けにもなると思います。文句を言う前にバグ報告までしっかり行いましょう。返され方が変わります動画の削除機能はドキュメントの誤りで、実はサポートされてませんでした。