プラットフォームのバージョン管理

Facebookのプラットフォームは、アプリ開発者が段階的に変更を導入できるように、バージョン管理をサポートしています。このドキュメントでは、バージョンがSDKとAPIに及ぼす影響と、リクエストでそれらのバージョンを使用する方法について説明します。

バージョン管理

すべてのAPIやSDKが同じバージョン管理システムを共有しているわけではありません。たとえば、グラフAPIのバージョンは、iOS用Facebook SDKとは異なるペースと番号で管理されています。すべてのFacebook SDKは、異なるバージョンのAPIと対話する機能をサポートしています。バージョンごとに機能が異なる複数バージョンのAPIまたはSDKが共存可能です。

グラフAPIの最新バージョン

グラフAPIの最新バージョン: v19.0

異なるバージョンがある理由

バージョン管理を行う目的は、アプリの開発者が、APIやSDKが変更されるタイミングを事前に把握できるようにすることです。これはウェブ開発でも役立ちますが、モバイル開発では必須とも言えます。スマホでアプリを使う人がアプリをアップグレードするまで長時間かかる(または決してアップグレードしない)可能性があるからです。

各バージョンはリリースから少なくとも2年間は維持されるため、該当アプリがどれだけの期間動作を続けるか、またどれだけの期間新しいバージョンへのアップデートをしなければならないかについてタイムラインをしっかり把握することができます。

バージョンスケジュール

各バージョンは最低でも2年間の動作が保証されています。次のバージョンがリリースされた日から2年後に、現在のバージョンは使用できなくなります。例えば、APIバージョンv2.3が2015年3月25日にリリースされ、APIバージョンv2.4が2015年8月7日にリリースされたとすると、v2.3はv2.4リリースの2年後の2017年8月7日に期限が切れることになります。

APIの場合、あるバージョンが使用できなくなると、そのバージョンに対して行われた呼び出しは、その次に古い使用可能なバージョンにデフォルトで設定されます。以下は、タイムラインの例です。

SDKについては、ダウンロード可能なパッケージであるため、バージョンは常に利用可能です。ただし、SDKは動作しなくなったAPIやメソッドに依存している可能性があるため、サポートを終了したSDKはもはや機能していないと考えてください。

バージョンのタイムライン、変更点、リリース日についての具体的な情報は、更新履歴ページでご覧いただけます。

1つのバージョン内で変更が起こることはないのでしょうか？

Facebookは、セキュリティやプライバシーに関する問題に対処するため、短期間であらゆるAPIを変更する権利を有しています。これらの変更は頻繁ではありませんが、実際に起きることは確かです。

APIのバージョンを指定しないとどうなるのでしょうか？

バージョンを指定せずに行われたAPI呼び出しは、バージョン指定のない呼び出しと呼ばれます。たとえば、現在のバージョンがv4.0だとします。呼び出しは次のようになります:

curl -i -X "https://graph.facebook.com/v4.0/{my-user-id}&access_token={access-token}"

これと同じ呼び出しで、バージョン指定のないものは、次のようになります:

curl -i -X "https://graph.facebook.com/{my-user-id}&access_token={access-token}"

バージョン指定のない呼び出しは、アプリダッシュボードの[設定] > [詳細]の[APIバージョンのアップグレード]カードで設定されたバージョンを使用します。次の例で、アプリダッシュボードのバージョンセットはv2.10であり、バージョン指定のない呼び出しはこれに相当することになります:

curl -i -X "https://graph.facebook.com/v2.10/{my-user-id}&access_token={access-token}"

可能な限り常にバージョンを指定することをおすすめします。

制限

Facebook JavaScript SDKに、バージョン指定のないAPI呼び出しは行えません。

アプリから現在のバージョンよりも古いバージョンへの呼び出しを行うことはできますか？

旧バージョンのAPI呼び出しは、それが利用可能であって、かつ該当アプリでそれまでにそのバージョンの呼び出しをしたことがあるなら、指定することができます。例えば、v2.0リリース後に作成されたアプリでv2.0を使用した呼び出しをしている場合、それより新しいバージョンがリリースされた後も、v2.0が期限切れになるまではそのバージョンの呼び出しをすることができます。v2.0の後に作成されたアプリでv2.2までは呼び出しをしていなかった場合、v2.0またはv2.1を使用した呼び出しをすることはできなくなります。実行できるのは、v2.2以降のバージョンを使用した呼び出しだけです。

マーケティングAPIのバージョン管理

マーケティングAPIには、独自のバージョン管理スキームがあります。バージョン番号もそのスケジュールも、グラフAPIの場合とは異なります。

マーケティングAPIのバージョン管理について詳しくはこちら

バージョン指定リクエストの実行

グラフAPI

コアであれ拡張であれ、ほとんどのグラフ APIエンドポイントはバージョン指定されたパスで利用できます。Graph APIでのバージョンの詳しい使い方については、Graph APIクイックスタートガイドで説明しています。

ダイアログ

バージョン指定パスは、APIエンドポイントだけでなく、ダイアログやソーシャルプラグインにも当てはまります。たとえば、ウェブアプリ用にFacebookログインダイアログを生成したい場合、ダイアログを生成するエンドポイントの前にバージョン番号を付けることができます。

https://www.facebook.com/v19.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}

ソーシャルプラグイン

FacebookソーシャルプラグインのHTML5またはxfbmlのバージョンを使用している場合、レンダリングされるバージョンは、JavaScript SDKを初期化する時点で指定されるバージョンによって決まります。

プラグインのiframe版やプレーンリンク版を挿入している場合は、プラグインのソースパスの前にバージョン番号を付けます。

<iframe
  src="//www.facebook.com/v19.0/plugins/like.php?href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2Fplugins%2F&amp;width&amp;layout=standard&amp;action=like&amp;show_faces=true&amp;share=true&amp;height=80&amp;appId=634262946633418" 
  scrolling="no" 
  frameborder="0" 
  style="border:none; overflow:hidden; height:80px;" 
  allowTransparency="true">
</iframe>

SDKからのバージョン指定リクエスト

iOS、Android、またはJavaScript用Facebook SDKを使用している場合、バージョン指定の呼び出しの大半は自動です。これは、各SDK独自のバージョン管理システムとは異なることに注意してください。

JavaScript

JavaScript SDKが異なる複数のAPIバージョンを使用できるのは、sdk.jsパスを使用している場合のみです。

JavaScript SDKからFB.init()を使用している場合、次のようにして、バージョンパラメーターを使用する必要があります:

FB.init({
  appId      : '{app-id}',
  version    : 'v19.0'
});

initでバージョンフラグを設定すると、FB.api()を呼び出すごとに、呼び出されるパスの前に自動的にバージョンが付加されます。Facebookログインのためのダイアログが呼び出されることになった場合にも、同じことが当てはまります。そのバージョンのAPIのFacebookログインダイアログが表示されます。

必要であれば、FB.api()呼び出しのエンドポイントのパスの前にバージョンを付加するだけで、バージョンを上書きできます。

iOS

リリースされたiOS用Facebook SDKの各バージョンは、リリース日に利用可能なバージョンに関連付けられています。つまり、新しいSDKにアップグレードする場合、最新のAPIバージョンへのアップグレードも実行することになるということです(使用可能な旧バージョンのAPIを、[FBSDKGraphRequest initWithGraphPath]により手動で指定することは可能)。APIバージョンは、iOS用Facebook SDKの各バージョンのリリースに記載されています。

JavaScript SDKと同じように、iOS用Facebook SDKを介してグラフAPIを呼び出す際には、その前にバージョンが付加されます。例えば、APIの最新バージョンがv2.7である場合、/me/friendsの呼び出し(次のサンプルコードで使用されているもの)で実際に呼び出されるのは、/v2.7/me/friendsになります:

[[[FBSDKGraphRequest alloc] initWithGraphPath:@"me/friends"
  parameters:@{@"fields": @"cover,name,start_time"}]
    startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
        (...)
    }];

呼び出しのバージョンは、[FBSDKGraphRequestConnection overrideVersionPartWith]で上書きすることができます。

Android

リリースされたAndroid用Facebook SDKの各バージョンは、リリース日に利用可能なバージョンに関連付けられています。つまり、新しいSDKにアップグレードする場合、最新のAPIバージョンへのアップグレードも実行することになるということです(使用可能な旧バージョンのAPIを、GraphRequest.setVersion()により手動で指定することは可能)。APIのバージョンは、Android用Facebook SDKの各バージョンのリリースに記載されています。

JavaScript SDKと同様に、Android用Facebook SDKを介してグラフAPIを呼び出す際には、その前にバージョンが付加されます。例えば、APIの最新バージョンがv2.7である場合、/meの呼び出し(次のサンプルコードで使用されているもの)で実際に呼び出されるのは、/v2.7/meになります:

GraphRequest request = GraphRequest.newGraphPathRequest (
        accessToken,
        "/me/friends",
        new GraphRequest.GraphJSONObjectCallback() {
            @Override
            public void onCompleted(
                   JSONObject object,
                   GraphResponse response) {
                // Application code
            }
        });
Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,link");
request.setParameters(parameters); 
request.executeAsync();

呼び出しのバージョンは、GraphRequest.setVersion()で上書きすることができます。