グラフAPIバージョンアップグレードガイド

このガイドは、アプリのバージョンをアップグレードする際に役立ちます。バージョンのアップグレードに向けてアプリをテスト、準備するためのステップが収録されています。各プラットフォームリリースの変更内容については、プラットフォームの更新履歴に関するページを参照してください。

複数のバージョンを一括でアップグレードすることが推奨されます。利用可能な最新バージョンにアップグレードすると、アップグレードにかかる時間を最適化できます。

一般のアップグレードツール

APIアップグレードツール

APIアップグレードツールには、指定したターゲットバージョンへのアップグレードでアプリに影響する変更内容のカスタムリストが表示されます。アップグレード前のバージョンとアップグレード後のバージョンの間の関連する変更がすべて表示されるため、複数のバージョンをアップグレードする場合に特に便利です。

テストユーザー

テストユーザーを使用して、プロダクションアプリが特定のバージョンでどのように動作するかをテストできます。テストユーザーのアクセストークンを使用して、呼び出しに適用されている最小グラフAPIバージョンを上書きするように、テストユーザーを編集できます。これにより、アプリの既存のプロダクションバージョンのアップグレード後の動作を確認できます。

早期アップグレード

バージョンアップグレードの1か月前に、該当するアプリのアプリダッシュボードの[詳細設定]セクションに[API Version Upgrades]セクションが追加されます。このセクションには次の機能があります。

開発者と管理者のアップグレード

アプリのすべての開発者と管理者が、次に利用可能なバージョンにアップグレードされます。これは、テストユーザーを使用したバージョンの上書きに似ていますが、実際の利用者によるテストから、より豊富で多様なデータが得られるというメリットがあります。

すべての呼び出しのアップグレード

アプリが実行するすべての呼び出しが、次に利用可能なバージョンにアップグレードされます。最初にテストユーザーかアプリ開発者のいずれかを使用してアップグレード後の動作をテストした後で、この機能を使用することが推奨されます。早期アップグレードは、予期しなかった不具合や問題が発生した場合に元のバージョンに戻ることができるオプションがあるため、便利です。

v2.4からv2.5へのアップグレード

グラフAPI

GET {user_id}/accounts

v2.5ではmanage_pagesまたはpages_show_listのいずれかのアクセス許可が必要になりました。

コールトゥアクションのアクセス許可

POST {page_id}/call_to_actionsPOST/DELETE {call-to-action-id}には、v2.5で導入された新しいアクセス許可pages_manage_ctaが必要になりました。

RTUの購読の無効化

コールバックURLが7日間連続で失敗した場合に、リアルタイムアップデート(RTU)の購読を自動的に無効にできるようになりました。再度有効にするには、POSTリクエストを/subscriptionsに対して行います。この変更は支払い購読には適用されません。

マーケティングAPIの名前変更

APIとUI間の3レベルキャンペーン構造において一貫性のある命名規則が導入されました。これによって、エンドポイント、パラメーター、フィールド、enumレベルの命名規則が変更されます。変更内容の詳細は、こちらをご覧ください。

v2.3からv2.4へのアップグレード

グラフAPI

フィールドの取得方法の変更

これまでは、グラフAPI呼び出しからの応答により、一連のデフォルトフィールドが返されていました。ペイロードサイズを減らし、モバイルネットワークの遅延を改善するため、大部分のグラフAPI呼び出しについて、返されるデフォルトフィールドの数を減らしました。v2.4では、呼び出しの応答フィールドを宣言によってリストする必要があります。

タイムライン投稿の取得方法の変更

アプリがユーザーまたはページの{id}/linksまたは{id}/statusesを参照している場合は、{id}/feedを使用するようにこれらの呼び出しを変更する必要があります。

特定のページエッジでの検索結果の最大制限数: 100

ページに対して呼び出しを実行してデータを取得するときに、v2.4では検索結果の最大制限数として100が適用されます。これは、ページの/feed/posts/promotable_postsエッジに影響します。グラフAPI呼び出しがこの制限を超える可能性がある場合は、結果を複数ページに分割する必要があります。

ページへのアクセス許可の変更

v2.3からv2.4の間では、ページへのアクセス許可に関して、アプリに反映する必要がある変更が多数あります。まず、ページアクセストークンには、/v2.4/{page_id}/promotable_posts/v2.4/{page_id}/offers/v2.4/{page_id}/milestonesとのインターフェイスが必要になりました。また、ページの大事な出来事とクーポンにはmanage_pagespublish_pagesアクセス許可が必要になりました。

イベントの変更

グラフAPI v2.4では、{event_id}/invited{event_id}/likes{event_id}/sharedpostsに対するGET操作が削除されました。

その他に廃止されたもの

90日後および2年後に廃止が予定されている機能とアクセス許可がいくつかあります。詳細については、プラットフォームv2.4更新履歴、90日後に廃止されるものに関するページをご覧ください。

v2.2からv2.3へのアップグレード

グラフAPI

ページのリアルタイムアップデート

これまで、ページからのリアルタイムアップデート(RTU)にはアップデートをトリガーしたオブジェクトのIDだけが含まれていました。この場合、アップデートに関する内容をさらに検出するには、グラフAPIに対し、{object_id}を使用して追加の呼び出しを実行する必要がありました。2015年3月25日以降、ページRTUにはオブジェクトタイプに基づく実際のコンテンツが含まれています。これにより、追加の呼び出しは不要になりました。

また、ページの評価に新しいRTUプロパティが追加されました。開発者はこのプロパティをフォローすることで、評価のアップデートが発生するたびにアップデートを取得できます。

デフォルトの検索結果制限数: 25

v2.3では、limitパラメーターを指定せずにエッジを呼び出すと、デフォルトの結果制限数として25が適用されます。グラフAPI呼び出しがこの制限を超える可能性がある場合は、応答数が多くなる場合に備えてlimitパラメーターを指定します。

空の配列応答

v2.3では、すべてのグラフAPI応答により、空の配列が有効なJSONフォーマットでシリアル化されます。コードが空の配列の古い処理方法に依存している場合は、詳細についてFacebookプラットフォーム更新履歴: APIバージョン2.3の更新履歴の項目をご覧ください。

ログインフローを手作業で構築する

独自のログインフローを構築する場合、最新のOAuth RFC仕様に準拠するためのOAuthコード交換のアップデートがあります。詳細については変更履歴の項目をご覧ください。Facebookプラットフォーム更新履歴: APIバージョン2.3をご覧ください。

写真エッジのデフォルトの変更

写真エッジに対応していないノードでの写真エッジの動作が変更されました。グラフAPI v2.3より前のバージョンでは、このエッジは未定義の写真を示す疑問符を返しました。

LinkPostThreadCommentStatusノードのこのエッジについて、グラフAPIはエラーを返すようになりました。

リクエストオブジェクトの名前変更

グラフAPIの以前のバージョンでは、/v2.x/{user-id}/apprequestsに対する呼び出しを実行するすべてのアプリタイプがサポートされていました。このエッジは、ゲームアプリの招待リクエストに使用されていました。v2.3以降では、ゲーム以外のアプリがRequestsオブジェクトを使用する場合、App Inviteを使用するようにアプリを変更する必要があります。

ページオブジェクト関連の変更

  • ページアクセストークンが必須 - アプリがページの代わりに投稿、コメント、いいねなどの操作を実行する場合、これらの操作は渡されたアクセストークンに基づいて行われるようになりました。ページの代わりにアクションを実行する場合は、コードで適切なページアクセストークンが渡されることを確認してください。

  • countrycountriesに名前変更- ページ投稿のfeed_targetingフィールドのcountryサブフィールドの名前がcountriesに変更されました。これは、POST|GET /v2.3/{page-post-id}の呼び出しに影響します。

  • ページの削除 - アプリがDELETE /v2.3/{comment-id}を使用してページ投稿を削除する場合そのページの管理者アクセス許可を含むページアクセストークンを渡す必要があります。

  • countryの要件 - アプリが/v2.3/{page-id}locationフィールドを更新する場合は、countryサブパラメーターを指定する必要があります。country='United States'の場合、stateサブパラメーターも指定する必要があります。

  • POSTページのフィールドの変更 - Pagehoursparkingpayment_optionsフィールドへのアップデートのPOSTの動作が変更されました。Facebookプラットフォーム更新履歴: APIバージョン2.3をご覧ください。

アクセス許可の変更

  • user_posts - アプリに対し利用者のタイムラインの投稿へのアクセスを許可する、新しいアクセス許可user_postsが追加されました。これまでは、このコンテンツにアクセスするにはread_streamアクセス許可を使用していました。read_streamアクセス許可があるアプリには、user_postsアクセス許可が自動的に付与されています。Facebookプラットフォーム更新履歴: APIバージョン2.3をご覧ください。

  • ページへの投稿 - アプリがページに投稿する場合、publish_pagesアクセス許可とmanage_pagesアクセス許可の両方が必要になりました。v2.2以前で利用者にpublish_actionsアクセス許可とmanage_pagesアクセス許可が付与されていた場合、その利用者には自動的にpublish_pagesが付与されています。ただし、publish_pagesを使用するかまたはv2.3以上で新しい利用者からこのアクセス許可をリクエストする場合は、ログインレビューからそのアクセス許可を使用することが承認されている必要があります。

  • read_friendlistsの名前変更 - read_friendlistsアクセス許可がread_custom_friendlistsに名前変更されました。Facebookプラットフォーム更新履歴: APIバージョン2.3をご覧ください。v2.3以上ではログインダイアログでread_custom_friendlistsを指定する必要があります。以前のバージョンでread_friendlistsを付与した利用者の場合、v2.3以上で/me/permissionsを呼び出すとこれはread_custom_friendlistsとして返されます。

位置情報と場所の変更

  • 一貫性のあるplaceフィールド - アプリがPhotosAlbumsVideos、およびStatusesPlaceタグを使用する場合、グラフAPI v2.3への移行時にいくつか変更を行う必要があります。v2.3では、placeフィールドには常に、name フィールドやlocationオブジェクトなどの一貫性のあるデータが含まれています。

  • Eventplace - 一貫性のある方法で場所データを格納するようにEventノードが更新されました。以前はイベントのlocationフィールドには場所のnameが含まれ、venueフィールドにはlocationオブジェクトが含まれていました。v2.3ではlocationフィールドとvenueフィールドの両方が廃止され、namelocationオブジェクトはplaceフィールドに格納されます。

90日後に廃止されるその他のもの

90日後に廃止される機能とソーシャルプラグインが多数あります。プラットフォームv2.3更新履歴: 90日経過後に廃止されるものをご覧ください。

ソーシャルプラグイン

  • コメントプラグインの変更 - Facebookコメントプラグインを利用している場合は、versionパラメーター(version=v2.3)を渡すようにFacebook JS SDKのURLをアップグレードします。2015年6月22日以降、古いバージョンのコメントプラグインは自動的にv2.3にアップグレードされます。

  • Facebookいいね!ボックス - Facebookいいね!ボックスを使用している場合は、この機能の代わりにページプラグインを使用することが推奨されます。そのためには、Facebookいいね!ボックスdiv=fb-like-boxdiv classdiv=fb-pageに置き換えます。これは自動的にアップグレードされます。

v2.1からv2.2へのアップグレード

グラフAPI

ページのリアルタイムアップデート

多くのアプリで、ページの変更のためにリアルタイムアップデートが使用されています。これにはコメントや投稿などのデータが含まれます。v2.2以前のバージョンでは、このためにページタブアプリとして登録されていなかった/{page-id}/tabsアプリにアプリを追加していました。

リアルタイムアップデートのためのアプリの登録にtabsエッジを使用することは廃止されます。tabsエッジを使用する代わりに、新しい/v2.2/{page-id}/subscribed_appsエンドポイントを使用して、リアルタイムアップデートの購読を管理できます。

すべてのアプリは、新しいリアルタイムアップデートインターフェイスを使用する必要があります。

多くのインターフェイスでページアクセストークンが必須に

以前のバージョンでは、ユーザーアクセストークンを使用して、一部のインターフェイスを介して一部のページデータにアクセスできました。v2.2では、多くのインターフェイスでページアクセストークンを使用することが必須となりました。詳細については、更新履歴のさまざまな項目をご覧ください。

ids=x,y,z構文で返されるIDの数を50個に制限

グラフAPIの利用」ドキュメントに記載されているids=構文を使用している場合は、一度にリクエストできるIDの数が50に制限されています。

/{page_id}/adminsエッジから/{page_id}/rolesへの変更

インターフェイスを新しいエッジ名に移行するだけでなく、返される値も変更されました。詳細については、更新履歴をご覧ください。

/{page_id}/settingsがアップデートに新しいフォーマットを使用

以前のバージョンではsettingパラメーターとvalueパラメーターが使用されていました。v2.2ではoptionパラメーターを指定する必要があります。このパラメーターは、1つのキー/値ペアが含まれており、キーとしてenumが設定されているオブジェクトです。詳細については、settingsエッジを参照してください。

/{group-id}/albums/{user_id}/albumsと同じ構文を使用

グループの以前のバージョンのalbumsエッジは、ユーザーのエッジとはフォーマットが異なりました。現在は同じフォーマットを使用するようになりました。詳細については、/{user-id}/albumsエッジをご覧ください。

90日後に廃止されるその他のもの

その他にも、いくつかのあまり使用されない機能が90日後に廃止されます。詳細については、更新履歴の該当するセクションをご覧ください。

質問がある場合は、

よくある質問に関するページをご覧ください。