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

4/25 から開催された F8 2015 で、Graph API v2.3 が紹介されました。Graph API を扱う上で影響が大きいと思われるものをここでは紹介します。詳細は公式 Changelog や Upgrade Guide を参照してください。

/oauth/access_token のレスポンス変更

これまでは URL エンコードされたクエリ文字列が以下の様な形式で返されていました。

access_token=foobar&expires=5183814

今後は以下のように JSON オブジェクトが返されるようになり、項目も若干変わります。 expires が expires_in に変わっている点も要注意です。

{"access_token":"123456789XXXXXXXXXXX","token_type":"bearer","expires_in":5183814}

Facebook::OpenGraph では対応済で、Version 1.23 をリリースしてあります。以下のように Graph API から返される実行バージョンを比較して適宜扱いを変えています。
話は逸れますが、このバージョン比較では Graph API から返される facebook-api-version ヘッダを参照しています。この場合、バージョン指定なしでリクエストしていたり、失効済みのバージョンを指定していてデフォルトバージョンに暗黙に切り替わった場合でも、実際に実行されたバージョンを正しく取得できるのが便利です。開発者コミュニティに何か質問する前にこの facebook-api-version ヘッダを確かめておいたり、Facebook Platform にバグ登録する際には x-fb-rev ヘッダを共有すると捗ります。詳しくは Debuggin API Requests の該当箇所を参照してください。

また、Python 版 facebook_graph にも同等の変更を入れ、Facebook::Graph の対応も pull-req 済みです。

limit パラメータのデフォルト値が 25 に

これまで、友達一覧取得 API ではデフォルトで全件が返されるなど、エンドポイントによって limit 未指定時のデフォルトの挙動が異なっていました。今度から、limit を省略した場合のデフォルト値は 25 に統一されます。

空配列は []、空オブジェクトは {} を返す

これまで、対象となるオブジェクトが存在しなければ空配列が返されるケースなどがありました。今後は、配列で返るべきケースとオブジェクトで返るべきケースでより一貫性を持つようになります。v2.1 公開時には、それまで true もしくは false の真偽値のみ返すエンドポイントがある傍らで {"success": true} を返すエンドポイントがあったりしたのを統一していましたが、今回も同様に、より一貫性を持たせる類の変更となります。

Facebook Page の Real-time Updates サポート強化

v2.2 公開時に Facebook Page の Real-time Updates API が追加されましたが、さらに今度の変更でサポートが強化されました。色々と項目が増えていますので、Changelog を参照してください。

デバッグモード追加

今後、リクエスト時に debug パラメータを指定するとデバッグ情報が返されるようになります。先述の facebook-api-version や x-fb-rev ヘッダと併用すると便利そうです。指定できる値は all, info, warning となります。それぞれの返り値については Debugging API Requests の一覧を参照してください。

「Graph API を使って動画の削除はできるの？」という質問が 4 月に stackoverflow に上がっていました。当時のドキュメントを見る限り、他の投稿系と同様の条件下で DELETE もサポートされていたのですが、新しくアプリを作成して試してみると、質問内容にある通りエラーが返されてしまうという状態でした。そこでバグ報告をしたところ、先月解決したので共有です。

結論から言ってしまうと、原因はドキュメントの誤りで、本来はアプリから投稿した動画の削除はできません。
以下のキャプチャはバグ報告時に添付した もので、Deleting という項目で削除方法の記述がありました。/photo と同じ方法で削除ができるように見えます。ですが、これ自体が間違いだったということで、いまはこの項目ごと消えています。


うーん、CRUD 周りについては、項目自体は残しつつサポートされていない旨を明記するのが他のエンドポイントでは主流のようなのだけど…


とりあえず、動画削除はできないので気をつけましょう。

現地時間の 10/30 に Graph API v2.2 が発表されました。ハイライトとされているのは以下の点です。以前のバージョンとの比較は後に続きます。

1. Facebook ページへのコメント投稿の表示を、Graph API 経由で切り替えられる。
2. ユーザオブジェクトに token_for_business フィールドが追加され、 同一開発者が管理する複数アプリ間で同一ユーザを特定できる。
3. Real-time Updates API の Facebook ページ対応が進み、Facebook ページのタブアプリとして登録していないアプリでも更新情報の subscribe ができるようになった。
4. より多くのページ情報が Graph API を通じて更新できるようになった。

1. コメント投稿の表示を Graph API で切り替える。

Facebook ページに対して投稿されたコメントの表示を切り替える事ができるようになりました。これまでは表示の on/off に関するフラグとして、 FQL の stream や notification などのテーブルで is_hidden が利用できました。v2.2 からは comment にも is_hidden, can_hide フィールドが追加されたため、can_hide で非表示可否をチェックし、is_hidden の真偽値指定で表示切替できます。

2. ユーザオブジェクトへの token_for_business フィールド追加

v2.0 からはユーザオブジェクトの ID がアプリ毎に異なるものになるため、異なるアプリ間で同一ユーザを特定するのが面倒でした。その対策として今までは Business Mapping API が提供されていましたが、今回の更新で user ノードに token_for_business が追加され、同一ユーザを特定する手段が増えました。Business Mapping API の利用と同様、この新機能の利用に際しては、business の作成とアプリの紐付けが必要です。これが完了すれば、同じ business に紐付いたアプリ間で共通となる文字列をuser.token_for_business が返すようになります。
また、Canvas アプリの場合には、iframe でページが呼び出される際に渡される signed_request にも同情報が含まれるようになります。

3. Real-time Updates API の Facebook ページ対応

これまでもユーザ情報の更新を購読する機能として Real-time Updates API が提供されていました。使い方についてはFacebook Night vol.7 発表内容まとめ 3：Batch RequestとReal-time Update APIを参照してください。登録の流れと取得方法は一緒なので、こちらのドキュメントで対象となる項目など見てみてください。

4. Facebook ページ情報を Graph API 経由での更新

これまでのページ情報更新と同様、 /{PAGE_ID} への POST で諸々のページ設定を更新できます。Change Log には新しく更新対象となるフィールドが追加されているのですが、まだドキュメントの該当箇所には足されていないようです。

まとめ

ということで、 Business Mapping API 以外の方法でアプリを跨いだユーザ特定を行う方法が追加された他は、ページ関連の更新が中心という印象です。

Facebookの言語設定で関西弁がサポートされて皆賑わっていますが、これによってGraph APIで返されるlocaleもja_JPとは限らなくなるため、対応に追われている開発者の方もいるんじゃないかと思います。すでに試された方も多いでしょうが、関西弁設定にした状態でGraph APIを利用してlocaleを得るとja_KSが返されます。

ドキュメントでは、localeはISO 639-1 language codeとcountry codeをアンダースコアで結んだものって言ってるのに、country_codeでKSが来るとは… いよいよプリンセス・トヨトミ の世界ですね。ちなみに、これと同じく例外として挙げられているのは、以下のとおりar_ARとes_LAだけです。

There are two exceptions that do not follow the ISO standard: ar_AR and es_LA. We use these to denote umbrella locales for Arabic and Spanish. (For Spanish, we support a few specialized localizations.)

こうなってくると、慎重な開発者の方はja_KSが正しいものなのか一度確かめたくなると思うのですが、以下の投稿にある通り、まだサポートされるlocale一覧に追加されていません。


バグ報告したらアサインされましたので、気になる方は以下のチケットをsubscribeしてみてください。
A new locale, ja_KS 日本語（関西）, is missing from Facebook Locales XML file. 

たこ焼き食べたい。

　

今日本家ブログで発表されている通り、Graph APIのバージョン2.1がリリースされました。これで、v1.0, v2.0, v2.1 がしばらく共存することになります。v1.0は例外として、原則、新しいバージョンが出てから2年間が旧バージョンのサポート期間です。ということで、v.2.0のサポートは2016年8月7日までとなりました。

主な変更内容

• APIを介したページ投稿で、他ページについて言及（mention）できるようになりました。アプリ開発者が管理するページ以外のFacebookページについて言及する場合は、アプリの申請を行ってFacebook側のレビューをクリアする必要があります。この申請手順と趣旨は2.0から始まったポリシーの延長ですね。
• /USER/friendsが友達数も返すようになりました。これは遡ってv2.0にも適用されます。
• v2.1でのレスポンスは必ずJSONオブジェクトになります。真偽値のみを返していたエンドポイントの返り値も変わります。
  補足：これまで/OBJ/likesエンドポイントを通じていいね！した場合のレスポンスは'true'もしくは'false'といった真偽値のみでしたが、拙作のFacebook::OpenGraphでは他のエンドポイントと同じように扱えるようにするため、(true|false)のみ返された場合に { "success": (true|false) }という文字列に置換した上でJSONデコードするようにしていました。今回の本家変更では最初から { "success": (true|false) } 形式で返されるようになったため、参照するフィールド名を含め、Facebook::OpenGraphを使っていた開発者は改修が不要です。
• Field expansionの形式がもっと簡潔になります。
  補足：Facebook::OpenGraphでは、ハッシュで渡されたリクエストパラメータをよしなに扱ってField expansion対応していますが、昔の形式もサポートされ続けるので特に改修は必要ありません。
• /?id=ENCODED_URLで、Open Graph上に登録されている該当URLの情報が取得できます。

無効となる機能

• FQLとREST APIが無効になります。ただし、2015年4月30日まで有効なv1.0と、2016年7月6日まで有効なv2.0では引き続き利用できます。
• Field Expansionの形式が簡潔になりますが、以前の書き方もサポートされ続けます。また、v1.0とv2.0でも新しい形式を利用できるようになります。
• Login Dialogは旧return_session, session_versionパラメータを受け付けなくなります。
• /APP/insightsがこの発表から90日後にあたる2014年11月5日に無効になりますので、代わりに/v2.1/APP/app_insightsを使わなくてはなりません。
• ページタブに表示するタイプのアプリで受け取るsigned_requestオブジェクトのpageプロパティでは、likedフィールドが返されなくなります。今日以前に作成されたアプリに関しては、2014年11月5日以降、likedフィールドでは常にtrueが返されるようになります。
• Recommendatinos Barプラグインは無効になります。90日後の2014年11月5日から先は、どのウェブサイトでも表示されなくなります。