Facebook開発者向けドキュメントの日本語訳とTips

FB.api({method: 'fql.query'},function(){})

検索して一番出てくるパターンです。一番シンプルなもので、指定されたqueryを実行し、そのレスポンスをコールバック関数へ渡します。下の例では、ログイン中のユーザがlikeしたページを取得してリスト表示します。(source_id=me()と書かれている部分は、ログイン中のユーザのIDが補完されます。)

    FB.api(
        {
            method : 'fql.query',
            query : 'SELECT name,type,page_url FROM page WHERE page_id
IN (SELECT target_id FROM connection WHERE source_id=me() and
target_type="Page") AND type!="APPLICATION"'
        },
        function(response) {
            var ul = $(document.createElement('ul'));
            for (var i=0;i<response.length;i++) {
                var row = response[i];
                $(document.createElement('li'))
                    .text(row.name)
                    .appendTo(ul);
            }
            ul.appendTo('#main_container');
        }
    );

上記の場合は一度の問い合わせで一つのFQLクエリを実行しますが、これに対し、method: 'fql.multi_query'は複数のFQLクエリを実行できます。

FB.Data.query

FB.Data.queryを使うと下記のようにプレイスホルダを使うことができます。下記サンプルでは、{0}にFB.getSession().uidが補完されます。実行しているFQLは上述のものと同じです。

また、ここでは返された配列の処理にFB.Array.forEachを使っています。第一引数に配列を渡し、第２引数に関数を渡します。ここで指定する関数には、配列の一つ一つの要素が渡されます（この場合はpageテーブルから取得した各レコードです）。

    //ログイン中のユーザがlikeしたページ（アプリケーションを除く）
    var likeStmt = FB.Data.query('SELECT name,type,page_url FROM page
WHERE page_id IN (SELECT target_id FROM connection WHERE source_id={0}
and target_type="Page") AND type!="APPLICATION"',FB.getSession().uid);

    likeStmt.wait(function(rows){
        var ul = $(document.createElement('ul'));
        FB.Array.forEach(rows,function(row){
            $(document.createElement('li'))
                .text(row.name)
                .appendTo(ul);
        });
        ul.appendTo('#main_container');
    });

FB.Data.queryとFB.Data.waitOnで、複数クエリを扱う

下記サンプルでは、ユーザが投稿したリンクを取得するクエリ(linkStmt)とユーザ情報を取得するクエリ(userStmt)の両方が完了してからコールバック関数が実行されます。FB.Data.waitOn()の第一引数にはFB.Data.queryオブジェクトを配列で渡し、第２引数にコールバック関数を指定します。

FB.Data.waitOn([u1,u2], function(args){ var u1_value = args[0], // u1クエリの返り値} のように各クエリの返り値(args[i])を得る代わりに、u1.valueのようにして返り値を得ることが出来ます。ここでは、その値をFB.Array.forEachに渡して処理しています。

    //ログイン中のユーザが投稿したリンクを新着順で
    var linkStmt = FB.Data.query('SELECT title, url FROM link WHERE
owner = {0} ORDER BY created_time DESC',FB.getSession().uid);

    //ログイン中のユーザの名前
    var userStmt = FB.Data.query('SELECT name FROM user WHERE uid = me()');

    //両クエリのレスポンスを待ってコールバックを実行
    FB.Data.waitOn([linkStmt,userStmt],function(){

        var ul = $(document.createElement('ul'));
        FB.Array.forEach(linkStmt.value,function(row){
            $(document.createElement('li'))
                .append($(document.createElement('a'))
                    .attr('href',row.url)
                    .attr('target','_blank')
                    .text(row.title)
                )
                .appendTo(ul);
        });
        ul.appendTo('#main_container');

        FB.Array.forEach(userStmt.value,function(row){
            $(document.createElement('p'))
                .appendTo('body')
                .text(row.name);
        });

    });

最適化してくれる

FB.Data.query()でクエリを指定するたび、そのクエリはFB.Data.queue配列に足されて行き、FB.api({method:'fql.multi_query'},.....)を用いて一度に実行されます。実行された段階でFB.Data.queueは空の配列になり、また次の実行を待ちます。

なので、下記のように別々にクエリを設定しても、これらは要所要所でまとめられて一度のHTTPリクエストで問い合わされます。

    var linkStmt = FB.Data.query('SELECT ...........', FB.getSession().uid);
    var userStmt = FB.Data.query('SELECT .................');

    FB.Data.waitOn([linkStmt,userStmt],function(){
        ................
    });

    // FB.Data using wait
    var someQuery = FB.Data.query('SELECT ...............',FB.getSession().uid);
    someQuery.wait(function(rows){
       
    });

firebugでパラメータを見ると下記のようになっています。3個のクエリがv_1,v_2,v_3として1個にまとめて問い合わされているのが分かります。

access_token	.............................
api_key	.............................
callback	FB.ApiServer._callbacks.f65f7e4093041a
format	json-strings
method	fql.multiquery
pretty	0
queries	{"v_1":"select title,url from link where owner = 44007581 ORDER BY created_time DESC","v_2":"select name from user where uid = me()","v_3":"select name,type,page_url from page where page_id IN (SELECT target_id FROM connection WHERE source_id=44007581 and target_type=\"Page\") AND type!=\"APPLICATION\""}
sdk	joey

まとめ

以上のように、JavaScript SDKでFQLを扱うには色々な方法がありますが、FB.apiに直接クエリを指定するよりは、FB.Data.queryやFB.Data.waitOnを使い合わせるのが便利そうなので使ってみてください。