平台版本控制

Facebook 平台支援版本控制功能，以便應用程式開發人員逐步推出新變更。本文件會講解不同版本如何影響 SDK 和 API，以及如何在要求中使用這些版本。

版本控制

並非所有 API 和 SDK 都會共用相同的版本控制系統。例如，與 iOS 版 Facebook SDK 相比，Graph API 版本的推出步伐和編號方式不盡相同。所有 Facebook SDK 均支援與我們不同版本的 API 互動。多個不同版本的 API 或 SDK 可同時存在，而每個版本的功能均有所不同。

Graph API 的最新版本是什麼？

最新版本 Graph API 為： v21.0

為什麼我們需要使用不同版本？

我們之所以會使用版本控制，是為了讓建立應用程式的開發人員能夠提前了解 API 或 SDK 的變更。不同版本除了有助於網頁開發外，對流動應用程式的開發亦至關重要，因為透過手機使用應用程式的用戶可能很久才會升級一次，甚至從不升級。

每個版本由發佈日期起將保留最少 2 年，因此可為您提供固定的時間線，讓您了解應用程式將可繼續運行多久，以及您有多少時間將之更新至較新版本。

版本時間表

每個版本將會運行最少兩年。原有版本在新版發佈日期的兩年後便不再可用。例如，如果 API v2.3 版在 2015 年 3 月 25 日發佈，而 API v2.4 版在 2015 年 8 月 7 日發佈，則 v2.3 版將在 v2.4 版發佈的兩年後（即 2017 年 8 月 7 日）到期。

一旦某個 API 版本不再可用，任何向其執行的呼叫會預設傳至下一個最早的可用版本。以下是時間線範例：

至於 SDK，由於其性質為可下載套件，所以各個版本都將保持可用。可是，SDK 所依賴的 API 或方法可能不再運行，所以您可將生命週期結束後的 SDK 視為不再有效。

您可以參閱我們的變更記錄頁面，以了解有關版本時間線、變更和發佈日期的具體資訊。

版本中的所有內容是否會完全維持不變？

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 擁有專屬的版本控制架構，其版本編號及時間表與 Graph API 有所不同。

進一步了解推廣 API 版本控制

執行指定版本要求

Graph API

您可以透過指定版本路徑使用大部分 Graph API 端點，無論是屬於核心還是擴展群組亦然。請參閱我們的 Graph API 快速入門指南，查看當中有關使用 Graph API 版本的完整指南。

對話框

指定版本路徑不僅適用於 API 端點，同時也適用於對話框和社交附加程式。例如，如果您想為網頁應用程式產生 Facebook 登入對話框，您可以為產生對話框的端點加入版本編號前綴：

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

社交附加程式

如果您使用我們社交附加程式的 HTML5 或 xfbml 版本，系統所顯示的版本將視乎您初始化 JavaScript SDK 時指定的版本而定。

如果您插入我們附加程式的 iframe 或普通連結版本，則需要在附加程式的來源路徑加入版本編號前綴：

<iframe
  src="//www.facebook.com/v21.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 版 Facebook SDK、Android 版 Facebook SDK 或 Facebook JavaScript SDK，系統一般會自動為您執行版本控制呼叫。請注意，這有別於每個 SDK 的專屬版本控制系統。

JavaScript

如果您使用 sdk.js 路徑，JavaScript SDK 只能使用不同的 API 版本。

如果您使用 JavaScript SDK 中的 FB.init()，您需要使用版本參數，例如：

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

如果您一開始就設定了版本標示，則任何向 FB.api() 執行的呼叫會自動為呼叫的路徑加入版本編號前綴。這也適用於任何被呼叫的 Facebook 登入對話框。您將會獲得該版本 API 的 Facebook 登入對話框。

如有需要，您只需為 FB.api() 呼叫中的端點路徑加入版本編號前綴，即可覆寫版本。

iOS

每個已發佈的 iOS 版 Facebook SDK 版本都會與發佈當日可用的版本建立聯繫。換句話說，當您升級至新的 SDK 時，您還可以升級至最新的 API 版本（不過您亦可以使用 [FBSDKGraphRequest initWithGraphPath] 手動指定更早的可用 API 版本）。發佈每個 iOS 版 Facebook SDK 版本時，我們均會列出相關的 API 版本。

與 JavaScript SDK 類似，當您使用 iOS 版 Facebook SDK 向 Graph 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 版 Facebook SDK 版本都會與發佈當日可用的版本建立聯繫。換句話說，當您升級至新的 SDK 時，您還可以升級至最新的 API 版本（不過您亦可以使用 GraphRequest.setVersion() 手動指定更早的可用 API 版本）。發佈每個 Android 版 Facebook SDK 版本時，我們均會列出相關的 API 版本。

與 JavaScript SDK 類似，當您使用 Android 版 Facebook SDK 向 Graph 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() 覆寫呼叫的版本。