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

Facebookのプラットフォームは、アプリ開発者が時間をかけて変更を適用できるように、バージョン管理とマイグレーションの両方をサポートしています。バージョン管理と安定性を提供するために、プラットフォームのサービスと機能の全範囲をコアと拡張の2つのグループに分割しました。

これらのグループの意味、グループがバージョンから受ける影響、FacebookのAPIとSDKでのこれらのバージョンを使用する方法、マイグレーション期間とは何かを理解するために読み進めてください。

コアと拡張

バージョンを提供するために、FacebookのプラットフォームコンポーネントであるAPIとSDKは、「コア」というラベルが付けられたものと「拡張」というラベルが付けられたものに分割されています。

コアのAPIとSDKは、開発者に提供されるFacebookプラットフォームの中核をなしています。これらの要素は、バージョンシステムに依存しており、コアAPIノード、フィールド、エッジ、ダイアログ、SDK、SDKメソッドと見なされるものはすべてそのバージョンの公開から少なくとも2年間は使用可能で、変更されないことを保証します。コア内の要素の根本的な変更は、新しいバージョンをリリースすることによってのみ行う必要があります

コア要素を以下に示します。

拡張は、上記以外のすべて、つまり、迅速な変更が必要とされるAPIとSDKです。このようなSDKとAPIはさまざまなバージョン経由でアクセスされますが、いつでも変更または削除される可能性があり、Facebookのプラットフォームロードマップで発表される90日マイグレーションの対象になっています。または、次の使用可能なAPIバージョンに同梱される場合もありますが、そのバーションの2年ウィンドウには含まれず、バージョンの有効期限が切れるかなり前に変更されることがあります。

バージョン管理

すべてのAPIとSDKが同じバージョン管理システムを共有するわけではありません。たとえば、グラフAPIは、iOS SDKとは異なるペースと番号付けを使用してバージョンが管理されます。2014年4月30日以降にリリースされたすべてのSDKは、APIのさまざまなバージョンと互換性があります。バージョンごとに機能が異なる複数のバージョンのAPIとSDKが同時に存在する可能性があります。

グラフAPIの最新バージョンは何ですか?

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

v3.1

バージョンがある理由は何ですか。

バージョン管理を行う目的は、アプリを構築する開発者が、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の場合は、ダウンロード可能パッケージのため、バージョンはいつでも入手できますが、サポート終了日を過ぎると、機能しなくなったAPIやメソッドに依存している可能性がある、サポート終了となったSDKも機能しなくなることを想定しておく必要があります。

更新履歴ページで、バージョンのタイムライン、変更、リリース日に関する個別の情報を確認することができます。

1つのバージョンでコアな要素が変更されることはありますか?

Facebookは、セキュリティやプライバシーに関係する問題が発生した場合に短期間のうちにAPIに変更を加える権利を有します。このような変更は頻繁には行われませんが、確実に行われます。

APIのバージョンを指定しないとどうなりますか?

Facebookでは、このような状態をバージョン指定のない呼び出しと呼びます。バージョン指定のない呼び出しは、デフォルトで、APIの使用可能な最も古いバージョンに設定されます。このAPIバージョンの仮のライフサイクルについて考えてみます。

バージョン指定のない呼び出しは、常に、チャートの一番上にあるまだ使用可能な最も古いバージョンを指しています。これは、今はv2.1ですが、2年後にはv2.2になり、その2年後にはv2.3になるというように変化して行きます。

そのため、可能な場合は、呼び出し時に必ずバージョンを指定することをおすすめします。

Facebook用JavaScript SDKを使用している場合は、バージョン指定のないAPI呼び出しを実行できません。

アプリで現在のバージョンよりも古いバージョンを呼び出せますか?

アプリは、アプリの作成時点で最新だったAPIのバージョンだけなく、アプリの作成後に公開されたより新しい廃止されていない任意のバージョンも呼び出すことができます。

たとえば、アプリがv2.0のリリース後に作成された場合は、v2.0はその有効期限が切れるまで、それ以降のバージョン(v2.1など)はそれぞれの有効期限が切れるまで呼び出すことができます。

アプリが作成されたが、新しいバージョンがリリースされるまで呼び出しやリクエストに使用されなかった場合は、古いバージョンを呼び出すことができません。例を使って説明します。

  • 最新バージョンがv2.0であった時点でアプリを作成したが、そのアプリがv2.1がリースされるまで使用されなかった場合、アプリで使用できるのはv2.0ではなく、v2.1のみになります。
  • 最新バージョンがv2.0であった時点でアプリを作成し、v2.1がリリースされる前にそのアプリを使用した場合は、v2.1のリリース後もv2.0を引き続き使用できます。

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

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

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

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

グラフAPI

コアまたは拡張のいずれであっても、ほぼすべてのグラフAPIエンドポイントには、バージョン指定パスを経由してアクセスできます。グラフAPIクイックスタートガイドに、グラフAPIでのバージョンの使用に関する完全ガイドが記載されています。

ダイアログ

バージョン指定パスは、APIエンドポイントには当てはまりませんが、ダイアログやソーシャルプラグインには当てはまります。たとえば、ウェブアプリ用のFacebookログインダイアログを作成する場合は、ダイアログを作成するエンドポイントの先頭にバージョン番号を付加することができます。

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

ソーシャルプラグイン

FacebookのソーシャルプラグインのHTML5またはxfbmlバージョンを使用している場合は、呼び出されるバージョンがJavaScript SDKの初期化中に指定されたバージョンによって決定されます。

Facebookのプラグインのいずれかのiframeまたはプレーンリンクバージョンを挿入している場合は、プラグインのソースパスの先頭にバージョン番号が付加されます。

<iframe
  src="//www.facebook.com/v3.1/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用Facebook SDK、Android用Facebook SDK、JavaScript用Facebook SDKを使用している場合は、バージョン管理呼び出しの大部分が自動的に行われます。このことは、SDKのバージョン管理システムによって異なることに注意してください。

JavaScript

sdk.jsパスを使用している場合は、JavaScript SDKでは異なるAPIバージョンしか使用できません。

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

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

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

必要な場合は、FB.api()呼び出しのエンドポイントのパスの先頭にバージョンを付加するだけで、バージョンを上書きすることができます。

iOS

リリースされたiOS SDKの各バージョンは、リリース日に使用可能なバージョンに対応付けられます。これは、新しいSDKにアップグレードすると、最新のAPIバージョンにアップグレードすることにもなることを意味します(ただし、[FBSDKGraphRequest initWithGraphPath]を使用して、使用可能な旧バージョンのAPIを手動で指定することができます)。APIバージョンは、iOS SDKの各バージョンのリリースにリストされます。

JavaScript SDKと同様に、iOS SDK経由でグラフAPIに対して発行されるすべての呼び出しの先頭にバージョンが付加されます。たとえば、v2.7がAPIの最新バージョンだった場合は、次のコードサンプルで使用される呼び出し/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 SDKの各バージョンは、リリース日に使用可能なバージョンに対応付けられます。これは、新しいSDKにアップグレードすると、最新のAPIバージョンにアップグレードすることにもなることを意味します(ただし、GraphRequest.setVersion()を使用して、使用可能な旧バージョンのAPIを手動で指定することができます)。APIバージョンは、Android SDKの各バージョンのリリースにリストされます。

JavaScript SDKと同様に、Android SDK経由でグラフAPIに対して発行されるすべての呼び出しの先頭にバージョンが付加されます。たとえば、v2.7がAPIの最新バージョンだった場合は、次のコードサンプルで使用される呼び出し/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()で上書きすることができます。

マイグレーション

マイグレーションは、Facebookプラットフォームの拡張要素に対する変更です。この変更では、新しい動作が導入されることがあるため、互換性を破る変更になります。

現在進行中のマイグレーションがプラットフォームページに一覧表示されます。マイグレーションには、最短でも90日間の移行期間があり、この期間中にアプリを移行する必要があります。移行期間が始まると、移行後の動作が、新しいアプリのデフォルトとなります。マイグレーション期間が完了すると、マイグレーション前の動作は完全に利用できなくなります。

ロードマップの個別のセクションに、完了したマイグレーションに関する情報があります。

グラフAPIによるマイグレーションの管理

マイグレーションは、/appノード内のマイグレーションフィールドを経由して管理できます。

エッジ上でアップデートを呼び出し、マイグレーションの開始と停止を実行できます。

アプリダッシュボードによるマイグレーションの管理

アプリダッシュボード[設定] > [詳細設定] > [マイグレーション]で、使用可能なマイグレーションの開始と停止を実行することができます。

クライアント側での一時的なマイグレーションの開始

アプリダッシュボードで、またはAPIを経由してマイグレーションを開始する代わりに、マイグレーションを設定するAPI呼び出しに特別なフラグを追加することができます。このフラグは「migrations_override」と呼ばれ、どのマイグレーションをオンまたはオフにするかを定義するJSON blobを指定する必要があります。たとえば、raw型の呼び出しを実行する場合、このフラグを次のように渡します。

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

これを使用することにより、すべての利用者が同時に新しいAPIを呼び出してアップデートしなくても、クライアントのアップデートを通して新しいAPIを呼び出すことができます。また、デバッグにも大変便利です。

これらのマイグレーションの名前は、上述の/appノードに記載されています。

JavaScript SDK、iOS SDK、Android SDKのAPIメカニズムを使用して、このフラグを渡すこともできます。